Simple and sweet utility functions for JavaScript and TypeScript applications Global

# any(pred, arr) → {boolean}

Check an Array of items (of any type) to see if any item satisfies a given predicate function. Exits when the first match is found.

Parameters:

Name	Type	Description
`pred`	`function`	A predicate function to evaluate against each item in a given array
`arr`	`Array.<*>`	An array of items to evaluate against the predicate function

View Source any.js, line 1

Returns:

Whether or not any items in the array matched the predicate function

Type: boolean

# append(firstVal, secondVal) → {Array.<*>|object|string}

Blends two values together based on their type. If both are objects this would result in a new object with the second value's props merged onto the first's. If the first value is an array, this would result in a new array with the second value concatenated onto the first value. If both values are strings or numbers, a new string will be returned with the second value added onto the first.

Parameters:

Name	Type	Description
`firstVal`	`string` \| `number` \| `Object.<string, any>` \| `Array.<*>`	A value that will have another appended onto
`secondVal`	`string` \| `number` \| `Object.<string, any>` \| `Array.<*>`	A value to append to the first value

View Source append.js, line 3

Returns:

A new Array, Object, or String that has the characters/values from the second provided value merged after those from the first provided value

Type: Array.<*> | object | string

# assign(obj) → {object}

Assigns the values from one or more Objects onto another Object. This mutates the original Object.

Parameters:

Name	Type	Description
`obj`	`object`	An Object to mutate with the values from one (or more) additionally supplied Objects
`...resOfObjects`	`object`	One or more Objects to extract from and assign onto the first Object

View Source assign.js, line 3

Returns:

The first object mutated with the values from any other object passed in

Type: object

# clone(obj) → {object|Array.<*>}

Recursively copies the content of an Object into a new Object

Parameters:

Name	Type	Description
`obj`	`object` \| `Array.<*>`	An Object (or Array) from which to create a deep copy

View Source clone.js, line 6

Returns:

The new (cloned) Object (or Array)

Type: object | Array.<*>

# combine(val1, val2) → {*}

Combines two values of the same type (if it makes sense to combine them). Numbers are summarized, strings and arrays are concatenated together, and true objects are merged (the second value merged on top of the first). In any other case only the first value is returned.

Parameters:

Name	Type	Description
`val1`	`*`	The base value to be combined with
`val2`	`*`	The value to combine

View Source combine.js, line 5

Returns:

If the values are of the same type, this represents the combined value of the two of them. Otherwise only the first value is returned

Type: *

# compose() → {function}

Creates a chain of Functions that will be executed in sequnce (from right to left), with the value from the previous Function fed into the next Function. The value that the chain of functions will executed on can be provided later.

Parameters:

Name	Type	Description
`...fns`	`function`	One or more function to execute (in sequential order) on a value that will be supplied later

View Source compose.js, line 4

Returns:

A single Function that is ready to receive a value and pass it through the composed chain of Functions

Type: function

# concat(firstArr, secondArr) → {Array.<*>}

Adds the values from one Array onto another Array, returned as a new Array (ie, it does not mutate the first Array). This operation is recursive, so you can supply as many arrays as you wish.

Parameters:

Name	Type	Description
`firstArr`	`Array.<*>`	An Array of values (of any type)
`secondArr`	`Array.<*>`	An Array of values (of any type)

View Source concat.js, line 1

Returns:

A new Array with the values from the second array concatenated onto those from the first

Type: Array.<*>

# cond(conditionalTransforms, val) → {*}

Several pieces of conditional logic to apply against a value and the first one which matches will have a corresponding transformation applied to it.

Supply an Array of pairs:

the first value is the conditional logic (Function) to match against the value
the second value is the transformation (Function) to apply to the value if the condition was matched

Note: if your tranformation is not a function then it will returned as-is in response to a succesfully met condition

Parameters:

Name	Type	Description
`conditionalTransforms`	`Array.<Array.<function()>>`	An array of arrays (which have two values: the condition function and the transformation function)
`val`	`*`	A value of any type that will be transformed according to the appropriate condition.

View Source cond.js, line 1

Returns:

The provided value transformed by the appropriate matching conditional transformation

Type: *

# contains(val, arr) → {boolean}

Checks if a given value is present in a String OR Array

Parameters:

Name	Type	Description
`val`	`string` \| `number`	A value which may be present in the String/Array
`arr`	`Array.<*>` \| `string`	An Array or String which may contain the provided value

View Source contains.js, line 3

Returns:

Whether or not the String|Array contains the provided value

Type: boolean

# converge(fn) → {function}

Run several Functions (or composed chains of Functions) onto the same input and converges their results as arguments to another Function.

A common example might be to take an Object that needs to be transformed in several different ways and then merged into one final Object. In that case you can supply a "merge" (or "assign") Function as the convergence Function, and then pass all your Object transforming Functions as additional arguments. When you're ready to receive the actual input Object it will be forked into all the transform Functions and their results will converge into the merge/assign Function you supplied first.

Parameters:

