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