- Provides a minimal, yet powerful set of utility functions
- Never mutates data
- Functions are automatically curried
- Only 6.8kb minified
Methods include:
- clone
- contains
- curry
- equals
- filter
- find
- forEach
- forEachBreak
- get
- getOr
- isEmpty
- map
- omit
- pick
- pickAll
- pipe
- range
- reduce
- reject
- scan
If there's something you'd like to see added, open an issue or create a pull request on GitHub.
###Installation: For use with Node/Browserify/webpack:
$ npm install hanuman-js
const H = require('hanuman-js');
For use in the Browser:
$ bower install hanuman-js
<script src="../bower_components/hanuman-js/dist/hanuman.min.js"></script>
###Usage: Since all methods are automatically curried, they may be used in the following manners:
/** Pass all arguments at once */
H.get('a', {a: 44}); // => 44
/** Create and immediately invoke a curried function */
H.get('a')({a: 44}); // => 44
/** Create and save a reference to a curried function to be used later */
const getA = H.get('a');
getA({a: 44}); // => 44
Creates a deep copy of the supplied input for all types except functions,
for which a reference is returned.
######*
→ *
const numbers = [1, 2, 3, 4, 5];
const numbersCopy = H.clone(numbers); // [1, 2, 3, 4, 5];
numbers === numbersCopy; // returns false
const user = {id: '28jd2', name: {first: 'Albert' , last: 'King' }, age: 55};
const userCopy = H.clone(user);
user === userCopy; // returns false
user.id === userCopy.id // returns true
user.name === userCopy.name // returns false
user.age === userCopy.age // returns true
const add = (a,b,c) => a + b + c;
H.clone(add) === add; \\ returns true
H.clone(44); // returns 44
H.clone('copy'); // returns 'copy'
H.clone(true); // returns true
H.clone(null); // returns null
H.clone(undefined); // returns undefined
Returns true if the supplied list contains the target item. Equality is determined using equals.
######*
→ array
→ boolean
const containsTwo = H.contains(2);
containsTwo([1, 2, 3, 4, 5]); // returns true
containsTwo([1, 3, 5, 7, 9]); // returns false
const containsTim = H.contains({name: 'tim', age: 54});
const users = [{name: 'lili' , age: 33 }, {name: 'tim', age: 54}];
containsTim(users); // returns true
const obj = {a: 44, b: 55};
H.contains('a', Object.keys(obj)); // returns true
Returns a curried version of the supplied function.
######function
→ function
const add = (a,b,c) => a + b + c;
const addTen = H.curry(add)(10);
addTen(2,3); // returns 15
addTen(2)(3); // returns 15
const addFifteen = addTen(5);
addFifteen(5); // returns 20
Returns true if the supplied items are equivalent, i.e. deep equal
.
######*
→ *
→ boolean
H.equals(1, 1); // returns true
H.equals(1, '1'); // returns false
H.equals(undefined, null); // returns false
H.equals([1, 2, 3], [1, 2, 3]); // returns true
H.equals({a: 44, b: {c: 55}}, {a: 44, b: {c: 55}}); // returns true
Applies a predicate function to a list of values and returns a new list of values which pass the test
######function
→ array
→ array
const isEven= (a) => a % 2 === 0;
const numbers = [1, 2, 3, 4, 5];
const getEvens = H.filter(isEven);
getEvens(numbers); // returns [2, 4]
Returns the first item in the list that matches the predicate, or undefined if not found
######function
→ array
→ * | undefined
const isEven= a => a % 2 === 0;
const numbers = [1, 2, 3, 4, 5];
const odds = [1, 3, 5, 7, 9];
H.find(isEven, numbers); // returns 2;
H.find(isEven, odds); // returns undefined;
const users = [
{ name: 'lili' , age: 33 },
{ name: 'tim', age: 54 }
];
const isTim = H.get('name') === 'tim';
H.find(isTim, users); // returns { name: 'tim', age: 54 }
Applies a function to each item in the collection. If the collection is an array, the iterator function will receive the value, index, and array. If the collection is an object, the iterator function will receive the value, key, and object.
######function
→ array
→ *
const log = (v, i, list) => console.log(v);
const numbers = [1, 2, 3, 4, 5];
const logEach = H.curry(log);
logEach(numbers); // logs 1, 2, 3, 4, 5
const logObject = (v, k, obj) => console.log(`${k}: ${v}`);
const user = {id: '28jd2', name: {first: 'Albert' , last: 'King' }, age: 55};
H.forEach(logObject, user) // logs 'id: 28jd2', 'name: [object Object]', 'age: 55'
Identical to forEach, except a predicate function is taken as the second parameter to allow for early termination of the iteration process. The predicate function accepts the same parameters as the iterator function. Since the order of object keys cannot be guaranteed, it is not possible to determine when termination will occur for objects.
######function
→ array
→ *
let result = [];
const numbers = [1, 2, 3, 4, 5];
const updateResult = v => result.push(v);
const greaterThanTwo = v => v > 2;
H.forEachBreak(updateResult, greaterThanTwo, numbers);
console.log(result); // [1, 2];
result = {};
const copyToResult = (v, k, obj) => result[key] = v;
const isName = (v, k) => k === 'name';
const user = {id: '28jd2', name: {first: 'Albert' , last: 'King' }, age: 55};
H.forEachBreak(copyToResult, isName, user);
// 'name' is the only property that is guaranteed to be undefined
console.log(result.name); // undefined
Returns a property from an object, or undefined if it doesn't exist. To retrieve a nested property, a period-delimited string or an array of keys may be passed as the first argument
######string | array
→ object
→ * | undefined
const user = {id: '28jd2', name: {first: 'Albert' , last: 'King' }, age: 55};
H.get('id', user); // returns '28jd2'
const getFirstName = H.get('name.first');
getFirstName(user); // returns 'Albert'
H.get('name.middle', user); // returns undefined
H.get(['name', 'last'], user); // returns 'King'
Returns a property from an object, or a specified default if it doesn't exist. To retrieve a nested property, a period-delimited string or an array of keys may be passed as the second argument
######*
→ string | array
→ object
→ *
const user = {
id: '28jd2',
name: {first: 'Albert' , last: 'King' },
age: 55
};
const getOrUnknown = H.getOr('unknown');
const getMiddleName = getOrUnknown('name.middle');
getOrUnknown('age', user); // returns 55
getMiddleName(user); // returns 'unknown'
######* cannot be curried *
Returns a boolean indicating whether or not the given input is empty
######string | array | object
→ boolean
H.isEmpty(''); // returns true
H.isEmpty('empty'); // returns false
H.isEmpty([]); // returns true
H.isEmpty([1, 2, 3]); // returns false
H.isEmpty({}); // returns true
H.isEmpty({a: 'empty'}); // returns false
H.isEmpty(0); // returns false
H.isEmpty(44); // returns false
H.isEmpty(null); // returns false
H.isEmpty(undefined); // returns false
Creates a new array or object by applying a function to each value in the array or object property
######function
→ array | object
→ array | object
const square = (a) => a * a;
const numbers = [1, 2, 3, 4, 5];
H.map(square, numbers); // returns [1, 4, 9, 16, 25]
const double = x => x * 2;
H.map(double, { a: 1, b: 2, c: 3 }); // returns { a: 2, b: 4, c: 6 }
Returns a copy of the supplied object containing all keys except those specified to be omitted. The opposite of pick.
######array
→ object
→ object
const fruit = {
a: 'apple',
b: 'banana',
c: 'cherry',
d: 'date',
e: 'elderberry'
};
H.omit(['a', 'b', 'd'], fruit) // returns {c: 'cherry', e: 'elderberry'};
Returns a new object by copying properties from the supplied object. Undefined properties are not copied to the new object.
######array
→ object
→ object
const fruit = {
a: 'apple',
b: 'banana',
c: 'cherry',
d: 'date',
e: 'elderberry'
};
H.pick(['a', 'b', 'd'], fruit) // returns {a: 'apple', b: 'banana', d: 'date'};
H.pick(['a', 'f'], fruit) // returns {a: 'apple'};
Returns a new object by copying properties from the supplied object. Undefined properties are copied to the new object.
######array
→ object
→ object
const fruit = {
a: 'apple',
b: 'banana',
c: 'cherry',
d: 'date',
e: 'elderberry'
};
H.pickAll(['a', 'b', 'd'], fruit) // returns {a: 'apple', b: 'banana', d: 'date'};
H.pickAll(['a', 'f'], fruit) // returns {a: 'apple', f: undefined};
######* cannot be curried *
Creates a composed function by chaining the provided functions from left to right. The first function in the chain may accept any number of arguments. The remaining functions may only accept a single argument.
######...function
→ function
const double = x => x * 2;
const subtractTen = x => x - 10;
H.pipe(subtractTen, double)(22) // returns 24
const evens = [2, 4, 6, 8, 10, 12];
const addTwo = (a,b) => a + b;
const doubleFirstPlus44 = H.pipe(H.get(0), double, H.curry(addTwo)(44));
doubleFirstPlus44(evens) // returns 48
Returns a list of sequential numbers
######number
→ number
→ array
H.range(1,5); // returns [1, 2, 3, 4, 5]
H.range(15,15); // returns [15]
H.range(1,0); // returns []
const startAtTwelve = H.range(12);
startAtTwelve(13); // returns [12, 13];
startAtTwelve(17); // returns [12, 13, 14, 15, 16, 17];
Applies an iterator function to an accumulator and the current value of the list, successively returning a single value
######function
→ *
→ array
→ *
const add = (a, b) => a + b;
const numbers = [1, 2, 3, 4, 5];
H.reduce(add, 0, numbers); // returns 15
H.reduce(add, 10, numbers); // returns 25
const isEven= (a) => a % 2 === 0;
const evenSquares = (acc, v) => {
if ( isEven(v) ) {
acc[v] = v * v;
}
return acc;
}
H.reduce(evenSquares, {}, numbers); // returns { 2:4, 4:16 }
Applies a predicate function to a list of values and returns a new list containing the values that do not pass the test
######function
→ array
→ array
const isEven= a => a % 2 === 0;
const numbers = [1, 2, 3, 4, 5];
H.reject(isEven, numbers); // returns [1, 3, 5];
Applies an iterator function to an accumulator and each value in a a list, returning a list of successively reduced values
######function
→ *
→ array
→ array
const add = (a, b) => a + b;
const numbers = [1, 2, 3, 4, 5];
H.scan(add, 0, []); // returns [0]
H.scan(add, 0, numbers); // returns [0, 1, 3, 6, 10, 15]
H.scan(add, '', ['a', 'b', 'c']); // returns ['', 'a', 'ab', 'abc']