Name	Type	Description
`fn`	`function`	A Function to converge the results (from executing all the others) into
`...forkedFunctions`	`function`	Two or more Functions (should be at least two, otherwise you're using the wrong util; use compose instead) that will later receive the same input

View Source converge.js, line 1

Returns:

A wrapped Function that is ready to receive a value(s) and pass it (in parallel) into the other Functions, converging those results as arguments to the first Function you supplied

Type: function

# convergeZip(fn) → {function}

Run several Functions (or composed chains of Functions) onto the same input and converges their results as arguments to another Function. Compare to "converge" however the difference is that this is always intended to be used with multiple input values and each of those values corresponds to one of the forked functions. They all still converge into one Function, but the forked function just don't receive the same input values.

Parameters:

Name	Type	Description
`fn`	`function`	A Function to converge the results (from executing all the others) into
`...forkedFunctions`	`function`	Two or more Functions (should be at least two, otherwise you're using the wrong util; use compose instead) that will later receive the same input

View Source convergeZip.js, line 1

Returns:

A wrapped Function that is ready to receive multiple values that each correspond to one of the fork functions, converging those results as arguments to the first Function you supplied

Type: function

# curry(fn) → {function}

Takes a Function whose params are meant to be supplied all at once and changes it so they can be supplied one at a time. As each argument is supplied a new Function is returned that is ready to receive the next argument. This continues until all arguments for your origianl function have been supplied and then the actual result is returned.

Note: you cannot set default values for curried function params (again, you cannot set default values for curried function params)

Parameters:

Name	Type	Description
`fn`	`function`	A Function whose signature needs to changed from requiring all at once to providing them one (or more) at a time.

View Source curry.js, line 1

Returns:

A new Function that will wait until all arguments have been supplied before returning a result (otherwise it will continue to return a new Function that is ready to receive the next argument)

Type: function

# curryN(arity, fn) → {function}

Same as the regular curry function, but you must also specify the number of arguments that the curried function will take before being fully executed. You would use this in cases where it cannot be inferred from the curried function itself.

Parameters:

Name	Type	Description
`arity`	`number`	The number of arguments the curried function will received before being executed
`fn`	`function`	A Function whose signature needs to changed from requiring all at once to providing them one (or more) at a time.

View Source curryN.js, line 1

Throws:

if arity is not supplied or is not a positive number

Type: TypeError

Returns:

A new Function that will wait until all (arity) arguments have been supplied before returning a result (otherwise it will continue to return a new Function that is ready to receive the next argument)

Type: function

# difference(arr1, arr2) → {Array.<string>|Array.<number>}

Compares two lists of Strings/Numbers and returns the values that are different between the two lists

Parameters:

Name	Type	Description
`arr1`	`Array.<string>` \| `Array.<number>`	An Array of Strings
`arr2`	`Array.<string>` \| `Array.<number>`	An Array of Strings

View Source difference.js, line 3

Returns:

An array of values that are different between the two lists

Type: Array.<string> | Array.<number>

# each(fn, arr)

A faster forEach that provides the same API as native.

Parameters:

Name	Type	Description
`fn`	`function`	A Function to execute for each iteration. It will receive the value, index and full array (respectively) as args
`arr`	`Array.<*>`	An Array to iterate over (any value will be passed into the iterate Function)

View Source each.js, line 1

# eitherOr(fnA, fnB, val) → {*}

A function that accepts two functions and a value and will return the first result which is "truthy". This function is curried because it doesn't make any sense to even have it unless you have the functions ahead of time but not the value.

Parameters:

Name	Type	Description
`fnA`	`function`	The first function to be executed on the value
`fnB`	`function`	The second function to be executed on the value
`val`	`*`	A value to be passed into the functions

View Source eitherOr.js, line 3

Returns:

The result of executing value passed in

Type: *

# entries(obj) → {Array.<string>}

Extracts an Array of key/value pairs from an Object.

Parameters:

Name	Type	Description
`obj`	`object`	The input object from which to extract prop keys and values

View Source entries.js, line 1

Returns:

An Array of key/value pairs corresponding to those on the input object

Type: Array.<string>

# escapeHtml(val) → {string}

Converts ampersands, angle brackets, apostrophes and blockquotes to their HTML encoded equivalents

Parameters:

Name	Type	Description
`val`	`string`	A string values to escape

View Source escapeHtml.js, line 10

Returns:

The original value (converted to string) and with any of the unallowed characters properly escaped (null/undefined values are converted to '')

Type: string

# filter(fn, val) → {object|Array.<*>|string}

Applies a filtering function you provide over a value you provide, according to its type. String values will have the filtering function applied over every character in the String. Objects will have the filtering function applied to every value in the Object. Arrays (or Array-like values) will have the filtering function applied to every value in the Array. If the type of your value is none of the above, the value will be returned as-is.

Parameters:

Name	Type	Description
`fn`	`function`	A filtering function that is invoked on the provided value
`val`	`object` \| `Array.<*>` \| `string`	An Object/Array/String whose values/chars will be filtered

View Source filter.js, line 6

Returns:

A new value that is the result of the filtering operation over all the chars or values in the original String/Object/Array

Type: object | Array.<*> | string

# filterObject(fn, obj) → {object}

Applies a filtering function you provide over every value in a given Object.

Parameters:

Name	Type	Description
`fn`	`function`	A filtering function that is invoked on every value in the provided Object
`obj`	`object`	An Object whose values will be filtered

View Source filterObject.js, line 3

Returns:

A new Object that is the result of the filtering operation over all the values in the original Object

Type: object

# filterString(fn, str) → {string}

Applies a filtering function you provide over every character in a given string.

Parameters:

Name	Type	Description
`fn`	`function`	A filtering function that is invoked on every char in the provided String value
`str`	`string`	A string value to filter over

View Source filterString.js, line 1

Returns:

A new String value that is the result of the filtering operation over the original string

Type: string

# find(pred, arr) → {*}

Find a single value from an array of values, based on criteria defined in a predicate function.

Parameters:

Name	Type	Description
`pred`	`function`	A predicate function to apply to the array of values (It should take a val as input and return a Boolean as output).
`arr`	`Array.<*>`	An array of values from which to find one particular matching value

View Source find.js, line 3

Returns:

Either a value from the array that matched the predicate function or undefined (if no match)

Type: *

# findIndex(pred, arr) → {number}

Find the index of a single value from an array of values, based on criteria defined in a predicate function.

Parameters:

Name	Type	Description
`pred`	`function`	A predicate function to apply to the array of values (It should take a val as input and return a Boolean as output).
`arr`	`Array.<*>`	An array of values from which to find the index of one particular matching value

View Source findIndex.js, line 1

Returns:

Either the index of the value from the array that matched the predicate function or negative one (-1, if no match).

Type: number

# first(val) → {*}

Extracts the first value of an array of values.

Parameters:

Name	Type	Description
`val`	`Array.<*>`	An array of values from which to extract the first value

View Source first.js, line 1

Returns:

The value at the first index of the supplied array (which may be undefined)

Type: *

# flatten(arr) → {Array.<*>}

Extracts nested arrays (of any depth) from a provided array, placing them onto on single new array.

Parameters:

Name	Type	Description
`arr`	`Array.<Array.<>>` \| `Array.<>`	An array of values that may or may not be nested arrays themselves

View Source flatten.js, line 3

Returns:

A new array of values, but with any nested arrays from the original input extracted onto one single (flat) array

Type: Array.<*>

# flipKeyValues(obj) → {object}

Swaps the values for keys in a given object. So the values in that object should be the kind that can be converted to unique string values

Parameters:

Name	Type	Description
`obj`	`object`	An object whose values can be swapped for keys

View Source invert.js, line 3

Returns:

A new object whose keys were the values from the original object

Type: object

# forIn(fn, obj)

A light wrapper around native for .. in, but will only iterate over an Object's own properties.

Parameters:

Name	Type	Description
`fn`	`function`	A function to execute iteratively, which will receive the `key`, `value`, and `object` (respectively)
`obj`	`object`	An object whose keys will be iterated over

View Source forIn.js, line 3

# fuzzy(propFn, needle, caseSensitiveopt, arr) → {Array.<string>|Array.<object>}

Performs a fuzzy search on a list of strings or objects. If a list of objects, provided the prop extraction function so the search can find the correct field(s) This is heavily inspired by (most of) the algorithm used by Matt York's fuzzy search function, however several features were not carried over and his implementation of that alrgorithm has been significantly changed to achieve a 25% speed improvement. Please see his original work - called fuzzy MIT - if you need some of his additional options.

Parameters:

Name	Type	Attributes	Default	Description
`propFn`	`function`			A function which will extract all the fields which you wish to fuzzy search on. Omit if the list is a list of strings
`needle`	`string`			The search value itself
`caseSensitive`	`boolean`	<optional>	false	Whether or not to perform a case-sensitive search
`arr`	`Array.<string>` \| `Array.<object>`			An array of string values or objects which have string values to be searched on

View Source fuzzy.js, line 1

Returns:

The filtered list of search results

Type: Array.<string> | Array.<object>

# getType(val) → {string}

Gets the type for any value. If available will inspect the constructor name, otherwise will use the typeof

Parameters:

Name	Type	Description
`val`	`*`	A value of any kind

View Source getType.js, line 5

Returns:

The stringified representation of the value's type

Type: string

# has(key, obj) → {boolean}

Checks if a given Object contains a specified prop name

Parameters:

Name	Type	Description
`key`	`string`	A prop name to look for in the object
`obj`	`object`	An Object to inspect for a given prop

View Source has.js, line 1

Returns:

Whether the object contains the specified prop

Type: boolean

# hasNestedProp(prop, obj) → {boolean}

Checks if a given Object contains a (potentially) nested property of a specified path

Parameters:

Name	Type	Description
`prop`	`Array.<string>` \| `string`	A prop name, a dot-separated prop path, or an array of prop path "pieces" to look for in the object
`obj`	`object`	An Object to inspect for a given prop at the specified path

View Source hasNestedProp.js, line 3

Returns:

Whether the object contains the specified prop path

Type: boolean

# identity(v) → {*}

A function that always returns the value passed to it

Parameters:

Name	Type	Description
`v`	`*`	A value to be returned

View Source identity.js, line 1

Returns:

The value passed in

Type: *

# intersection(arr1, arr2) → {Array.<string>|Array.<number>}

Compares two lists of Strings/Numbers and returns the values that are in common (intersect) between the two lists

Parameters:

Name	Type	Description
`arr1`	`Array.<string>` \| `Array.<number>`	An Array of Strings/Numbers
`arr2`	`Array.<string>` \| `Array.<number>`	An Array of Strings/Numbers

View Source intersection.js, line 3

Returns:

The values in common between the two lists

Type: Array.<string> | Array.<number>

# is(ofType, val) → {boolean}

Checks to see if a value is a certain type. You may specify that type as a case-insensitive string (ie, 'string', 'boolean', 'object', 'function', 'array', 'regexp', 'date', 'set, 'map'), OR a JavaScript type constructor function (ie, String, Function, Boolean, Array, RegExp, Date, Set, Map).

Parameters:

Name	Type	Description
`ofType`	`function` \| `string`	A JavaScript type constructor function (like `Function`, `String`, `RegExp`, `Boolean`, `Array`, `Object`, etc.) or a string value matching the name of one
`val`	`*`	A value (of any type)

View Source is.js, line 4

Returns:

Whether or not the value matches the specified type

Type: boolean

Example

is('boolean', true)
is('array', [1, 2, 3])
is(RegExp, /[a-z0-9]/)
is(Function, () => null)

# isArrayish(val) → {boolean}

Checks if a given value is "array-like".

This includes:

Array
Set
WeakSet
Float64Array
Float32Array
Int32Array
Uint16Array
Int16Array
Uint8ClampedArray
Uint8Array
Int8Array

Parameters:

Name	Type	Description
`val`	`*`	A value to check as being an array

View Source isArrayish.js, line 32

Returns:

Whether the value is an array-like type

Type: boolean

# isBlankString(val) → {boolean}

Checks a value to see if it is a String containing either no characters OR no characters except for whitespace.

Parameters:

Name	Type	Description
`val`	`*`	A value of any type

View Source isBlankString.js, line 1

Returns:

Whether or not the value is a blank string

Type: boolean

# isEmpty(val) → {boolean}

Checks if a value is empty. Arrays, Objects, Strings, Sets, and Null/Undefined values are considered empty if their length (or size) prop is zero (or if they are Null or Undefined). Whitespace-only strings are NOT considered empty (use isBlankString instead).

Parameters:

Name	Type	Description
`val`	`*`	A value of any type which may be considered empty

View Source isEmpty.js, line 3

Returns:

Whether or not the value is empty

Type: boolean

# isEqual(firstVal, secondVal) → {boolean}

Checks if two provided values are deeply equal. If Objects or Arrays (or Array-like values) are provided, they are inspected recursively. Primitive values are checked to see if they are stricly equal (ie triple equals; no type coercion).

Parameters:

Name	Type	Description
`firstVal`	`*`	A value which may be null, undefined, a JavaScript primitive value, an array of values, an array-like value, or an object
`secondVal`	`*`	A value which may be null, undefined, a JavaScript

View Source isEqual.js, line 3

Returns:

Whether or not the two values are deeply equal

Type: boolean

# isInteger(val) → {boolean}

Checks a value to see if it is an integer.

Parameters:

Name	Type	Description
`val`	`*`	A value (of any type)

View Source isInteger.js, line 3

Returns:

Whether or not the value is an integer

Type: boolean

# isMap(val) → {boolean}

Checks to see if a value is a Map or WeakMap

Parameters:

Name	Type	Description
`val`	`*`	A value (of any type)

View Source isMap.js, line 3

Returns:

Whether or not the value is a Map or WeakMap

Type: boolean

# isNegativeInteger(val) → {boolean}

Checks if a given numeric value is a negative integer.

Parameters:

Name	Type	Description
`val`	`number`	A value to verify is a negative integer

View Source isNegativeInteger.js, line 3

Returns:

Whether or not the given value is a negative integer

Type: boolean

# isNegativeNumber(val) → {boolean}

Checks if a given numeric value is negative.

Parameters:

Name	Type	Description
`val`	`number`	A value to verify is a negative number

View Source isNegativeNumber.js, line 3

Returns:

Whether or not the given value is a negative number

Type: boolean

# isNil(val) → {boolean}

Checks to see if a value is null OR undefined

Parameters:

Name	Type	Description
`val`	`*`	A value (of any type)

View Source isNil.js, line 1

Returns:

Whether or not the value is null or undefined

Type: boolean

# isNumber(val) → {boolean}

Checks if a given value is numeric

Parameters:

Name	Type	Description
`val`	`number`	A value to verify is a number

View Source isNumber.js, line 1

Returns:

Whether or not the given value is a number

Type: boolean

# isObject(val) → {boolean}

A high-speed, mostly adequate check of a value which may be an Object. This excludes values that are technically an Object but in practice are not what you really mean when you speak of Objects.

Parameters:

Name	Type	Description
`val`	`*`	A value (of any type)

View Source isObject.js, line 46

Returns:

Whether or not the value is an Object

Type: boolean

# isObjectish(val) → {boolean}

Tests whether or not a given value is object-like. This means a hashmap, map, weak map, object literal, instantiated custom class, but not some of the kinds of constructs which JavaScript considers to be technically an object (Error, Array, Null, Function, Date, etc.)

Parameters:

Name	Type	Description
`val`	`*`	A value that may or may not be object-like

View Source isObjectish.js, line 44

Returns:

Whether or not the value is object-like

Type: boolean

# isPositiveInteger(val) → {boolean}

Checks if a given numeric value is a positive integer.

Parameters:

Name	Type	Description
`val`	`number`	A value to verify is a positive integer

View Source isPositiveInteger.js, line 3

Returns:

Whether or not the given value is a positive integer

Type: boolean

# isPositiveNumber(val) → {boolean}

Checks if a given numeric value is positive.

Parameters:

Name	Type	Description
`val`	`number`	A value to verify is a positive number

View Source isPositiveNumber.js, line 3

Returns:

Whether or not the given value is a positive number

Type: boolean

# isPrime(val) → {boolean}

Checks if a given numeric value is a prime number. This is any integer value divisible only by itself and 1.

Parameters:

Name	Type	Description
`val`	`number`	A value to verify is a prime number

View Source isPrime.js, line 1

Returns:

Whether or not the given value is a prime number

Type: boolean

# isPrimitive(val) → {boolean}

Checks if a given value is of a primitive type (ie, Boolean, String, Number, or Symbol).

Parameters:

Name	Type	Description
`val`	`*`	A value which may be of a primitive type

View Source isPrimitive.js, line 27

Returns:

Whether or not the value is primitive

Type: boolean

# isPromise(val) → {boolean}

Checks if a value is a JavaScript Promise. This just means a deferred object/function with a method named then.

Parameters:

Name	Type	Description
`val`	`*`	A value of any type which may be a promise

View Source isPromise.js, line 1

Returns:

Whether or not the value is a promise

Type: boolean

# isSameType(val1, val2) → {boolean}

Inspects two values to see if they are the same type. The typeof and (if necessary) constructor names are inspected during this check.

Parameters:

Name	Type	Description
`val1`	`*`	A value (of any type)
`val2`	`*`	A value (of any type)

View Source isSameType.js, line 3

Returns:

Whether or not the two values are of the same type

Type: boolean

# isSet(val) → {boolean}

Checks to see if a value is a Set or WeakSet

Parameters:

Name	Type	Description
`val`	`*`	A value (of any type)

View Source isSet.js, line 3

Returns:

Whether or not the value is a Set or WeakSet

Type: boolean

# isStrictEqual(firstVal, secondVal) → {boolean}

Inspects two values to see if they are strictly equal, meaning no type coercion or deepyly nested equality checks are performed. A very simple triple equals is all that is used.

Parameters:

Name	Type	Description
`firstVal`	`*`	A value (of any type)
`secondVal`	`*`	A value (of any type)

View Source isStrictEqual.js, line 1

Returns:

Whether or not the two values are strictly equal

Type: boolean

# isUndefined(val) → {boolean}

Checks to see if a value is undefined

Parameters:

Name	Type	Description
`val`	`*`	A value (of any type)

View Source isUndefined.js, line 1

Returns:

Whether or not the value is undefined

Type: boolean

# isZero(val) → {boolean}

Checks if a given value is zero or a string representing zero. For string values, what we want is "0" or "0.0" but not "" or " " (which also coerce to zero).

Parameters:

Name	Type	Description
`val`	`number` \| `string`	A value to verify is zero or a zero-like string.

View Source isZero.js, line 1

Returns:

Whether or not the given value is zero or a zero-like string.

Type: boolean

# last(arr) → {*}

Retrieves the last value from an Array

Parameters:

Name	Type	Description
`arr`	`Array.<*>`	An array of any kind of values

View Source last.js, line 1

Returns:

The last value from a given array

Type: *

# map(fn, val) → {object|Array.<*>|string}

Applies a mapping function you provide over a value you provide, according to its type. String values will have the mapping function applied over every character in the String. Objects will have the mapping function applied to every value in the Object. Arrays (or Array-like values) will have the mapping function applied to every value in the Array. If the type of your value is none of the above, the value will be returned as-is. Also, this mapping operation does not mutate the original value.

Parameters:

Name	Type	Description
`fn`	`function`	A mapping function that is invoked on the provided value
`val`	`object` \| `Array.<*>` \| `string`	An Object/Array/String whose values/chars will be mapped over

View Source map.js, line 5

Returns:

A new value that is the result of the mapping operation over all the chars or values in the original String/Object/Array

Type: object | Array.<*> | string

# mapObject(fn, obj) → {object}

Applies a mapping function you provide over every value in a given Object.

Parameters:

Name	Type	Description
`fn`	`function`	A mapping function that is invoked on every value in the provided Object
`obj`	`object`	An Object whose values will be mapped over

View Source mapObject.js, line 3

Returns:

A new Object that is the result of the mapping operation over all the values in the original Object

Type: object

# mapObjectRecursive(fn, obj) → {object}

Applies a mapping function you provide over every value in a given Object (recursively).

Parameters:

Name	Type	Description
`fn`	`function`	A mapping function that is invoked on every value in the provided Object
`obj`	`object`	An Object whose values will be mapped over (recursively)

View Source mapObjectRecursive.js, line 4

Returns:

A new Object that is the result of the mapping operation over all the values in the original Object

Type: object

# mapSpec(spec, obj) → {object}

Applies one or more mapping functions to the value in a given Object. But rather than applying the same mapping function to every value in an Object, instead you use a "spec" object to link the appropriate mapping function to the key/val in the input Object.

This is similar to Ramda's evolve() however you can also set values in your spec that are not functions (which will just override whatever matching key there might be on the input object). Addtionally, it supplies the key and the object as the 2nd and third params to your spec's transformation function, so that you can create props based on the entire input Object (with Ramda you'll need to also use applySpec() and in a separate operation to derived these kinds of values).

As an example, If you want a mapping function to be applied to a prop called "name", then you would first pass in a spec object with a prop on it called "name" and the value would be the mapping function. Then the actual input object (with the desciption field) will have the matching mapping function from your spec applied to it directly.

Parameters:

Name	Type	Description
`spec`	`object`	An Object whose keys should correspond to keys in the input Object and whose values are mapping functions that will receive the matching input Object's prop as input
`obj`	`object`	The actual input to map over and transform

View Source mapSpec.js, line 5

Returns:

A new Object with all the mapping functions from the spec Object applied to the corresponding values in the input Object (if they exist)

Type: object

Example

mapSpec({
    age: Number,
    isAlive: Boolean,
    name: str => `${str.charAt(0).toUpperCase()}${str.slice(1)}`
  }, {
    age: '20',
    isAlive: 1,
    name: 'john'
  })

# mapString(fn, str) → {string}

Applies a mapping function you provide over every character in a given string.

Parameters:

Name	Type	Description
`fn`	`function`	A mapping function that is invoked on every char in the provided String value
`str`	`string`	A string value to map over

View Source mapString.js, line 1

Returns:

A new String value that is the result of the mapping operation over the original string

Type: string

# memoize(fn) → {function}

Takes a snapshot of the input args and the output result for a provided function, and on repeated usage will shortcut invoking the function and return the cached output instead, whenever the same input args are supplied to the function.

Parameters:

Name	Type	Description
`fn`	`function`	A function whose input values (supplied later) will be cached with its output result, so that the invoking the function can be skipped the next time the same values are passed to it

View Source memoize.js, line 3

Returns:

A memoized version of the original function. It will cache the input values supplied to it each time it is used

Type: function

# merge() → {object|Array.<*>}

Merges the values from 2 or more Objects or Arrays together into a new Object/Array. Null and Undefined values are handled gracefully, and if the second value is a primitive it will be returned as-is, instead of trying to merge it onto the first.

Parameters:

Name	Type	Description
`...val`	`Array.<(object\|Array.<*>)>`	Values to merge together (values with higher precedence should be provided last)

View Source merge.js, line 3

Returns:

A new value that contains the combined values from all the values passed in

Type: object | Array.<*>

# omit(keys, obj) → {object}

Removes specified keys from an object (after cloning the Object).

Parameters:

Name	Type	Description
`keys`	`Array.<string>`	An array of keys to search for in the Object and exclude from the output
`obj`	`object`	An Object from which to copy and remove keys

View Source omit.js, line 4

Returns:

A copy of the original Object, but without the specified keys

Type: object

# omitNull(obj) → {object}

Removes all null or undefined values from a given object

Parameters:

Name	Type	Description
`obj`	`object`	An Object from which to copy and remove null/undefined

View Source omitNull.js, line 1

Returns:

A copy of the original Object, but without any null or undefined values

Type: object

# omitUndefined(obj) → {object}

Removes all undefined values from a given object

Parameters:

Name	Type	Description
`obj`	`object`	An Object from which to copy and remove undefined

View Source omitUndefined.js, line 1

Returns:

A copy of the original Object, but without any undefined values

Type: object

# pick(keys, obj) → {object}

Removes everything except the specified keys from an object (after cloning the Object).

Parameters:

Name	Type	Description
`keys`	`Array.<string>`	An array of keys to search for in the Object and include from the output
`obj`	`object`	An Object from which to copy and remove keys

View Source pick.js, line 1

Returns:

A copy of the original Object, but with only the specified keys

Type: object

# pipe() → {function}

Creates a chain of Functions that will be executed in sequnce (from left to right), with the value from the previous Function fed into the next Function. The value that the chain of functions will executed on can be provided later.

Parameters:

Name	Type	Description
`...fns`	`function`	One or more function to execute (in sequential order) on a value that will be supplied later

View Source pipe.js, line 4

Returns:

A single Function that is ready to receive a value and pass it through the piped chain of Functions

Type: function

# prepend(firstVal, secondVal) → {Array.<*>|object|string}

Merges two values together, placing the characters (or values) from one before those from the other.

Parameters:

Name	Type	Description
`firstVal`	`Array.<*>` \| `object` \| `string` \| `number`	An Array, Object, String or Number that the will have a new value(s) merged before its own characters/values
`secondVal`	`Array.<*>` \| `object` \| `string` \| `number`	An Array, Object, String or Number that the will merge before those from the first provided value

View Source prepend.js, line 3

Returns:

A new Array, Object, or String that has the characters/values from the second provided value merged before those from the first provided value

Type: Array.<*> | object | string

# promiseAll(requests, ignoreErrors) → {Promise.<*>}

Gathers an Array of Functions that return Promises and returns an Array of results, once they have all completed. The only difference between this and native Promise.all() is that these promises will all be resolved/rejected before the final Promise (containing all the results) is returned. With native Promise.all(), the first unhandled rejection will cause the whole endeavor to be terminated. Addtionally you can pass in a flag to force caught errors to be ignored entirely.

Parameters:

Name	Type	Description
`requests`	`Array.<function()>`	An array of Functions that return Promises
`ignoreErrors`	`boolean`	Whether or not to ignore errors entirely (this will cause all the results to be returned and any Errors will be returned in place of the results)

View Source promiseAll.js, line 1

Returns:

A Promise that will resolve once all of the Promises are resolved/rejected

Type: Promise.<*>

# promiseChain(requests) → {Promise.<*>}

Gathers an Array of Promises (or of Functions that return Promises) and executes them in sequential order they appear in the Array. The value from the last will be supplied to the next (in case you need it).

Parameters:

Name	Type	Description
`requests`	`Array.<Promise.<*>>` \| `Array.<function()>`	An array of Promises (or of Functions that return Promises) which need to be executed in sequential order

View Source promiseChain.js, line 1

Returns:

A Promise that will resolve when each of the requests completes

Type: Promise.<*>

# promiseCompose(requests) → {Promise.<*>}

Gathers an Array of Promises (or of Functions that return Promises) and executes them from right to left. You can pass them all together in either a single array, or one by one as arguments (ie, in the style of either apply or call).

Parameters:

Name	Type	Description
`requests`	`Array.<Promise.<*>>` \| `Array.<function()>`	An array of Promises (or of Functions that return Promises) which need to be executed in sequential order

View Source promiseCompose.js, line 3

Returns:

A Promise that will resolve when each of the requests completes

Type: Promise.<*>

# propAt(prop, obj) → {*|undefined}

Looks for a specified key on an Object you provide. The is performed safely and will not throw an error if something on the prop path chain you specify doesn't exist. Will always return undefined if a prop path cannot be resolved (rather than throwing).

Parameters:

Name	Type	Description
`prop`	`string` \| `Array.<string>`	A top-level key OR a deeply nested prop path (which may be represented as an array or as a single dot-delimited string)
`obj`	`object`	An object which may contain a specified prop

View Source propAt.js, line 3

Returns:

The value associated with the nested prop path OR undefined if it does not exist

Type: * | undefined

# propEquals(prop, val, obj) → {boolean}

Looks for a specified key on an Object you provide and checks to see if its corresponding value equals the value you specifiy.

Parameters:

Name	Type	Description
`prop`	`string`	A key to search for on the Object
`val`	`*`	A value that the extracted prop will be compared against
`obj`	`object`	An object which may contain a specified prop

View Source propEquals.js, line 3

Returns:

Whether or not the requested prop equals the specified value

Type: boolean

# propIs(type, prop, obj) → {boolean}

Looks for a specified key on an Object you provide and checks to see if its corresponding value is of the type you specifiy.

Parameters:

Name	Type	Description
`type`	`function` \| `string`	A JavaScript type constructor function (ie `Boolean`, `RegExp`, `Date`, `Array`, `Object`, `Number`, `String`, etc) OR a string represention of the type (ie, "boolean", "regexp", "date", "array", "object", "number", "string", etc)
`prop`	`string`	A key to search for on the Object
`obj`	`object`	An object which may contain a specified prop

View Source propIs.js, line 4

Returns:

Whether or not the requested prop is of the type specified

Type: boolean

# propOr(fallback, prop, obj) → {*}

Attempts to find a specified key on an Object you provide, and if not found will fall back to an additional value you specify.

Parameters:

Name	Type	Description
`fallback`	`*`	A value to fall back on if the requested key does not exist on the provided Object
`prop`	`string`	A key to search for on the Object
`obj`	`object`	An object which may contain a specified prop

View Source propOr.js, line 4

Returns:

Either the requested prop (from the Object) or the fallback value

Type: *

# propSet(prop, val, obj) → {object}

Looks for a specified key on an Object you provide and sets it to the provided value. If the path does not exist, it will be created (you can check for the path via propIs or propAt or propEquals first if you don't wish to create the path every time). The is performed safely and will not throw an error if somethign on the prop path chain you specify doesn't exist.

Parameters:

Name	Type	Description
`prop`	`string` \| `Array.<string>`	A top-level key OR a deeply nested prop path (which may be represented as an array or as a single dot-delimited string)
`val`	`*`	A value to be placed at the provided property path
`obj`	`object`	An object which onto which the value will be placed

View Source propSet.js, line 5

Returns:

The original object, but modified to have the provided value placed at the specified path it does not exist

Type: object

# reduce(fn, defaultVal, arr) → {*}

A simple wrapper around native Array.prototype.reduce(), for use in a compose/pipe chain of functions. Can also reduce the key/value pairs of an object, if one is supplied in place of an array.

Parameters:

Name	Type	Description
`fn`	`function`	A function to control the reduction of each item in the array\|object into the single output value
`defaultVal`	`*`	A starting value for the reduction accumulator
`arr`	`Array.<*>` \| `object`	An array of values of any type OR an object containing key/value pairs

View Source reduce.js, line 1

Returns:

The original Array|Object somehow reduced to one value, according to the supplied function

Type: *

# renameKeys(keyMap, obj) → {object}

Renames a set of keys in a given object (removing the old ones)

Parameters:

Name	Type	Description
`keyMap`	`object`	An object whose keys are the current key names and whose values are the new key names
`obj`	`object`	An Object whose keys will be renamed

View Source renameKeys.js, line 4

Returns:

A new Object that has all the specified keys renamed to their new names

Type: object

# shim(obj) → {Proxy}

Recursively shims an Object. Every time the getter is invoked (which happens whenever prop paths are referenced in the consuming code), the path is shimmed with another Proxy. It is not a polyfill but rather a way to keep deep prop paths that may not exist on the source object from throwing an error.

Parameters:

Name	Type	Description
`obj`	`object`	An object that will be the Proxy's source

View Source shim.js, line 16

Returns:

An Object that will return props on the source Object if they exist but safely handle missing prop paths without throwing errors.

Type: Proxy

# size(val) → {number}

Checks the length (or size) of many different types of values:

Array
Set
Map
Object (num of keys)
String (num of chars)
Function (num of params)

Parameters:

Name	Type	Description
`val`	`object` \| `string` \| `Array.<*>` \| `function`	A value of type Object, String, Array or Function

View Source size.js, line 3

Returns:

The length of the String or Array, OR the number of keys in the Object

Type: number

# toCamelCase(str) → {string}

Transforms a string value into one which is camel cased. Hyphens and underscores are removed and interpred as the boundaries for new words. The first letter of each new word - not preceded by whitespace - is capitalized.

Parameters:

Name	Type	Description
`str`	`string`	A string which may contain underscores and hyphens and/or may be title-cased.

View Source toCamelCase.js, line 1

Returns:

A new string that is without hyphens and underscores and the first letter of every new word boundary is capitalized, unless preceded by whitespace

Type: string

# toHashCode(val, limitopt) → {number}

Creates a numeric hash code (integer) between 1 and the specified limit. The sum of all the string char codes is the dividend and the limit is the divisor, but the remainder (integer) will be the actual hash code.

Parameters:

Name	Type	Attributes	Default	Description
`val`	`string` \| `number`			A string or numeric value for which to generate the hash code
`limit`	`number`	<optional>	26	The limit of the range of hash code values (this will be the divisor in the modulus division)

View Source toHashCode.js, line 1

Returns:

A numeric representation of the characters in the provided string (will return zero if a string|number is not provided as input)

Type: number

# toInteger(str) → {number}

Converts a given value to an Integer and rounds up or down floating point values appropriately. If the values is a Boolean, then true will yield 1 and false will yield 0. If NaN` then zero will always be returned.

Parameters:

Name	Type	Description
`str`	`string`	A string which may be numeric

View Source toInteger.js, line 1

Returns:

Either the successfully converted number or zero (if it was NaN)

Type: number

# toKebabCase(str) → {string}

Transforms a string value into one which is hyphenated. Whitespace and underscores are replaced with hyphens, and uppercase letters are interpreted as boundaries for new hyphenated words.

Parameters:

Name	Type	Description
`str`	`string`	A string which may contain uppercase characters

View Source toKebabCase.js, line 1

Returns:

A new string that is a hyphenated representation of the original string

Type: string

# toLowerCase(str) → {string}

Simple wrapper around String.prototype.toLowerCase() that is provided for consistency with the non-native string case methods (toKebabCase(), toCamelCase(), etc)

Parameters:

Name	Type	Description
`str`	`string`	A string which may contain uppercase characters

View Source toLowerCase.js, line 1

Returns:

A new string that is an lowercase representation of the original string

Type: string

# toNumber(val) → {number|undefined}

Coerces a given string value to a number (if valid).

Parameters:

Name	Type	Description
`val`	`string`	A string value to coerce to a number

View Source toNumber.js, line 4

Returns:

A numeric representation of the original value, or undefined if it cannot be coerced to a number.

Type: number | undefined

# toSnakeCase(str) → {string}

Transforms a string value into one which is separated by underscores. Whitespace and hyphens are replaced with underscores, and uppercase letters are interpreted as boundaries for new underscore-separated words.

Parameters:

Name	Type	Description
`str`	`string`	A string which may contain uppercase characters or hyphens

View Source toSnakeCase.js, line 1

Returns:

A new string that is an lowercase representation of the original string

Type: string

# toTitleCase(str) → {string}

Transforms a string value into one which is title-cased. The first letter of any word is capitalized.

Parameters:

Name	Type	Description
`str`	`string`	A string which may contain uppercase characters

View Source toTitleCase.js, line 1

Returns:

A new string that is an lowercase representation of the original string

Type: string

# toUpperCase(str) → {string}

Simple wrapper around String.prototype.toUpperCase() that is provided for consistency with the non-native string case methods (toKebabCase(), toCamelCase(), etc)

Parameters:

Name	Type	Description
`str`	`string`	A string which may contain lowercase characters

View Source toUpperCase.js, line 1

Returns:

A new string that is an uppercase representation of the original string

Type: string

# toUriEncoded(obj) → {string}

Transforms an object's key/value pairs into an encoded URI string, delimited by ampersands &

Parameters:

Name	Type	Description
`obj`	`object`	An object whose key/value pairs need to be serialized into a single string.

View Source toUriEncoded.js, line 4

Returns:

A new string that represents the key/value pairs on the originating object

Type: string

# uniq(list) → {Array.<*>}

Filters an array of values down to only those which are unique

Parameters:

Name	Type	Description
`list`	`Array.<*>`	An array of values which may or may not contain duplicates

View Source uniq.js, line 3

Returns:

A new list containing only the unique values from the original array

Type: Array.<*>

# uniqBy(pred, list) → {Array.<*>}

Filters an array of values down to only those which are unique, based on a provided predicate function (or shorthand for retrieving a prop inside an object)

Parameters:

Name	Type	Description
`pred`	`function` \| `string`	A predicate function
`list`	`Array.<*>`	An array of values which may or may not contain duplicates

View Source uniqBy.js, line 4

Returns:

A new list containing only the unique values from the original array

Type: Array.<*>

# unthunk(thunk) → {function}

Transforms a thunk (of however many levels deep) into a single function that will received all the args at once

Parameters:

Name	Type	Description
`thunk`	`function`	A function that returns a function (which may return a function, and so on)

View Source unthunk.js, line 1

Returns:

A single function that is ready to receive all the arguments at once

Type: function

# validate(validations, values) → {object}

Applies many validations to an object of values. Those validations are written as Arrays of pairs:

for the value at the first index supply your validation function that must pass
for the value at the second index supply a corresponding error message (OR function returning an error message) should the validation fail.

If you do not supply a validation error message, a default one will be built that looks like: "${val}" is not valid for "${key}"

And of course, you can write your validation error message as a function that will receive the value and key name as its first and second params (you should return a message as a string).

If you do not supply valid input (Array of validator function and validation error message), rather than throwing an error it will be replaced with a validation function that always returns false and a corresponding error message of: Validations for "${key}" are broken

Parameters:

Name	Type	Description
`validations`	`Array.<function()>`	An array of validator functions and their corresponding error message
`values`	`object`	An Object of key value pairs, the keys should correspond to validators and the values are that which is to be validated

View Source validate.js, line 85

Returns:

An object containing the key names of the values and one or more validation error messages (Only key names whose values were found to be invalid will show up on this output Object; an empty Object means everything was valid)

Type: object

Example

validate(isRequired, val)
validate([isRequired, 'field is required'], val)
validate([
  [isRequired, (_, key) => `${key} is required`],
  [isValidThing, val => `${val} is not a valid thing`],
  [mustBeBlue, 'Your favorite color must be blue'],
  [functionalOrObjectOriented]
], val)

# values(obj) → {Array.<*>}

A simple polyfill for Object.values()

Parameters:

Name	Type	Description
`obj`	`object`	An Object whose values need to be retrieved

View Source values.js, line 3

Returns:

A list of all the values in the provided Object, ordered by keys

Type: Array.<*>

Vanillas

Methods

# any(pred, arr) → {boolean}

Parameters:

# append(firstVal, secondVal) → {Array.<*>|object|string}

Parameters:

# assign(obj) → {object}

Parameters:

# clone(obj) → {object|Array.<*>}

Parameters:

# combine(val1, val2) → {*}

Parameters:

# compose() → {function}

Parameters:

# concat(firstArr, secondArr) → {Array.<*>}

Parameters:

# cond(conditionalTransforms, val) → {*}

Parameters:

# contains(val, arr) → {boolean}

Parameters:

# converge(fn) → {function}

Parameters:

# convergeZip(fn) → {function}

Parameters:

# curry(fn) → {function}

Parameters:

# curryN(arity, fn) → {function}

Parameters:

# difference(arr1, arr2) → {Array.<string>|Array.<number>}

Parameters:

# each(fn, arr)

Parameters:

# eitherOr(fnA, fnB, val) → {*}

Parameters:

# entries(obj) → {Array.<string>}

Parameters:

# escapeHtml(val) → {string}

Parameters:

# filter(fn, val) → {object|Array.<*>|string}

Parameters:

# filterObject(fn, obj) → {object}

Parameters:

# filterString(fn, str) → {string}

Parameters:

# find(pred, arr) → {*}

Parameters:

# findIndex(pred, arr) → {number}

Parameters:

# first(val) → {*}

Parameters:

# flatten(arr) → {Array.<*>}

Parameters:

# flipKeyValues(obj) → {object}

Parameters:

# forIn(fn, obj)

Parameters:

# fuzzy(propFn, needle, caseSensitiveopt, arr) → {Array.<string>|Array.<object>}

Parameters:

# getType(val) → {string}

Parameters:

# has(key, obj) → {boolean}

Parameters:

# hasNestedProp(prop, obj) → {boolean}

Parameters:

# identity(v) → {*}

Parameters:

# intersection(arr1, arr2) → {Array.<string>|Array.<number>}

Parameters:

# is(ofType, val) → {boolean}

Parameters:

Example

# isArrayish(val) → {boolean}

Parameters:

# isBlankString(val) → {boolean}

Parameters:

# isEmpty(val) → {boolean}

Parameters:

# isEqual(firstVal, secondVal) → {boolean}

Parameters:

# isInteger(val) → {boolean}