@hat-core/util

Utility library for manipulation of JSON data.

Main characteristics:

  • input/output data types are limited to JSON data, functions and undefined (sparse arrays and complex objects with prototype chain are not supported)
  • functional API with curried functions (similar to ramdajs)
  • implementation based on natively supported browser JS API
  • scope limited to most used functions in hat projects
  • usage of paths instead of lenses

TODO: define convetion for naming arguments based on their type and semantics

Source:

Methods

(static) append(val, arr) → {Array}

Source:

Append value to end of array (curried function)

Parameters:
Name Type Description
val *
arr Array
Returns:
Type
Array

(static) change(path, fn, x) → {*}

Source:

Change value referenced with path by appling function (curried function)

Parameters:
Name Type Description
path Path
fn function
x *
Returns:
Type
*

(static) clone(x) → {*}

Source:

Create new deep copy of input value.

In case of Objects or Arrays, new instances are created with elements obtained by recursivly calling clone in input argument values.

Parameters:
Name Type Description
x *

value
Returns:

copy of value

Type
*

(static) concat(x, y) → {Array}

Source:

Concatenate two arrays (curried function)

Parameters:
Name Type Description
x Array
y Array
Returns:
Type
Array

(static) contains(val, x) → {Boolean}

Source:

Check if array contains value (curried function)

TODO: add support for objects (should we check for keys or values?)

Parameters:
Name Type Description
val *
x Array | Object
Returns:
Type
Boolean

(static) curry(fn) → {function}

Source:

Curry function with fixed arguments lenth

Function arity is determined based on function's length property.

Parameters:
Name Type Description
fn function
Returns:
Type
function

(static) dec(val) → {Number}

Source:

Decrement value

Parameters:
Name Type Description
val Number
Returns:
Type
Number

(static) delay(fn, topt, args) → {Promise}

Source:

Delay function call fn(...args) for t milliseconds

TODO: move to other module

Parameters:
Name Type Attributes Default Description
fn function
t Number <optional>
 0
args *
Returns:
Type
Promise

(static) equals(x, y) → {Boolean}

Source:

Deep object equality (curried function)

Parameters:
Name Type Description
x *
y *
Returns:
Type
Boolean

(static) filter(fn, arr) → {Array}

Source:

Change array to contain only elements for which function returns true (curried function)

Parameters:
Name Type Description
fn function
arr Array
Returns:
Type
Array

(static) find(fn, x) → {*}

Source:

Find element in array or object for which provided function returns true (curried function)

Until element is found, provided function is called for each element with arguments: current element, current index/key and initial container.

If searched element is not found, undefined is returned.

Parameters:
Name Type Description
fn function
x Array | Object
Returns:
Type
*

(static) findIndex(fn, x) → {*}

Source:

Find element's index/key in array or object for which provided function returns true (curried function)

Until element is found, provided function is called for each element with arguments: current element, current index/key and initial container.

If searched element is not found, undefined is returned.

Parameters:
Name Type Description
fn function
x Array | Object
Returns:
Type
*

(static) flap(…fns) → {function}

Source:

Apply list of functions to same arguments and return list of results

Parameters:
Name Type Attributes Description
fns function <repeatable>

functions
Returns:
Type
function

(static) flatten(arr) → {Array}

Source:

Flatten nested arrays.

Create array with same elements as in input array where all elements which are also arrays are replaced with elements of resulting recursive application of flatten function.

If argument is not an array, function returns the argument encapsulated in an array.

Parameters:
Name Type Description
arr *
Returns:
Type
Array

(static) fromPairs(arr) → {Object}

Source:

Convert array of key, value pairs to object

Parameters:
Name Type Description
arr Array
Returns:
Type
Object

(static) get(path, x) → {*}

Source:

Get value referenced by path (curried function)

If input value doesn't contain provided path value, undefined is returned.

Parameters:
Name Type Description
path Path
x *
Returns:
Type
*

(static) identity(x) → {*}

Source:

Identity function returning same value provided as argument.

Parameters:
Name Type Description
x *

input value
Returns:

same value as input

Type
*

(static) inc(val) → {Number}

Source:

Increment value

Parameters:
Name Type Description
val Number
Returns:
Type
Number

(static) insert(idx, val, arr) → {Array}

Source:

Insert value into array on specified index (curried function)

Parameters:
Name Type Description
idx Number
val *
arr Array
Returns:
Type
Array

(static) isArray(x) → {Boolean}

Source:

Check if value is Array.

For same argument, if this function returns true, functions isNil, isBoolean, isInteger, isNumber, isString, and isObject will return false.

Parameters:
Name Type Description
x *

input value
Returns:
Type
Boolean

(static) isBoolean(x) → {Boolean}

Source:

Check if value is Boolean.

For same argument, if this function returns true, functions isNil, isInteger, isNumber, isString, isArray and isObject will return false.

Parameters:
Name Type Description
x *

input value
Returns:
Type
Boolean

(static) isInteger(x) → {Boolean}

Source:

Check if value is Integer.

For same argument, if this function returns true, function isNumber will also return true.

For same argument, if this function returns true, functions isNil, isBoolean, isString, isArray and isObject will return false.

Parameters:
Name Type Description
x *

input value
Returns:
Type
Boolean

(static) isNil(x) → {Boolean}

Source:

Check if value is null or undefined.

For same argument, if this function returns true, functions isBoolean, isInteger, isNumber, isString, isArray and isObject will return false.

Parameters:
Name Type Description
x *

input value
Returns:
Type
Boolean

(static) isNumber(x) → {Boolean}

Source:

Check if value is Number.

