always

Creates a function that always returns returnValue.

always(returnValue: T): T
Parameters
returnValue (T)
Returns
T:
Example
const alwaysBlue = always('blue');
alwaysBlue() === 'blue';

bind

Sets a function's this context. Similar to Function.prototype.bind.

bind
Parameters
operation (Function)
context (Object)
Returns
Function:
Example
bind(console.log, console);

both

Returns true if the results of arg applied to both condition1 and condition2 are truthy.

both
Parameters
condition1 (Function)
condition2 (Function)
Returns
boolean:
Example
const isOneToTen = both(
  n => n >= 1,
  n => n <= 10
);

isOneToTen(3) === true;
isOneToTen(11) === false;

clear

Returns an empty copy of subject.

clear
Parameters
subject ((Array | Collection | Object))
Returns
(Array | Collection | Object):
Example
clear([1, 2, 3]) // returns []
clear(List.of(1, 2, 3)) // returns List []
clear({one: 1, two: 2, three: 3}) // returns {}

compose

Create a function that runs operations from right-to-left.

compose is not curried.

compose(operations: Array<Function>): Function
Parameters
operations (Array<Function>) any number of unary functions.
Returns
Function:
Example
const doubleAndTakeEvens = pipe(
  filter(n => n % 2 === 0),
  map(n => n * 2)
);

doubleAndTakeEvens(List.of(1, 2, 3))
// returns List [ 2, 4, 6 ]

count

Returns the number of values in subject.

count
Parameters
subject (TYPE)
Returns
number:
Example
count(List.of(1, 2, 3)) === 3;

curry

Creates a curried version of operation.

curry(operation: Function): Function
Parameters
operation (Function)
Returns
Function:
Example
const toArray = curry((a, b, c) => [a, b, c]);
const toArrayWith1 = toArray(1);
toArrayWith1(2, 3) === [1, 2, 3];

curryN

Create a curried version of operation that expects arity arguments. Inception-ally, curryN is also curried.

curryN
Parameters
arity (number) number of arguments the curried function accepts
operation (Function) to curry
Returns
Function:
Example
const toArray = curryN(3)((...args) => [...args]);
toArray(1, 2, 3) === [1, 2, 3];

debounce

operation is called interval milliseconds after the most recent call.

debounce
Parameters
interval (number) of milliseconds
operation (Function)
Returns
any: the most recent result of operation

debounceImmediate

operation is called immediately and then interval milliseconds after the most recent call.

debounceImmediate
Parameters
interval (number) of milliseconds
operation (Function)
Returns
any: the most recent result of operation

difference

Take the difference between one iterable and another iterable. Only the elements present in just subject will remain.

difference
Parameters
toRemove (Iterable)
subject (Iterable)
Returns
Iterable:
Example
const removeOne = difference(Set.of(1));

removeOne(Set.of(1, 2, 3)) // returns Set { 2, 3 }

either

Returns true if the results of arg applied to either first or second are truthy.

either
Parameters
first (Function)
second (Function)
subject (any)
Returns
boolean:
Example
const oneOrTwo = either(
  n => n === 1,
  n => n === 2
);

oneOrTwo(1) === true;
oneOrTwo(2) === true;
oneOrTwo(3) === false;

entrySeq

Get a Seq of the entries (i.e. [key, value] tuples) in subject.

entrySeq
Parameters
subject ((Array | Iterable | Object))
Returns
Seq:
Example
entrySeq(Map({one: 1, two: 2}))
// returns Seq [ ['one', 1], ['two', 2] ]

every

Returns true if all items in subject match predicate.

every
Parameters
predicate (Function) returns true if item is a match.
subject (Iterable)
Returns
bool:
Example
const alwaysBlue = every(v => v === 'blue');

alwaysBlue(List.of('blue', 'blue')) === true;
alwaysBlue(List.of('red', 'blue')) === false;

filter

Remove values for which predicate returns false.

filter
Parameters
predicate (Function) returns true if a value should be included.
subject (Iterable) to filter.
Returns
Iterable: without values that didn't match predicate .
Example
// returns List [ 2 ]
filter(
  (n) => n % 2 === 0,
  List.of(1, 2, 3)
);

Records have a fixed set of keys, so filter returns a Map instead.

