2.0.2
Creates a function that always returns returnValue
.
(T)
T
:
const alwaysBlue = always('blue');
alwaysBlue() === 'blue';
Sets a function's this
context. Similar to Function.prototype.bind
.
Function
:
bind(console.log, console);
Returns true
if the results of arg
applied to both condition1
and
condition2
are truthy.
boolean
:
const isOneToTen = both(
n => n >= 1,
n => n <= 10
);
isOneToTen(3) === true;
isOneToTen(11) === false;
Returns an empty copy of subject
.
(Array | Collection | Object)
:
clear([1, 2, 3]) // returns []
clear(List.of(1, 2, 3)) // returns List []
clear({one: 1, two: 2, three: 3}) // returns {}
Create a function that runs operations from right-to-left.
compose
is not curried.
Function
:
const doubleAndTakeEvens = pipe(
filter(n => n % 2 === 0),
map(n => n * 2)
);
doubleAndTakeEvens(List.of(1, 2, 3))
// returns List [ 2, 4, 6 ]
Returns the number of values in subject
.
(TYPE)
number
:
count(List.of(1, 2, 3)) === 3;
Creates a curried version of operation
.
(Function)
Function
:
const toArray = curry((a, b, c) => [a, b, c]);
const toArrayWith1 = toArray(1);
toArrayWith1(2, 3) === [1, 2, 3];
Create a curried version of operation
that expects arity
arguments.
Inception-ally, curryN
is also curried.
Function
:
const toArray = curryN(3)((...args) => [...args]);
toArray(1, 2, 3) === [1, 2, 3];
operation
is called interval
milliseconds after the most recent call.
any
:
the most recent result of
operation
operation
is called immediately and then interval
milliseconds after the most
recent call.
any
:
the most recent result of
operation
Take the difference between one iterable and another iterable. Only the elements present in just subject will remain.
(Iterable)
(Iterable)
Iterable
:
const removeOne = difference(Set.of(1));
removeOne(Set.of(1, 2, 3)) // returns Set { 2, 3 }
Returns true if the results of arg
applied to either first
or second
are truthy.
boolean
:
const oneOrTwo = either(
n => n === 1,
n => n === 2
);
oneOrTwo(1) === true;
oneOrTwo(2) === true;
oneOrTwo(3) === false;
Get a Seq of the entries (i.e. [key, value] tuples) in subject
.
Seq
:
entrySeq(Map({one: 1, two: 2}))
// returns Seq [ ['one', 1], ['two', 2] ]
Returns true
if all items in subject
match predicate
.
(Iterable)
bool
:
const alwaysBlue = every(v => v === 'blue');
alwaysBlue(List.of('blue', 'blue')) === true;
alwaysBlue(List.of('red', 'blue')) === false;
Remove values for which predicate
returns false
.
(Iterable)
to filter.
Iterable
:
without values that didn't match
predicate
.
// returns List [ 2 ]
filter(
(n) => n % 2 === 0,
List.of(1, 2, 3)
);
Record
s 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})
);
Remove values for which predicate
returns true
.
(Iterable)
to filter.
Iterable
:
without values that matched
predicate
.
// returns List [ 1, 3 ]
filterNot(
(n) => n % 2 === 0,
List.of(1, 2, 3)
);
Flattens an iterable as deeply as possible.
(Iterable)
Iterable
:
// return List [ 1, 2, 3, 4, 5, 6 ]
flatten(List.of(List.of(1, List.of(2, 3)), List.of(4, 5, 6)));
Flattens an iterable depth
levels.
(number)
(Iterable)
Iterable
:
// 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)));
Executes effect
for each value in subject
, then returns subject
.
(Function)
(TYPE)
TYPE
:
forEach(
v => console.log(v),
Map({ one: 1, two: 2, three: 3 })
);
// prints...
// 1
// 2
// 3
A version of Immutable.fromJS that drops all but the first argument for
compatibility with other transmute functions like map
.
(any)
Iterable?
:
fromJS({items: [1, 2, 3]})
// returns Map { items: List [ 1, 2, 3 ] }
Retrieve the value at key
from subject
.
(any)
to lookup in
subject
.
any
:
the value at
key
.
// returns 1
get('one', Map({one: 1, two: 2, three: 3}))
Retrieve a keyPath
from a nested Immutable or JS structure.
getIn
short circuts when it encounters a null
or undefined
value.
any
:
const getFirstName = getIn(['name', 'first']);
const user = UserRecord({
name: Map({
first: 'Test',
last: 'Testerson',
}),
});
getFirstName(user) === 'Test'
Returns true
if key
exists in subject
.
boolean
:
const hasOne = has('one');
hasOne({one: 1}) === true;
hasOne(Map({two: 2})) === false;
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.
boolean
:
const hasFirstName = hasIn(['name', 'first']);
const user = UserRecord({
name: Map({
first: 'Test',
last: 'Testerson',
}),
});
hasFirstName(user) === true
Returns it's first argument.
(any)
any
:
identity('something') === 'something'
Applies affirmative
to subject
if predicate(subject)
is truthy.
Otherwise applies negative
to subject
.
any
:
const incrementAwayFromZero = ifElse(
n => n >= 0,
n => n + 1,
n => n - 1
);
incrementAwayFromZero(1) === 2
incrementAwayFromZero(-1) === -2
Applies affirmative
to subject
if predicate(subject)
is truthy.
Otherwise returns subject
.
any
:
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]
Create a Map, or OrderedMap from subject
with a key for each item
returned by keyMapper
.
(Function)
generates keys for each item
(Iterable)
to index
KeyedIterable
:
indexBy(get('id'), List.of({id: 123}, {id: 456}))
// returns Map { 123: {id: 123}, 456: {id: 456} }
Get a Seq of the keys in subject
.
Seq
:
keySeq({one: 1, two: 2, three: 3})
// returns Seq [ 'one', 'two', 'three' ]
Create a new Iterable by applying mapper
to each item in subject
.
(Iterable)
the Iterable to map.
Iterable
:
with each value of
subject
updated with mapper.
// returns List [ 2, 3, 4 ]
map(
(val) => val + 1,
List.of(1, 2, 3)
);
Transform the contents of subject
to into
by applying operation
to each
item.
Iterable
:
reduce(
List(),
(acc, val) => acc.push(val),
Map({ one: 1, two: 2, three: 3 })
);
// returns List [ 1, 2, 3 ]
Returns a copy of subject
with key
set to value
.
(Array | Iterable | Object)
:
set('one', 2, {one: 1});
// returns {one: 2}
Returns true
if any items in subject
match predicate
.
(Iterable)
bool
:
const anyBlue = some(v => v === 'blue');
anyBlue(List.of('blue', 'red')) === true;
anyBlue(List.of('red', 'red')) === true;
Sort subject
according to the value returned by getSortValue
.
Iterable
:
an ordered version of
subject
(e.g. sorting a
Map
returns an
OrderedMap
).
// 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})
);
Get a Seq of the values in subject
.
Seq
:
valueSeq(Map({ one: 1, two: 2, three: 3 }))
// returns Seq [ 1, 2, 3 ]
Returns true
if value is an Array.
(any)
boolean
:
Returns true if value
is "empty".
If given null, undefined, isEmpty will return true.
(any)
boolean
:
Returns true if value
is a Function.
(any)
boolean
:
Returns true if value
is an instance of Constructor
.
(Function)
(any)
boolean
:
Returns true
if subject
is null
.
(any)
boolean
:
Returns true
if subject
is a JavaScript Number and not NaN
.
(any)
boolean
:
Returns true if value
is an Object.
(any)
boolean
:
Returns true
if subject
is an instance of a Record.
(any)
boolean
:
Returns true if value
is a String.
(any)
boolean
:
Returns true
if subject
is undefined
.
(any)
boolean
:
Like map
but transforms an Iterable's keys rather than its values.
(Function)
returns a new key
(KeyedIterable)
KeyedIterable
:
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()));
Returns true
if the key => value pairs in pattern
match the correspoding key => value pairs in subject
.
boolean
:
const hasOneAndThree = match({one: 1, three: 3});
hasOneAndThree(Map({one: 1, two: 2, three: 3})) === true;
Memoizer that uses a Map
to allow for arbitrarily many/complex keys.
(Function)
to memoize.
(Function
= defaultHashFunction
)
that generates the cache key.
Function
:
memoized version of
operation
.
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;
Like memoize, but only caches the most recent value. It's often useful for caching expensive calculations in react components.
(Function)
Function
:
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
Takes each entry of updates
and sets it on subject
.
(Iterable)
key-value pairs to merge in
subject
.
(Iterable)
the thing to update.
Iterable
:
with each key-value of
updates
merged into
subject
.
// returns Map { "one" => 3, "two" => 2, "three" => 1}
merge(
Map({one: 1, two: 2, three: 3}),
Map({one: 3, three: 1})
);
Drop specified keys from a KeyedIterable (e.g. a Map
or OrderedMap
).
(Array<any>)
to remove.
(KeyedIterable)
from which to remove
keys
.
KeyedIterable
:
without
keys
.
// returns Map { "two" => 2 }
omit(
['one', 'three'],
Map({one: 1, two: 2, three: 3})
);
fn
is only run one time.
(Function)
any
:
the result of the first time
fn
was called
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
(Function)
the function to bind.
(any)
the first argument to pass to
operation
(...any)
Function
:
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
(Function)
the function to bind.
Function
:
const add = (a, b, c) => a + b + c;
const add11 = partialApply(add, [5, 6]);
add11(7); // returns 18
Select specified keys from a KeyedIterable (e.g. a Map
or OrderedMap
).
KeyedIterable
:
with just
keys
.
// returns Map { "one" => 1, "three" => 3 }
pick(
['one', 'three'],
Map({one: 1, two: 2, three: 3})
);
Create a function that runs operations from left-to-right.
pipe
is not curried.
Function
:
const takeEvensAndDouble = pipe(
filter(n => n % 2 === 0),
map(n => n * 2)
);
takeEvensAndDouble(List.of(1, 2, 3))
// returns List [ 4 ]
Select key
from each item in subject
.
(any)
(Iterable)
Iterable
:
const pluckName = pluck('name');
pluckName(userMap) === Map({123: 'Testing'});
Creates a function identical to operation
but with length arity
.
Function
:
const op = (...args) => args;
op.length === 0;
const twoArgOp = setArity(2, op);
twoArgOp.length === 2;
Set the value
at keyPath
in a nested structure.
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 } }
Ensures operation
is only called once every interval
milliseconds.
any
:
the most recent result of
operation
Converts an Iterable to a native JS structure.
(Iterable)
to convert.
(Array | Object)
:
native JS requivalent of
subject
.
Converts subject
to a Seq
if possible.
Seq
:
Returns the value converted to a string.
(any)
Returns a unique integer string appended to prefix
.
(string
= ''
)
uniqueId('test-') === 'test-1';
uniqueId('other-') === 'other-2';
uniqueId('test-') === 'test-3';
Sets the value at key
to the result of updater
.
(Array | Iterable | Object)
:
const incrementCount = update('count', n => n + 1);
incrementCount({count: 1});
// returns {count: 2}
Apply updater
to the value at keyPath
.
(Function)
the tranformation to apply.
(Array | Iterable | Object)
:
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 } }
Takes items in subject
that match pattern
.
(Function)
(Iterable)
Iterable
:
const users = Map({
123: {id: '123', name: 'Jack'},
456: {id: '456', name: 'Jill'},
});
where({name: 'Jack'}, users);
// returns Map { 123: {id: '123', name: 'Jack'} }
Removes values in unwanted
from subject
.
(Iterable)
(Iterable)
Iterable
:
const removeOne = without(Set.of(1));
removeOne(Set.of(1, 2, 3)) // returns Set { 2, 3 }