hanuman-js

ø( ^_^ )ø

• 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

Methods:

clone

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

contains

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
 

curry

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

equals

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

filter

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]

find

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 }
 

forEach

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'
 

forEachBreak

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
 
 

get

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'

getOr

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'
 

isEmpty

* 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

map

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 }

omit

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'};

pick

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'};

pickAll

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};

pipe

* 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

range

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];
 

reduce

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 }

reject

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];

scan

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']