For same argument, if this function returns true, function isInteger may also return true if argument is integer number.

For same argument, if this function returns true, functions isNil, isBoolean, isString, isArray and isObject will return false.

Parameters:
Name Type Description
x *

input value
Returns:
Type
Boolean

(static) isObject(x) → {Boolean}

Source:

Check if value is Object.

For same argument, if this function returns true, functions isNil, isBoolean, isInteger, isNumber, isString, and isArray will return false.

Parameters:
Name Type Description
x *

input value
Returns:
Type
Boolean

(static) isString(x) → {Boolean}

Source:

Check if value is String.

For same argument, if this function returns true, functions isNil, isBoolean, isInteger, isNumber, isArray, and isObject will return false.

Parameters:
Name Type Description
x Any

input value
Returns:
Type
Boolean

(static) length(arr) → {Number}

Source:

Array length

Parameters:
Name Type Description
arr Array
Returns:
Type
Number

(static) map(fn, x) → {Array|Object}

Source:

Change array or object by appling function to it's elements (curried function)

For each element, provided function is called with element value, index/key and original container.

Parameters:
Name Type Description
fn function
x Array | Object
Returns:
Type
Array | Object

(static) merge(x, y) → {Object}

Source:

Merge two objects (curried function)

If same property exist in both arguments, second argument's value is used as resulting value

Parameters:
Name Type Description
x Object
y Object
Returns:
Type
Object

(static) mergeAll() → {Object}

Source:

Merge multiple objects (curried function)

If same property exist in multiple arguments, value from the last argument containing that property is used

Parameters:
Type Description
Array.<Object>
Returns:
Type
Object

(static) move(srcPath, dstPath, x) → {*}

Source:

Change by moving value from source path to destination path (curried function)

Parameters:
Name Type Description
srcPath Path
dstPath Path
x *
Returns:
Type
*

(static) not(val) → {Boolean}

Source:

Logical not

Parameters:
Name Type Description
val Any
Returns:
Type
Boolean

(static) omit(path, x) → {*}

Source:

Omitting value referenced by path (curried function)

Parameters:
Name Type Description
path Path
x *
Returns:
Type
*

(static) pick(arr, obj) → {Object}

Source:

Create object containing only subset of selected properties (curried function)

Parameters:
Name Type Description
arr Array
obj Object
Returns:
Type
Object

(static) pipe(…fns) → {function}

Source:

Pipe function calls

Pipe provides functional composition with reversed order. First function may have any arity and all other functions are called with only single argument (result from previous function application).

In case when no function is provided, pipe returns identity function.

Parameters:
Name Type Attributes Description
fns function <repeatable>

functions
Returns:
Type
function

(static) reduce(fn, val, x) → {*}

Source:

Reduce array or object by appling function (curried function)

For each element, provided function is called with accumulator, elements value, element index/key and original container.

Parameters:
Name Type Description
fn function
val *

initial accumulator value
x Array | Object
Returns:

reduced value

Type
*

(static) repeat(x, n) → {Array}

Source:

Create array by repeating same value (curried function)

Parameters:
Name Type Description
x *
n Number
Returns:
Type
Array

(static) reverse(arr) → {Array}

Source:

Reverse array

Parameters:
Name Type Description
arr Array
Returns:
Type
Array

(static) set(path, val, x) → {*}

Source:

Replace value referenced with path with another value (curried function)

Parameters:
Name Type Description
path Path
val *
x *
Returns:
Type
*

(static) sleep(t) → {Promise}

Source:

Create promise that resolves in t milliseconds

TODO: move to other module

Parameters:
Name Type Description
t Number
Returns:
Type
Promise

(static) slice(begin, end, arr) → {Array}

Source:

Get array slice (curried function)

Parameters:
Name Type Description
begin Number
end Number
arr Array
Returns:
Type
Array

(static) sort(fn, arr) → {Array}

Source:

Sort array (curried function)

Comparison function receives two arguments representing array elements and should return:

  • negative number in case first argument is more significant then second
  • zero in case first argument is equaly significant as second
  • positive number in case first argument is less significant then second
Parameters:
Name Type Description
fn function
arr Array
Returns:
Type
Array

(static) sortBy(fn, arr) → {Array}

Source:

Sort array based on results of appling function to it's elements (curried function)

Resulting order is determined by comparring function application results with greater then and lesser then operators.

Parameters:
Name Type Description
fn function
arr Array
Returns:
Type
Array

(static) strictParseFloat(value) → {Number}

Source:

Strictly parse floating point number from string

If provided string doesn't represent valid number, NaN is returned.

Parameters:
Name Type Description
value String
Returns:
Type
Number

(static) strictParseInt(value) → {Number}

Source:

Strictly parse integer from string

If provided string doesn't represent integer value, NaN is returned.

Parameters:
Name Type Description
value String
Returns:
Type
Number

(static) toPairs(obj) → {Array}

Source:

Convert object to array of key, value pairs

Parameters:
Name Type Description
obj Object
Returns:
Type
Array

(static) union(x, y) → {Array}

Source:

Create union of two arrays using equals to check equality (curried function)

Parameters:
Name Type Description
x Array
y Array
Returns:
Type
Array

(static) zip(arr1, arr2) → {Array}

Source:

Combine two arrays in single array of pairs

The returned array is truncated to the length of the shorter of the two input arrays.

Parameters:
Name Type Description
arr1 Array
arr2 Array
Returns:
Type
Array

Type Definitions

Path

Source:

Path can be an object property name, array index, or array of Paths

TODO: explain paths and path compositions (include examples)

Type:
  • String | Number | Array.<Path>