// returns Map { 'one' => 1, 'three' => 3 }
filter(
  (n) => n % 2 === 0,
  ThreeRecord({one: 1, two: 2, three: 3})
);

filterNot

Remove values for which predicate returns true.

filterNot
Parameters
predicate (Function) returns true if a value should be excluded.
subject (Iterable) to filter.
Returns
Iterable: without values that matched predicate .
Example
// returns List [ 1, 3 ]
filterNot(
  (n) => n % 2 === 0,
  List.of(1, 2, 3)
);

flatten

Flattens an iterable as deeply as possible.

flatten(subject: Iterable): Iterable
Parameters
subject (Iterable)
Returns
Iterable:
Example
// return List [ 1, 2, 3, 4, 5, 6 ]
flatten(List.of(List.of(1, List.of(2, 3)), List.of(4, 5, 6)));

flattenN

Flattens an iterable depth levels.

flattenN
Parameters
depth (number)
subject (Iterable)
Returns
Iterable:
Example
// return List [ 1, List [ 2, 3 ], 4, 5, 6 ]
flattenN(1, List.of(List.of(1, List.of(2, 3)), List.of(4, 5, 6)));

forEach

Executes effect for each value in subject, then returns subject.

forEach
Parameters
effect (Function)
subject (TYPE)
Returns
TYPE:
Example
forEach(
  v => console.log(v),
  Map({ one: 1, two: 2, three: 3 })
);

// prints...
// 1
// 2
// 3

fromJS

A version of Immutable.fromJS that drops all but the first argument for compatibility with other transmute functions like map.

fromJS(json: any): Iterable?
Parameters
json (any)
Returns
Iterable?:
Example
fromJS({items: [1, 2, 3]})
// returns Map { items: List [ 1, 2, 3 ] }

get

Retrieve the value at key from subject.

get
Parameters
key (any) to lookup in subject .
subject ((Iterable | Object)) in which to look up key .
Returns
any: the value at key .
Example
// returns 1
get('one', Map({one: 1, two: 2, three: 3}))

getIn

Retrieve a keyPath from a nested Immutable or JS structure.

getIn short circuts when it encounters a null or undefined value.

getIn
Parameters
keyPath (Array<string>)
subject ((Array | Iterable | Object))
Returns
any:
Example
const getFirstName = getIn(['name', 'first']);
const user = UserRecord({
  name: Map({
    first: 'Test',
    last: 'Testerson',
  }),
});
getFirstName(user) === 'Test'

has

Returns true if key exists in subject.

has
Parameters
key (any)
subject ((Array | Iterable | Object))
Returns
boolean:
Example
const hasOne = has('one');

hasOne({one: 1}) === true;
hasOne(Map({two: 2})) === false;

hasIn

Returns true if keyPath is defined in a nested data structure.

hasIn short circuts and returns false when it encounters a null or undefined value.

hasIn
Parameters
keyPath (Array<string>)
subject ((Array | Iterable | Object))
Returns
boolean:
Example
const hasFirstName = hasIn(['name', 'first']);
const user = UserRecord({
  name: Map({
    first: 'Test',
    last: 'Testerson',
  }),
});
hasFirstName(user) === true

identity

Returns it's first argument.

identity(thing: any): any
Parameters
thing (any)
Returns
any:
Example
identity('something') === 'something'

ifElse

Applies affirmative to subject if predicate(subject) is truthy. Otherwise applies negative to subject.

ifElse
Parameters
predicate (Function)
affirmative (Function)
negative (Function)
subject (any)
Returns
any:
Example
const incrementAwayFromZero = ifElse(
  n => n >= 0,
  n => n + 1,
  n => n - 1
);

incrementAwayFromZero(1) === 2
incrementAwayFromZero(-1) === -2

ifThen

Applies affirmative to subject if predicate(subject) is truthy. Otherwise returns subject.

ifThen
Parameters
predicate (Function)
affirmative (Function)
subject (any)
Returns
any:
Example
import ifThen from 'transmute/ifThen';

const toJS = ifThen(
  subject => typeof subject.toJS === 'function',
  subject => subject.toJS
);

toJS(List.of(1, 2, 3)) //=> [1, 2, 3]
toJS([1, 2, 3]) //=> [1, 2, 3]

