Name: transmute
Owner: HubSpot
Description: kind of like lodash but works with Immutable
Created: 2017-05-26 20:08:11.0
Updated: 2018-03-23 22:42:30.0
Pushed: 2018-03-26 16:50:58.0
Homepage: http://github.hubspot.com/transmute/
Size: 1549
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
@hs/transmute provides convenient, composable functions for transforming Arrays, Immutable.js data structures, and Objects.
Transmute can be installed with npm or yarn.
npm install @hs/transmute
rt { Map } from 'immutable';
rt pick from 'transmute/pick';
eturns Map { one => 1, three => 3 }
(['one', 'three'], Map({one: 1, two: 2, three: 3}));
Most of the function (with the execption of some of the composition functions like compose and pipe) are curried to facilitate partial application. You might also notice that the argument order is the oposite of you'll find in other utility libraries. Passing the options and then the subject makes currying much more useful.
rt { Map } from 'immutable';
rt pick from 'transmute/pick';
t pickTwo = pick(['two']);
eturns Map { two => 2 }
Two(Map({one: 1, two: 2, three: 3}));
transmute also includes some helpful composition functions which are powerful when we combine them with curried transforms.
rt { Map, Set } from 'immutable';
rt * as t from 'transmute';
t setOfKeysWithEvenValues = t.pipe(
filter((val) => val % 2 === 0),
keySeq,
t
eturns Set { 'two', 'four' }
EvenValues(Map({one: 1, two: 2, three: 3, four: 4}));
Creates a function that always returns returnValue.
Parameters
returnValue TExamples
t alwaysBlue = always('blue');
ysBlue() === 'blue';
Returns T
Sets a function's this context. Similar to Function.prototype.bind.
Parameters
Examples
(console.log, console);
Returns Function
Returns true if the results of arg applied to both condition1 and
condition2 are truthy.
Parameters
Examples
t isOneToTen = both(
=> n >= 1,
=> n <= 10
eToTen(3) === true;
eToTen(11) === false;
Returns boolean
Returns an empty copy of subject.
Parameters
Examples
r([1, 2, 3]) // returns []
r(List.of(1, 2, 3)) // returns List []
r({one: 1, two: 2, three: 3}) // returns {}
Returns (Array | Collection | Object)
Create a function that runs operations from right-to-left.
compose is not curried.
Parameters
Examples
t doubleAndTakeEvens = pipe(
lter(n => n % 2 === 0),
p(n => n * 2)
leAndTakeEvens(List.of(1, 2, 3))
eturns List [ 2, 4, 6 ]
Returns Function
Returns the number of values in subject.
Parameters
subject TYPEExamples
t(List.of(1, 2, 3)) === 3;
Returns number
Creates a curried version of operation.
Parameters
operation FunctionExamples
t toArray = curry((a, b, c) => [a, b, c]);
t toArrayWith1 = toArray(1);
rayWith1(2, 3) === [1, 2, 3];
Returns Function
Create a curried version of operation that expects arity arguments.
Inception-ally, curryN is also curried.
Parameters
Examples
t toArray = curryN(3)((...args) => [...args]);
ray(1, 2, 3) === [1, 2, 3];
Returns Function
operation is called interval milliseconds after the most recent call.
Parameters
Returns any the most recent result of operation
src/debounceImmediate.js:52-52
operation is called immediately and then interval milliseconds after the most
recent call.
Parameters
Returns 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.
Parameters
toRemove Iterablesubject IterableExamples
t removeOne = difference(Set.of(1));
veOne(Set.of(1, 2, 3)) // returns Set { 2, 3 }
Returns Iterable
Returns true if the results of arg applied to either first or second
are truthy.
Parameters
Examples
t oneOrTwo = either(
=> n === 1,
=> n === 2
rTwo(1) === true;
rTwo(2) === true;
rTwo(3) === false;
Returns boolean
Get a Seq of the entries (i.e. [key, value] tuples) in subject.
Parameters
Examples
ySeq(Map({one: 1, two: 2}))
eturns Seq [ ['one', 1], ['two', 2] ]
Returns Seq
Returns true if all items in subject match predicate.
Parameters
predicate Function returns true if item is a match.subject IterableExamples
t alwaysBlue = every(v => v === 'blue');
ysBlue(List.of('blue', 'blue')) === true;
ysBlue(List.of('red', 'blue')) === false;
Returns bool
Remove values for which predicate returns false.
Parameters
predicate Function returns true if a value should be included.subject Iterable to filter.Examples
eturns List [ 2 ]
er(
) => n % 2 === 0,
st.of(1, 2, 3)
Records have a fixed set of keys, so filter returns a Map instead.
eturns Map { 'one' => 1, 'three' => 3 }
er(
) => n % 2 === 0,
reeRecord({one: 1, two: 2, three: 3})
Returns Iterable without values that didn't match predicate.
Remove values for which predicate returns true.
Parameters
predicate Function returns true if a value should be excluded.subject Iterable to filter.Examples
eturns List [ 1, 3 ]
erNot(
) => n % 2 === 0,
st.of(1, 2, 3)
Returns Iterable without values that matched predicate.
Flattens an iterable as deeply as possible.
Parameters
subject IterableExamples
eturn List [ 1, 2, 3, 4, 5, 6 ]
ten(List.of(List.of(1, List.of(2, 3)), List.of(4, 5, 6)));
Returns Iterable
Flattens an iterable depth levels.
Parameters
depth numbersubject IterableExamples
eturn List [ 1, List [ 2, 3 ], 4, 5, 6 ]
tenN(1, List.of(List.of(1, List.of(2, 3)), List.of(4, 5, 6)));
Returns Iterable
Executes effect for each value in subject, then returns subject.
Parameters
effect Functionsubject TYPEExamples
ach(
=> console.log(v),
p({ one: 1, two: 2, three: 3 })
rints...
Returns TYPE
A version of Immutable.fromJS that drops all but the first argument for
compatibility with other transmute functions like map.
Parameters
json anyExamples
JS({items: [1, 2, 3]})
eturns Map { items: List [ 1, 2, 3 ] }
Returns Iterable?
Retrieve the value at key from subject.
Parameters
key any to lookup in subject.subject (Iterable | Object) in which to look up key.Examples
eturns 1
'one', Map({one: 1, two: 2, three: 3}))
Returns any the value at key.
Retrieve a keyPath from a nested Immutable or JS structure.
getIn short circuts when it encounters a null or undefined value.
Parameters
Examples
t getFirstName = getIn(['name', 'first']);
t user = UserRecord({
me: Map({
first: 'Test',
last: 'Testerson',
,
irstName(user) === 'Test'
Returns any
Returns true if key exists in subject.
Parameters
Examples
t hasOne = has('one');
ne({one: 1}) === true;
ne(Map({two: 2})) === false;
Returns boolean
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.
Parameters
Examples
t hasFirstName = hasIn(['name', 'first']);
t user = UserRecord({
me: Map({
first: 'Test',
last: 'Testerson',
,
irstName(user) === true
Returns boolean
Returns it's first argument.
Parameters
thing anyExamples
tity('something') === 'something'
Returns any
Applies affirmative to subject if predicate(subject) is truthy.
Otherwise applies negative to subject.
Parameters
Examples
t incrementAwayFromZero = ifElse(
=> n >= 0,
=> n + 1,
=> n - 1
ementAwayFromZero(1) === 2
ementAwayFromZero(-1) === -2
Returns any
Applies affirmative to subject if predicate(subject) is truthy.
Otherwise returns subject.
Parameters
Examples
rt ifThen from 'transmute/ifThen';
t toJS = ifThen(
bject => typeof subject.toJS === 'function',
bject => subject.toJS
(List.of(1, 2, 3)) //=> [1, 2, 3]
([1, 2, 3]) //=> [1, 2, 3]
Returns any
Create a Map, or OrderedMap from subject with a key for each item
returned by keyMapper.
Parameters
keyMapper Function generates keys for each itemsubject Iterable to indexExamples
xBy(get('id'), List.of({id: 123}, {id: 456}))
eturns Map { 123: {id: 123}, 456: {id: 456} }
Returns KeyedIterable
Get a Seq of the keys in subject.
Parameters
Examples
eq({one: 1, two: 2, three: 3})
eturns Seq [ 'one', 'two', 'three' ]
Returns Seq
Create a new Iterable by applying mapper to each item in subject.
Parameters
mapper Function applied to each item in subject.subject Iterable the Iterable to map.Examples
eturns List [ 2, 3, 4 ]
al) => val + 1,
st.of(1, 2, 3)
Returns Iterable with each value of subject updated with mapper.
Transform the contents of subject to into by applying operation to each
item.
Parameters
into anyoperation Functionsubject Iterable [description]Examples
ce(
st(),
cc, val) => acc.push(val),
p({ one: 1, two: 2, three: 3 })
eturns List [ 1, 2, 3 ]
Returns Iterable
Returns a copy of subject with key set to value.
Parameters
Examples
'one', 2, {one: 1});
eturns {one: 2}
Returns (Array | Iterable | Object)
Returns true if any items in subject match predicate.
Parameters
predicate Function returns true if item is a match.subject IterableExamples
t anyBlue = some(v => v === 'blue');
lue(List.of('blue', 'red')) === true;
lue(List.of('red', 'red')) === true;
Returns bool
Sort subject according to the value returned by getSortValue.
Parameters
getSortValue Function returns a value to sort on for each item in subject.subject (Array | Iterable | Object) the thing to sort.Examples
eturns List [ 2, 1, 3 ]
By(
) => n % 2,
st.of(1, 2, 3)
avascript
eturns OrderedMap { "one" => 1, "two" => 2, "three" => 3 }
By(
) => n % 2,
p({three: 3, one: 1, two: 2})
Returns Iterable an ordered version of subject (e.g. sorting a Map returns an OrderedMap).
Get a Seq of the values in subject.
Parameters
Examples
eSeq(Map({ one: 1, two: 2, three: 3 }))
eturns Seq [ 1, 2, 3 ]
Returns Seq
Returns true if value is an Array.
Parameters
value anyReturns boolean
Returns true if value is “empty”.
If given null, undefined, isEmpty will return true.
Parameters
value anyReturns boolean
Returns true if value is a Function.
Parameters
value anyReturns boolean
Returns true if value is an instance of Constructor.
Parameters
Constructor Functionvalue anyReturns boolean
Returns true if subject is null.
Parameters
subject anyReturns boolean
Returns true if subject is a JavaScript Number and not NaN.
Parameters
value anyReturns boolean
Returns true if value is an Object.
Parameters
value anyReturns boolean
Returns true if subject is an instance of a Record.
Parameters
subject anyReturns boolean
Returns true if value is a String.
Parameters
value anyReturns boolean
Returns true if subject is undefined.
Parameters
subject anyReturns boolean
Like map but transforms an Iterable's keys rather than its values.
Parameters
keyMapper Function returns a new keysubject KeyedIterableExamples
Can be useful for converting keys of API results to a common type.
rt { mapKeys, toString } from 'transmute';
t stringifyKeys = mapKeys(toString);
t m = Map.of(123, Map(), 456, Map(), 789, Map());
ngifyKeys(m).equals(Map.of('123', Map(), '456', Map(), '789', Map()));
Returns KeyedIterable
Returns true if the key => value pairs in pattern match the correspoding key => value pairs in subject.
Parameters
Examples
t hasOneAndThree = match({one: 1, three: 3});
neAndThree(Map({one: 1, two: 2, three: 3})) === true;
Returns boolean
Memoizer that uses a Map to allow for arbitrarily many/complex keys.
Parameters
operation Function to memoize.hashFunction Function that generates the cache key. (optional, default defaultHashFunction)Examples
t sum = memoize((list) => {
turn list.reduce((total, n) => total + n, 0);
oes work and returns 15
List.of(1, 2, 3, 4, 5))
eturns 15 but does no work
List.of(1, 2, 3, 4, 5))
We can use the hashFunction param to customize the key used in the cache.
t sum = memoize(
ist) => list.reduce((total, n) => total + n, 0),
ist) => return list.join('-')
It's also possible to inspect the state of an instance by reading the .cache property.
t sum = memoize(...);
isMap(sum.cache) === true;
Returns Function memoized version of operation.
Like memoize, but only caches the most recent value. It's often useful for caching expensive calculations in react components.
Parameters
operation FunctionExamples
t sum = memoizeLast((...nums) => nums.reduce((acc, n) => acc + n));
List.of(1, 2, 3))
does work, returns 6
List.of(1, 2, 3))
takes cached value, returns 6
List.of(4, 5, 6))
does work, returns 15
List.of(1, 2, 3))
does work again, returns 6
Returns Function
Takes each entry of updates and sets it on subject.
Parameters
updates Iterable key-value pairs to merge in subject.subject Iterable the thing to update.Examples
eturns Map { "one" => 3, "two" => 2, "three" => 1}
e(
p({one: 1, two: 2, three: 3}),
p({one: 3, three: 1})
Returns Iterable with each key-value of updates merged into subject.
Drop specified keys from a KeyedIterable (e.g. a Map or OrderedMap).
Parameters
keys Array<any> to remove.subject KeyedIterable from which to remove keys.Examples
eturns Map { "two" => 2 }
(
one', 'three'],
p({one: 1, two: 2, three: 3})
Returns KeyedIterable without keys.
fn is only run one time.
Parameters
fn FunctionReturns 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
Parameters
operation Function the function to bind.first any the first argument to pass to operationargs …anyReturns 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
Parameters
operation Function the function to bind.args (Array | Iterable) ordered collection of arguments to bind to fn.Examples
t add = (a, b, c) => a + b + c;
t add11 = partialApply(add, [5, 6]);
1(7); // returns 18
Returns Function
Select specified keys from a KeyedIterable (e.g. a Map or OrderedMap).
Parameters
Examples
eturns Map { "one" => 1, "three" => 3 }
(
one', 'three'],
p({one: 1, two: 2, three: 3})
Returns KeyedIterable with just keys.
Create a function that runs operations from left-to-right.
pipe is not curried.
Parameters
Examples
t takeEvensAndDouble = pipe(
lter(n => n % 2 === 0),
p(n => n * 2)
EvensAndDouble(List.of(1, 2, 3))
eturns List [ 4 ]
Returns Function
Select key from each item in subject.
Parameters
key anysubject IterableExamples
t pluckName = pluck('name');
kName(userMap) === Map({123: 'Testing'});
Returns Iterable
Creates a function identical to operation but with length arity.
Parameters
Examples
t op = (...args) => args;
ength === 0;
t twoArgOp = setArity(2, op);
rgOp.length === 2;
Returns Function
Set the value at keyPath in a nested structure.
Parameters
Examples
n(['one', 'two'], 3, {one: {two: 2}});
eturns {one: {two: 3}}
Unset keyPaths will be set based on the most recent type.
n(['one', 'two'], 3, {});
eturns {one: {two: 3}}
n(['one', 'two'], 3, Map());
eturns Map { one => Map { two => 3 } }
Ensures operation is only called once every interval milliseconds.
Parameters
Returns any the most recent result of operation
Converts an Iterable to a native JS structure.
Parameters
subject Iterable to convert.Returns (Array \| Object) native JS requivalent of subject.
Converts subject to a Seq if possible.
Parameters
Returns Seq
Returns the value converted to a string.
Parameters
value anyReturns a unique integer string appended to prefix.
Parameters
prefix string (optional, default '')Examples
ueId('test-') === 'test-1';
ueId('other-') === 'other-2';
ueId('test-') === 'test-3';
Sets the value at key to the result of updater.
Parameters
Examples
t incrementCount = update('count', n => n + 1);
ementCount({count: 1});
eturns {count: 2}
Returns (Array | Iterable | Object)
Apply updater to the value at keyPath.
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.Examples
t incrementUserCount = updateIn(['users', 'count'], n => n + 1);
ementUserCount({users: {count: 1}});
eturns {users: {count: 2}}
Unset keyPaths will be set based on the most recent type.
t incrementUserCount = updateIn(['users', 'count'], (n = 0) => n + 1);
ementUserCount({});
eturns {users: {count: 1}}
ementUserCount(Map());
eturns Map { users => Map { count => 1 } }
Returns (Array | Iterable | Object)
Takes items in subject that match pattern.
Parameters
pattern Functionsubject IterableExamples
t users = Map({
3: {id: '123', name: 'Jack'},
6: {id: '456', name: 'Jill'},
e({name: 'Jack'}, users);
eturns Map { 123: {id: '123', name: 'Jack'} }
Returns Iterable
Removes values in unwanted from subject.
Parameters
unwanted Iterablesubject IterableExamples
t removeOne = without(Set.of(1));
veOne(Set.of(1, 2, 3)) // returns Set { 2, 3 }
Returns Iterable