indexBy

Create a Map, or OrderedMap from subject with a key for each item returned by keyMapper.

indexBy
Parameters
keyMapper (Function) generates keys for each item
subject (Iterable) to index
Returns
KeyedIterable:
Example
indexBy(get('id'), List.of({id: 123}, {id: 456}))
// returns Map { 123: {id: 123}, 456: {id: 456} }

keySeq

Get a Seq of the keys in subject.

keySeq
Parameters
subject ((Iterable | Object | Array))
Returns
Seq:
Example
keySeq({one: 1, two: 2, three: 3})
// returns Seq [ 'one', 'two', 'three' ]

map

Create a new Iterable by applying mapper to each item in subject.

map
Parameters
mapper (Function) applied to each item in subject .
subject (Iterable) the Iterable to map.
Returns
Iterable: with each value of subject updated with mapper.
Example
// returns List [ 2, 3, 4 ]
map(
  (val) => val + 1,
  List.of(1, 2, 3)
);

reduce

Transform the contents of subject to into by applying operation to each item.

reduce
Parameters
into (any)
operation (Function)
subject (Iterable) [ description ]
Returns
Iterable:
Example
reduce(
  List(),
  (acc, val) => acc.push(val),
  Map({ one: 1, two: 2, three: 3 })
);
// returns List [ 1, 2, 3 ]

set

Returns a copy of subject with key set to value.

set
Parameters
key (any)
value (any)
subject ((Array | Iterable | Object))
Returns
(Array | Iterable | Object):
Example
set('one', 2, {one: 1});
// returns {one: 2}

some

Returns true if any items in subject match predicate.

some
Parameters
predicate (Function) returns true if item is a match.
subject (Iterable)
Returns
bool:
Example
const anyBlue = some(v => v === 'blue');

anyBlue(List.of('blue', 'red')) === true;
anyBlue(List.of('red', 'red')) === true;

sortBy

Sort subject according to the value returned by getSortValue.

sortBy
Parameters
getSortValue (Function) returns a value to sort on for each item in subject .
subject ((Array | Iterable | Object)) the thing to sort.
Returns
Iterable: an ordered version of subject (e.g. sorting a Map returns an OrderedMap ).
Example
// returns List [ 2, 1, 3 ]
sortBy(
  (n) => n % 2,
  List.of(1, 2, 3)
);
// returns OrderedMap { "one" => 1, "two" => 2, "three" => 3 }
sortBy(
  (n) => n % 2,
  Map({three: 3, one: 1, two: 2})
);

valueSeq

Get a Seq of the values in subject.

valueSeq
Parameters
subject ((Iterable | Object | Array))
Returns
Seq:
Example
valueSeq(Map({ one: 1, two: 2, three: 3 }))
// returns Seq [ 1, 2, 3 ]

isArray

Returns true if value is an Array.

isArray(value: any): boolean
Parameters
value (any)
Returns
boolean:

isEmpty

Returns true if value is "empty". If given null, undefined, isEmpty will return true.

isEmpty(value: any): boolean
Parameters
value (any)
Returns
boolean:

isFunction

Returns true if value is a Function.

isFunction(value: any): boolean
Parameters
value (any)
Returns
boolean:

isInstanceOf

Returns true if value is an instance of Constructor.

isInstanceOf
Parameters
Constructor (Function)
value (any)
Returns
boolean:

isNull

Returns true if subject is null.

isNull(subject: any): boolean
Parameters
subject (any)
Returns
boolean:

isNumber

Returns true if subject is a JavaScript Number and not NaN.

isNumber(value: any): boolean
Parameters
value (any)
Returns
boolean:

isObject

Returns true if value is an Object.

isObject(value: any): boolean
Parameters
value (any)
Returns
boolean:

isRecord

Returns true if subject is an instance of a Record.

isRecord(subject: any): boolean
Parameters
subject (any)
Returns
boolean:

isString

Returns true if value is a String.

isString(value: any): boolean
Parameters
value (any)
Returns
boolean:

isUndefined

Returns true if subject is undefined.

isUndefined(subject: any): boolean
Parameters
subject (any)
Returns
boolean:

mapKeys

Like map but transforms an Iterable's keys rather than its values.

mapKeys
Parameters
keyMapper (Function) returns a new key
subject (KeyedIterable)
Returns
KeyedIterable:
Example

Can be useful for converting keys of API results to a common type.

import { mapKeys, toString } from 'transmute';
const stringifyKeys = mapKeys(toString);
const m = Map.of(123, Map(), 456, Map(), 789, Map());
stringifyKeys(m).equals(Map.of('123', Map(), '456', Map(), '789', Map()));

match

Returns true if the key => value pairs in pattern match the correspoding key => value pairs in subject.

match
Parameters
pattern ((Array | Iterable | Object))
subject ((Array | Iterable | Object))
Returns
boolean:
Example
const hasOneAndThree = match({one: 1, three: 3});
hasOneAndThree(Map({one: 1, two: 2, three: 3})) === true;

memoize

Memoizer that uses a Map to allow for arbitrarily many/complex keys.

memoize(operation: Function, hashFunction: Function): Function
Parameters
operation (Function) to memoize.
hashFunction (Function = defaultHashFunction) that generates the cache key.
Returns
Function: memoized version of operation .
Example
const sum = memoize((list) => {
  return list.reduce((total, n) => total + n, 0);
});
// does work and returns 15
sum(List.of(1, 2, 3, 4, 5))
// returns 15 but does no work
sum(List.of(1, 2, 3, 4, 5))

We can use the hashFunction param to customize the key used in the cache.

const sum = memoize(
  (list) => list.reduce((total, n) => total + n, 0),
  (list) => return list.join('-')
);

It's also possible to inspect the state of an instance by reading the .cache property.

const sum = memoize(...);
Map.isMap(sum.cache) === true;

memoizeLast

Like memoize, but only caches the most recent value. It's often useful for caching expensive calculations in react components.

memoizeLast(operation: Function): Function
Parameters
operation (Function)
Returns
Function:
Example
const sum = memoizeLast((...nums) => nums.reduce((acc, n) => acc + n));
sum(List.of(1, 2, 3))
//> does work, returns 6
sum(List.of(1, 2, 3))
//> takes cached value, returns 6
sum(List.of(4, 5, 6))
//> does work, returns 15
sum(List.of(1, 2, 3))
//> does work again, returns 6

merge

Takes each entry of updates and sets it on subject.

merge
Parameters
updates (Iterable) key-value pairs to merge in subject .
subject (Iterable) the thing to update.
Returns
Iterable: with each key-value of updates merged into subject .
Example
// returns Map { "one" => 3, "two" => 2, "three" => 1}
merge(
  Map({one: 1, two: 2, three: 3}),
  Map({one: 3, three: 1})
);

omit

Drop specified keys from a KeyedIterable (e.g. a Map or OrderedMap).

omit
Parameters
keys (Array<any>) to remove.
subject (KeyedIterable) from which to remove keys .
Returns
KeyedIterable: without keys .
Example
// returns Map { "two" => 2 }
omit(
  ['one', 'three'],
  Map({one: 1, two: 2, three: 3})
);

once

fn is only run one time.

once(fn: Function): any
Parameters
fn (Function)
Returns
any: the result of the first time fn was called

partial

Like fn.bind(), but without the option to pass context.

partial is not curried.

const add = (a, b, c) => a + b + c; const add11 = partial(add, 5, 6); add11(7); // returns 18

partial(operation: Function, first: any, args: ...any): Function
Parameters
operation (Function) the function to bind.
first (any) the first argument to pass to operation
args (...any)
Returns
Function:

partialApply

Like transmute/partial, but takes an Array or Iterable of arguments to pass to operation rather than a dynamic number of args. Unlike partial it is curried.

partial : partialApply :: Function.prototype.call : Function.prototype.apply

partialApply
Parameters
operation (Function) the function to bind.
args ((Array | Iterable)) ordered collection of arguments to bind to fn .
Returns
Function:
Example
const add = (a, b, c) => a + b + c;
const add11 = partialApply(add, [5, 6]);
add11(7); // returns 18

pick

Select specified keys from a KeyedIterable (e.g. a Map or OrderedMap).

pick
Parameters
keys ((Array | Iterable | Object)) to select.
subject (KeyedIterable) from which to select keys .
Returns
KeyedIterable: with just keys .
Example
// returns Map { "one" => 1, "three" => 3 }
pick(
  ['one', 'three'],
  Map({one: 1, two: 2, three: 3})
);

pipe

Create a function that runs operations from left-to-right.

pipe is not curried.

pipe(operations: Array<Function>): Function
Parameters
operations (Array<Function>) any number of unary functions.
Returns
Function:
Example
const takeEvensAndDouble = pipe(
  filter(n => n % 2 === 0),
  map(n => n * 2)
);

takeEvensAndDouble(List.of(1, 2, 3))
// returns List [ 4 ]

pluck

Select key from each item in subject.

pluck
Parameters
key (any)
subject (Iterable)
Returns
Iterable:
Example
const pluckName = pluck('name');
pluckName(userMap) === Map({123: 'Testing'});

setArity

Creates a function identical to operation but with length arity.

setArity
Parameters
arity (number) from 0 to 9
operation (Function)
Returns
Function:
Example
const op = (...args) => args;
op.length === 0;

const twoArgOp = setArity(2, op);
twoArgOp.length === 2;

setIn

Set the value at keyPath in a nested structure.

setIn
Parameters
keyPath ((Array<any> | Iterable<any>))
value (any)
subject ((Array | Iterable | Object))
Example
setIn(['one', 'two'], 3, {one: {two: 2}});
// returns {one: {two: 3}}

Unset keyPaths will be set based on the most recent type.

setIn(['one', 'two'], 3, {});
// returns {one: {two: 3}}

setIn(['one', 'two'], 3, Map());
// returns Map { one => Map { two => 3 } }

throttle

Ensures operation is only called once every interval milliseconds.

throttle
Parameters
interval (number) of milliseconds
operation (Function)
Returns
any: the most recent result of operation

toJS

Converts an Iterable to a native JS structure.

toJS(subject: Iterable): (Array | Object)
Parameters
subject (Iterable) to convert.
Returns
(Array | Object): native JS requivalent of subject .

toSeq

Converts subject to a Seq if possible.

toSeq(subject: (Array | Iterable | Object | String)): Seq
Parameters
subject ((Array | Iterable | Object | String))
Returns
Seq:

toString

Returns the value converted to a string.

toString(value: any)
Parameters
value (any)

uniqueId

Returns a unique integer string appended to prefix.

uniqueId(prefix: string)
Parameters
prefix (string = '')
Example
uniqueId('test-') === 'test-1';
uniqueId('other-') === 'other-2';
uniqueId('test-') === 'test-3';

update

Sets the value at key to the result of updater.

update
Parameters
key (any)
updater (Function)
subject ((Array | Iterable | Object))
Returns
(Array | Iterable | Object):
Example
const incrementCount = update('count', n => n + 1);
incrementCount({count: 1});
// returns {count: 2}

updateIn

Apply updater to the value at keyPath.

updateIn
Parameters
keyPath ((Array<any> | Iterable<any>)) the location where updater should be applied.
updater (Function) the tranformation to apply.
subject ((Array | Iterable | Object)) the thing to update.
Returns
(Array | Iterable | Object):
Example
const incrementUserCount = updateIn(['users', 'count'], n => n + 1);
incrementUserCount({users: {count: 1}});
// returns {users: {count: 2}}

Unset keyPaths will be set based on the most recent type.

const incrementUserCount = updateIn(['users', 'count'], (n = 0) => n + 1);
incrementUserCount({});
// returns {users: {count: 1}}

incrementUserCount(Map());
// returns Map { users => Map { count => 1 } }

where

Takes items in subject that match pattern.

where
Parameters
pattern (Function)
subject (Iterable)
Returns
Iterable:
Example
const users = Map({
  123: {id: '123', name: 'Jack'},
  456: {id: '456', name: 'Jill'},
});

where({name: 'Jack'}, users);
// returns Map { 123: {id: '123', name: 'Jack'} }

without

Removes values in unwanted from subject.

without
Parameters
unwanted (Iterable)
subject (Iterable)
Returns
Iterable:
Example
const removeOne = without(Set.of(1));

removeOne(Set.of(1, 2, 3)) // returns Set { 2, 3 }