stunsail · Version

TIP!stunsail pairs nicely with param.macro, a Babel plugin for compile-time partial application & lambda parameters

allcollectionslogic v1.0.0

all(collection, fn)
expand signatures

Universal version of native Array#every that works on pretty much any iterable - Arrays & Array-likes, Objects, Sets, Maps, strings, custom iterables, etc.

Returns true if the result of fn is truthy for every item in the collection, or stops iteration early and returns false if some item causes fn to return a falsy value.

fn defaults to value => !!value so that collection can quickly be tested for truthiness throughout.

ARGUMENTS

name type description
collection object Iterable-like object to map over, applying fn on each iteration
fn Function Callback applied to each item in collection

RETURNS

boolean – whether all arguments satisified the condition

USAGE

all([1, 3, 5, 7], v => v < 10)
// -> true
all({ one: 1, two: 2, three: 3 }, v => v === 3)
// -> false

SEE ALSO

anycollectionslogic v1.0.0

any(collection, fn)
expand signatures

Universal version of native Array#some that works on pretty much any iterable - arrays & array-likes, objects, Sets, Maps, strings, custom iterables, etc.

Returns true if the result of fn is truthy for any item in the collection, or stops iteration early and returns false if some item causes fn to return a falsy value.

fn defaults to val => !!val so that collection can quickly be tested for truthiness throughout.

ARGUMENTS

name type description
collection object Iterable-like object to map over, applying fn on each iteration
fn Function Callback applied to each item in collection

RETURNS

boolean – whether any item satisifed the condition

USAGE

any({ one: 1, two: 2, three: 3 }, v => v === 3)
// -> true
any([1, 3, 5, 7], v => v > 10)
// -> false

SEE ALSO

applyfunctions v1.0.0

apply(fn, args)
expand signatures

Call fn using the array args as its arguments. Similar to native Function#apply() but does not set the function's this value.

ARGUMENTS

name type description
fn Function Function to which args will be applied
args array Array of arguments to apply to fn

RETURNS

any – result of applying args to fn

USAGE

apply(Math.max, [99, 5, 302])
// -> 302
const max = apply(Math.max)
max([1, 2, 100, 4])
// -> 100

camelCasestrings v1.0.0

camelCase(string)
expand signatures

Convert the given string to camelCase.

ARGUMENTS

name type description
string string Input string to convert to camel-case

RETURNS

string

USAGE

camelCase('A space separated string')
// -> 'aSpaceSeparatedString'
camelCase('snake_cased_thing')
// -> 'snakeCasedThing'
camelCase('alreadyCamelCased')
// -> 'alreadyCamelCased'

capfunctions v1.0.0

cap(fn)
expand signatures

Add a cap on the number of arguments passable to fn. Any arguments beyond limit will not be passed, which is useful for creating functions compatible with currying or as callbacks / parameters to higher order functions.

ARGUMENTS

name type description
fn Function Function whose arguments to limit
limit Number The number of arguments to allow (default = 1)

RETURNS

Function – new function accepting only limit arguments

USAGE

const log = cap(console.log, 2)
log(1, 2, 3)
// -> [ 1, 2 ]
;['1', '2.2', '2.54'].map(parseInt)
// -> [ 1, NaN, NaN ]
const toInt = cap(parseInt)
;['1', '2.2', '2.54'].map(toInt)
// -> [ 1, 2, 2 ]

clampnumbers v1.0.0

clamp(value, lower, upper)
expand signatures

Ensures that a number value is between bounds lower and upper.

If value is not a number it's assumed to be 0, while lower and upper are set to value when they aren't numbers (or aren't provided).

ARGUMENTS

name type description
value number The number to operate on
lower number Lower bound
upper number Upper bound

RETURNS

number – between lower & upper

USAGE

clamp(20, -10, 10)
// -> 10
clamp(-15, -10, 10)
// -> -10

countcollectionsstrings v1.0.0

count(collection, search, maxOccurrences)
expand signatures

Return the number of occurrences of search in collection, up to maxOccurrences if provided.

Numbers are checked for divisiblity, i.e. 4 can fit in 9 twice, so it could be said that there are 2 occurrences of 4 in 9.

Strings are treated as collections. All other primitives are checked for equality.

ARGUMENTS

name type description
collection any Collection in which to search
search any Value to search for
maxOccurrences number Max occurrences to search for (optional)

RETURNS

number – occurrences found

USAGE

count([1, 6, 6, 3], 6)
// -> 2
count('hello world', 'l')
// -> 3
count('hello world', 'l', 2)
// -> 2
count(new Set([1, 6, 6, 3]), 6)
// -> 1
count({ a: 'hello', b: 'hello' }, 'hello')
// -> 2
const map = new Map()
map.set('a', 5)
map.set('b', 5)
map.set('c', 10)
count(map, 5)
// -> 2

defaultsobjects v1.0.0

defaults(object, extension)
expand signatures

Sets own properties from extension on object if any of them are not present on object.

ARGUMENTS

name type description
object object Base object to extend
extension object Object containing default properties

RETURNS

object

USAGE

const base = { abc: '123', def: '456' }
const ext = { abc: '999', ghi: '789' }
const result = defaults(base, ext)
// -> { abc: '123', def: '456', ghi: '789' }

eachcollections v1.0.0

each(collection, fn)
expand signatures

Universal version of native Array#forEach that works on pretty much any iterable - arrays & array-likes, objects, Sets, Maps, strings, custom iterables, etc.

ARGUMENTS

name type description
collection Iterable Iterable-like object to iterate over
fn Function Called with each iteration

RETURNS

undefined

USAGE

each([1, 2, 3], v => console.log(v))
// -> 1 2 3
each('string', v => console.log(v))
// -> s t r i n g
each({ key: 'value', keyTwo: 'valueTwo' }, v => console.log(v))
// -> 'value' 'valueTwo'
each(new Set([1, 2, 3]), v => console.log(v))
// -> 1 2 3
const map = new Map()
map.set('keyOne', 'valueOne')
map.set('keyTwo', 'valueTwo')
each(map, v => console.log(v))
// -> 'value' 'valueTwo'
const obj = {
* [Symbol.iterator] () {
for (const n of [1, 2, 3]) {
yield n
}
}
}
each(obj, v => console.log(v))
// -> 1 2 3

filtercollections v1.0.0

filter(collection, fn)
expand signatures

Universal version of native Array#filter that works on pretty much any iterable - arrays & array-likes, objects, Sets, Maps, strings, custom iterables, etc.

fn is called with arguments value, key, collection. If the result is truthy, the element will be present in the resulting collection. If the result is falsy, it will be filtered.

ARGUMENTS

name type description
collection Iterable Iterable-like object from which to filter items
fn Function Predicate that decides whether to remove the item

RETURNS

any – same type as collection

USAGE

const object = { one: 1, two: 2, three: 3 }
filter(object, value => value % 2)
// -> { one: 1, three: 3 }
const array = [1, 2, 3, 4, 5]
filter(array, value => value % 2)
// -> [1, 3, 5]
filter('foobar', value => value !== 'o')
// -> fbar

firstcollections v1.0.0

first(collection)
expand signatures

Retrieve the item at index zero of the given array-like or Set object. For Sets this is based on insertion order, i.e. the first inserted object.

ARGUMENTS

name type description
arrayLike array Array-like value to access

RETURNS

any – first value of the given collection, i.e. array[0]

USAGE

first([1, 2, 3, 4])
// -> 1
first(new Set([1, 2, 3, 4]))
// -> 1
first((function () { return arguments }(1, 2, 3, 4)))
// -> 1

SEE ALSO

getobjects v1.0.0

get(object, path)
expand signatures

Access a property of object at path safely & deeply, returning undefined if it doesn't exist.

ARGUMENTS

name type description
object object Object-like value to access
path string | string[] String using dot or bracket syntax, or an array of path segments

RETURNS

any

USAGE

const object = { attributes: { flammable: true } }
get(object, 'attributes.toxic')
// -> undefined
get(object, 'attributes.flammable')
// -> true
const objectTwo = { array: [1, 2, 3] }
// these are equivalent
get(objectTwo, 'array[2]')
get(objectTwo, 'array.2')
// -> 2
get(objectTwo, 'array[3]')
// -> undefined

SEE ALSO

getOrobjects v1.0.0

getOr(object, path, defaultValue)
expand signatures

Access a property of object at path safely & deeply, returning defaultValue if it doesn't exist.

ARGUMENTS

name type description
object object Object-like value to access
path string | string[] String using dot or bracket syntax, or an array of path segments
defaultValue any Value to return if path resolves to nil

RETURNS

any

USAGE

const object = { attributes: { flammable: true } }
getOr(object, 'attributes.toxic', false)
// -> false
getOr(object, 'attributes.flammable', false)
// -> true
const objectTwo = { array: [1, 2, 3] }
// these are equivalent
getOr(objectTwo, 'array[2]', 'item three')
getOr(objectTwo, 'array.2', 'item three')
// -> 2
getOr(objectTwo, 'array[3]', 'item four')
// -> 'item four'

SEE ALSO

getTypetypes v1.0.0

getType(value)
expand signatures

Alternative to the builtin typeof operator that returns a more accurate type string.

ARGUMENTS

name type description
value any

RETURNS

string

USAGE

getType('hi!')
// -> string
getType({})
// -> object
getType([])
// -> array
getType(null)
// -> null
getType(new RangeError())
// -> rangeerror

SEE ALSO

hasobjects v1.0.0

has(object, path)
expand signatures

Alternative to the builtin Object#hasOwnProperty function with support for deep-property access using both dot and bracket syntax.

ARGUMENTS

name type description
object object Object-like value to access
path string | string[] String using dot or bracket syntax, or an array of path segments

RETURNS

boolean

USAGE

const object = { attributes: { flammable: true } }
has('attributes.flammable', object)
// -> true
const objectTwo = { array: [1, 2, 3] }
// these are equivalent
has(objectTwo, 'array[2]')
has(objectTwo, 'array.2')
// -> true
has(objectTwo, 'array[3]')
// -> false

SEE ALSO

includescollections v1.0.0

includes(value, collection)
expand signatures

Check whether value is included in collection. This is a version of isOneOf() with the arguments flipped.

ARGUMENTS

name type description
collection object List to check value against
value any Value to search for in collection

RETURNS

boolean

USAGE

includes([1, 2, 3], 2)
// -> true
includes({ key: 'value' }, 'value')
// -> true

SEE ALSO

invariantlogic v1.0.0

invariant(condition, message)
expand signatures

Test that condition is truthy and return its value, or throw an error with message when it is falsy.

message defaults to 'Invariant Violation'.

ARGUMENTS

name type description
condition any Value to test
message string Message thrown with the error when condition is falsy

RETURNS

any

USAGE

const truthyCondition = () => {}
const result1 = invariant(truthyCondition, 'No function provided.')
// -> () => {}
const falsyCondition = null
const result2 = invariant(truthyCondition, 'No function provided.')
// -> InvariantError: 'No function provided.'

isEqualtypeslogic v1.0.0

isEqual(a, b)
expand signatures

Check whether two values a and b are deeply equal. Works on almost any object - including plain objects, arrays, Maps, Sets, and Dates.

ARGUMENTS

name type description
a any
b any

RETURNS

boolean

USAGE

isEqual({}, {})
// -> true
isEqual(new Set([1, 2, 3]), new Set([1, 2, 3]))
// -> true
isEqual(new Set([1, 2]), new Set([9, 10]))
// -> false

isArraytypeslogic v1.0.0

isArray(value)
expand signatures

Check whether value is an array, like the built-in Array.isArray() method.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isArray([1, 2, 3])
// -> true
isArray({ length: 2, 0: 'foo', 1: 'bar' })
// -> false

isArrayLiketypeslogic v1.0.0

isArrayLike(value)
expand signatures

Check whether value is an array or an object with a length property and that it also has a property at length - 1.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isArrayLike([1, 2, 3])
// -> true
isArrayLike(null)
// -> false
isArrayLike('foobar')
// -> true
isArrayLike({ length: 2 })
// -> false
isArrayLike({ length: 2, 0: 'foo', 1: 'bar' })
// -> true

isBooleantypeslogic v1.0.0

isBoolean(value)
expand signatures

Check whether value is a boolean.

ARGUMENTS

name type description
value any Value to test

RETURNS

any

USAGE

isBoolean(true)
// -> true
isBoolean(false)
// -> true
isBoolean(0)
// -> false

isBuffertypeslogic v1.0.0

isBuffer(value)
expand signatures

Check whether value is a Buffer.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isBuffer(Buffer.from('string'))
// -> true
isBuffer('string')
// -> false

isDatetypeslogic v1.0.0

isDate(value)
expand signatures

Check whether value is a Date instance.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isDate(new Date())
// -> true
isDate(Date.now())
// -> false

isEmptytypeslogic v1.0.0

isEmpty(value)
expand signatures

Check whether value is an empty version of its type, i.e. {} for objects, [] for arrays, etc.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

// examples of `true` cases:
isEmpty({})
isEmpty([])
isEmpty(null)
isEmpty('')
isEmpty(' \t \n')
// examples of `false` cases:
isEmpty({ property: 'hello' })
isEmpty([1, 2, 3])
isEmpty(() => {})
isEmpty('a value')

isErrortypeslogic v1.0.0

isError(value)
expand signatures

Check whether value is a built-in Error type.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isError(new Error('did a bad thing'))
// -> true
isError(new TypeError('wrong kind of thing'))
// -> true
isError({ code: 'ENOENT', message: 'wrong' })
// -> false

isFunctiontypeslogic v1.0.0

isFunction(value)
expand signatures

Check whether value is a function.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

// examples of `true` cases:
isFunction(Function)
isFunction(() => {})
isFunction(async () => {})
isFunction(function () {})
isFunction(function * () {})
// examples of `false` cases:
isFunction(false)
isFunction('')
isFunction([])
isFunction({})
isFunction(new Map())
isFunction(new Set())
isFunction(new Date())
isFunction(null)
isFunction(undefined)
isFunction(1)

isInRangetypeslogic v1.0.0

isInRange(value, start, end)
expand signatures

Check whether value is between start and end, inclusively.

ARGUMENTS

name type description
value number Value to test
start number Lower boundary
end number Upper boundary

RETURNS

boolean

USAGE

isInRange(20, 0, 40)
// -> true
isInRange(-10, 0, 40)
// -> false
isInRange(10, 0, 10)
// -> true

SEE ALSO

isIterabletypeslogic v1.0.0

isIterable(value)
expand signatures

Check whether value is an iterable object, i.e. its [Symbol.iterator] property is set as a function.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isIterable([])
// -> true
isIterable({})
// -> false
isIterable(new Set())
// -> true
isIterable(new Map())
// -> true
isIterable({ [Symbol.iterator] () {} })
// -> true
isIterable(null)
// -> false

isMaptypeslogic v1.0.0

isMap(value)
expand signatures

Check whether value is a Map object.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isMap(new Map())
// -> true
isMap({})
// -> false

isNantypeslogic v1.0.0

isNan(value)
expand signatures

Check whether value is NaN.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isNan(NaN)
// -> true
isNan(40)
// -> false
isNan('string')
// -> false
isNan({})
// -> false

isNiltypeslogic v1.0.0

isNil(value)
expand signatures

Check whether value is null or undefined.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isNil(null)
// -> true
isNil(undefined)
// -> true
isNil(false)
// -> false

isNumbertypeslogic v1.0.0

isNumber(value)
expand signatures

Check whether value is a number.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isNumber(4)
// -> true
isNumber(NaN)
// -> false

isNumerictypeslogicstringsnumbers v1.0.0

isNumeric(value)
expand signatures

Check whether value is a number or a string that appears to be a number, including integers & decimals in strings.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

// examples of `true` cases:
isNumeric(1)
isNumeric(1.343)
isNumeric(Infinity)
isNumeric('1')
isNumeric('1.6')
isNumeric('943034.3923')
// examples of `false` cases:
isNumeric(false)
isNumeric([])
isNumeric({})
isNumeric(new Map())
isNumeric(new Set())
isNumeric(new Date())
isNumeric(NaN)
isNumeric(null)
isNumeric(undefined)

isObjecttypeslogic v1.0.0

isObject(value)
expand signatures

Check whether value is a plain object.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isObject({})
// -> true
isObject(() => {})
// -> false
isObject(new Map())
// -> false

isOneOfcollections v1.0.0

isOneOf(value, collection)
expand signatures

Check whether value is included in collection. This is a version of includes() with the arguments flipped.

ARGUMENTS

name type description
value any Value to search for in collection
collection object List to check value against

RETURNS

boolean

USAGE

isOneOf(2, [1, 2, 3])
// -> true
isOneOf('value', { key: 'value' })
// -> true

SEE ALSO

isPrimitivetypeslogic v1.0.0

isPrimitive(value)
expand signatures

Check whether value is a primitive, i.e. one of:

  • null
  • string
  • number
  • boolean
  • undefined

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

// examples of `true` cases:
isPrimitive(null)
isPrimitive('string')
isPrimitive(4)
isPrimitive(true)
isPrimitive(undefined)
// examples of `false` cases:
isPrimitive({})
isPrimitive([])
isPrimitive(new Date())

isSettypeslogic v1.0.0

isSet(value)
expand signatures

Check whether value is a Set object.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isSet(new Set())
// -> true
isSet([])
// -> false

isStringtypeslogic v1.0.0

isString(value)
expand signatures

Check whether value is a string.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isString('something here')
// -> true
isString(400)
// -> false

isSubsetobjectslogic v1.0.0

isSubset(superset, subset)
expand signatures

Check if a given object is a subset of another, recursively.

This differs from matches, which will check that the given properties of one object are deeply equal to those same properties in another — without the recursive partial behavior.

ARGUMENTS

name type description
superset object Object to compare with subset
subset object Object containing properties to match

RETURNS

boolean

USAGE

const path = {
id: 100,
label: "greeting",
node: {
kind: "string",
value: "hello"
}
}
isSubset(path, { label: "greeting" })
// -> true
isSubset(path, { node: { value: "hello" } })
// -> true
isSubset(path, { node: { kind: "number" } })
// -> false

SEE ALSO

isThenabletypeslogic v1.0.0

isThenable(value)
expand signatures

Check whether value is an object with a then method.

ARGUMENTS

name type description
value any Value to test

RETURNS

boolean

USAGE

isThenable(Promise.resolve())
// -> true
isThenable({ then () {} })

isTypetypeslogic v1.0.0

isType(value, type)
expand signatures

If type is a string, check whether value has that type. Other kinds will check that the types of type and value match.

ARGUMENTS

name type description
value any Value to test
type any Type string or a value whose type will be checked against that of value

RETURNS

boolean

USAGE

isType('bar', 'string')
// -> true
isType('3', 'number')
// -> false
isType(new Date(), Date)
// -> true

SEE ALSO

kebabCasestrings v1.0.0

kebabCase(string)
expand signatures

Convert the given string to kebab-case.

ARGUMENTS

name type description
string string Input string to convert to kebab-case

RETURNS

string

USAGE

kebabCase('A space separated string')
// -> 'a-space-separated-string'
kebabCase('camelCasedThing')
// -> 'camel-cased-thing'
kebabCase('already-kebab-cased')
// -> 'already-kebab-cased'

lastcollections v1.0.0

last(collection)
expand signatures

Retreive the item at the highest index of the given array-like or Set object. For Sets this is based on insertion order, i.e. the last inserted object.

ARGUMENTS

name type description
arrayLike array Array-like value to access

RETURNS

any – last value of the given collection, i.e. array[array.length - 1]

USAGE

last([1, 2, 3, 4])
// -> 4
last(new Set([1, 2, 3, 4]))
// -> 4
last((function () { return arguments }(1, 2, 3, 4)))
// -> 4

SEE ALSO

matchesobjectslogic v1.0.0

matches(object, compare)
expand signatures

Check that all properties of compare are deeply equal to those same properties of object.

This differs from isSubset, which will recurse into an object's properties to check whether they are subsets of those same paths in another object.

ARGUMENTS

name type description
object object Object on which to check for properties of compare
compare object Object containing properties to match

RETURNS

boolean

USAGE

const wishy = { name: 'wishy', color: 'green' }
matches(wishy, { color: 'green' })
// -> true
const washy = { name: 'washy', color: 'red' }
matches(washy, { color: 'blue' })
// -> false
const arr = [
{ name: 'willy', color: 'red' },
{ name: 'wally', color: 'red' },
{ name: 'dopey', color: 'brown' },
{ name: 'wishy', color: 'blue' },
{ name: 'washy', color: 'green' }
]
arr.find(o => matches(o, { color: 'green' })
// -> { name: 'washy', color: 'green' }
arr.find(o => matches(o, { color: 'brown' })
// -> { name: 'dopey', color: 'brown' }
arr.find(o => matches(o, { color: 'red' })
// -> { name: 'willy', color: 'red' }

SEE ALSO

oncefunctions v1.0.0

once(fn)
expand signatures

Return a wrapped version of fn that is only able to execute a single time. Further calls to the wrapped function will return the value from the original call.

ARGUMENTS

name type description
fn Function Function to wrap so that it only executes a single time

RETURNS

Function

USAGE

function expensive (someNumber) {
return someNumber
}
const wrapped = once(expensive)
wrapped(100)
// -> 100
wrapped(93247593475)
// -> 100

partitioncollections v1.0.0

partition(collection, fn)
expand signatures

Iterate over collection and apply fn to each item, returning an array where the first element contains all items for which fn returned a truthy value, and the second element contains all items for which it returned a falsy value.

ARGUMENTS

name type description
collection object Object-like value to split
fn Function Predicate with which to split items

RETURNS

[truthy, falsy]

USAGE

partition([true, false, true, false], v => v === true)
// -> [[true, true], [false, false]]
partition({ keyOne: true, keyTwo: false }, v => v === true)
// -> [{ keyOne: true }, { keyTwo: false }]
partition('some arbitrary string', v => v === ' ')
// -> [' ', 'somearbitrarystring']
partition(new Map([['keyOne', true], ['keyTwo', false]]), v => v === true)
// -> [ Map {'keyOne' => true}, Map {'keyTwo' => false} ]
partition(new Set(['Joe', 'Jerry', 'Rick', 'Bob']), v => v.startsWith('J'))
// -> [ Set {'Joe', 'Jerry'}, Set {'Rick', 'Bob'} ]

pathDotsutilities v1.0.0

pathDots(value)
expand signatures

Converts arrays of object path segments into dot-notated paths. If value is a string, brackets will be normalized to dots.

ARGUMENTS

name type description
value string | string[] String using dot or bracket syntax, or an array of path segments

RETURNS

boolean

USAGE

pathDots(['a', 'b', 'c', '0'])
// -> 'a.b.c.0'
pathDots('a[1].b.c[0]')
// -> 'a.1.b.c.0'

SEE ALSO

pathLinksutilities v1.0.0

pathLinks(value)
expand signatures

Convert value (a dot or bracket notated string) to an array of object path segments. If it's already an array it will just be returned.

ARGUMENTS

name type description
value string | string[] String using dot or bracket syntax, or an array of path segments

RETURNS

boolean

USAGE

pathLinks('a[1].b.c[0]')
// -> ['a', '1', 'b', 'c', '0']
pathLinks(['a', 'b', 'c', '0'])
// -> ['a', 'b', 'c', '0']

SEE ALSO

pipeasyncfunctions v1.0.0

pipe(a, b)
expand signatures

Run a set of functions in series using the output of each as the input to the next. The first value is allowed to be of any kind - if it is not a function it is simply passed as the argument to the second item. Subsequent non-function items are ignored.

Because pipe handles Promise-returning functions, it will always return a Promise in order to maintain a consistent API even if all given functions & values are synchronous.

ARGUMENTS

name type description
...inputs Function[] Set of functions to pipe through

RETURNS

Promise

USAGE

pipe(
'hello',
str => str.toUpperCase(),
str => str.split('').join('-')
).then(result => {
console.log(result)
// -> 'H-E-L-L-O'
})
async function getUserData (name) {
return { name, favoriteColor: 'blue' }
}
pipe(
name => getUserData(name),
user => user.favoriteColor === 'blue'
).then(result => {
console.log(result)
// -> true
})

randomnumberscollections v1.0.0

random(value, bound)
expand signatures

If value is an array or object, return a random value. If it's a number and bound is absent, return a random number between 0 and value. If bound is provided, return a random value between value and bound.

ARGUMENTS

name type description
value array | object | number Collection to sample or a bounding number
bound number Used as the upper bound when value is a number

RETURNS

any

USAGE

random([1, 2, 3])
// -> randomly chosen element from the array
random({ one: 1, two: 2, three: 3 })
// -> value from a randomly chosen key in the object
random(10)
// -> randomly chosen number between 0 and 10
random(-5, 5)
// -> randomly chosen number between -5 and 5

rangenumbers v1.0.0

range(...args)
expand signatures

Create an array of numbers beginning at and including start through and including end.

If step is provided, it is used as the increment between each element of the resulting array. This can affect the number of values in the result.

ARGUMENTS

name type description
start number Value at which to start the range
end number Value at which to end the range
step number Increment between each element

RETURNS

number[]

USAGE

range(0, 10)
// -> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
range(0, 10, 2)
// -> [0, 2, 4, 6, 8, 10]

SEE ALSO

reducecollections v1.0.0

reduce(collection, fn, initial)
expand signatures

Universal version of native Array#reduce that works on pretty much any iterable - arrays & array-likes, objects, Sets, Maps, strings, custom iterables, etc.

ARGUMENTS

name type description
collection Iterable Iterable-like object to reduce from
fn Function Function that builds the accumulator with each iteration
initial any Value first passed to fn

RETURNS

any

USAGE

let collection = { one: 1, two: 2, three: 3 }
reduce(collection, (acc, cur) => acc + cur, 0)
// -> 6
collection = [1, 2, 3, 4, 5]
reduce(collection, (acc, cur) => acc + cur, 0)
// -> 15
collection = 'foobar'
fn(collection, (acc, cur) => {
acc.splice(0, 0, cur)
return acc
}, [])
// -> ['r', 'a', 'b', 'o', 'o', 'f']

SEE ALSO

reduceWhilecollections v1.0.0

reduceWhile(collection, predicate, fn, initial)
expand signatures

Works just like reduce but short-circuits when predicate returns a falsy value.

ARGUMENTS

name type description
collection Iterable Iterable-like object to reduce from
predicate Function Function that will stop iteration when returning a falsy value
fn Function Function that builds the accumulator with each iteration
initial any Value first passed to fn

RETURNS

any

USAGE

const predicate = accumulator => accumulator !== 3
const reducer = (acc, cur) => acc + cur
const object = { one: 1, two: 2, three: 3 }
reduce(object, reducer, 0)
// -> 6
reduceWhile(object, predicate, reducer, 0)
// -> 3

SEE ALSO

sleepasyncutilities v1.0.0

sleep(ms)
expand signatures

Similar to the built-in setTimeout but does not receive a function to run when the time expires. Simply returns a Promise that resolves after ms. Pairs well with await.

ARGUMENTS

name type description
ms number Amount of time to wait

RETURNS

any

USAGE

async function foo () {
console.log('start')
await sleep(5000)
console.log('done')
}
foo()
// -> start
// ... 5 seconds pass ...
// -> done

snakeCasestrings v1.0.0

snakeCase(string)
expand signatures

Convert the given string to snake_case.

ARGUMENTS

name type description
string string Input string to convert to snake-case

RETURNS

string

USAGE

snakeCase('A space separated string')
// -> 'a_space_separated_string'
snakeCase('camelCasedThing')
// -> 'camel_cased_thing'
snakeCase('already_snake_cased')
// -> 'already_snake_cased'

mapcollections v1.0.0

map(collection, fn)
expand signatures

Universal version of native Array#map that works on pretty much any iterable - arrays & array-likes, objects, Sets, Maps, strings, custom iterables, etc.

The return value will be collection but each value will be the result of applying fn at each iteration to the arguments value, key, collection.

ARGUMENTS

name type description
collection object Iterable-like object to map over, applying fn on each iteration
fn Function Callback applied to each item in collection

RETURNS

any – same type as collection

USAGE

map({ one: 1, two: 2, three: 3 }, v => v + 1)
// -> { one: 2, two: 3, three: 4 }
map([1, 3, 5, 7], v => v * -1)
// -> [-1, -3, -5, -7]
map('foobar', v => v + '-')
// -> 'f-o-o-b-a-r-'

setobjects v1.0.0

set(object, path, value)
expand signatures

Sets the key at path to value on object and returns the object. Deep property access is supported using both dot and bracket syntax or an array of path segments.

ARGUMENTS

name type description
object object Object-like value to access
path string | string[] String using dot or bracket syntax, or an array of path segments
value any Value to which path will be set

RETURNS

object

USAGE

const object = { key: 'value', nested: { inner: { deep: 'thing' } } }
set(object, 'nested.inner.deep', 40)
// -> { key: 'value', nested: { inner: { deep: 40 } } }

SEE ALSO

textCasestrings v1.0.0

textCase(string)
expand signatures

Convert the given string to text case.

ARGUMENTS

name type description
string string Input string to convert to text-case

RETURNS

string

USAGE

textCase('snake-cased-string')
// -> 'snake cased string'
textCase('camelCasedThing')
// -> 'camel cased thing'
textCase('already text cased')
// -> 'already text cased'

toArrayutilitiescollections v1.0.0

toArray(value, begin, end)
expand signatures

Alternative to the [].slice.call() method of converting values to arrays. It will convert array-like objects and wrap values in an array that don't coerce.

ARGUMENTS

name type description
value any Value to convert
begin Number Optional index at which to begin a slice
end Number Optional index at which to end a slice

RETURNS

any

USAGE

toArray(undefined)
// -> []
toArray(null)
// -> [null]
toArray((function () { return arguments })(1, 2, 3))
// -> [1]
toArray(4)
// -> [4]
toArray(true)
// -> [true]
toArray(false)
// -> [false]
toArray({})
// -> [{}]
toArray([])
// -> []
toArray([1, 2, 3, 4, 5], 2)
// -> [3, 4, 5]
toArray([1, 2, 3, 4, 5], 2, -1)
// -> [3, 4]

toBooleanutilitieslogic v1.0.0

toBoolean(value, smart)
expand signatures

Return a boolean based on value - the usual falsy values and empty values will return false, while truthy values return true.

When smart is true and value is a string, it will be checked for the strings 'true' and 'false' and coerced to a boolean accordingly.

ARGUMENTS

name type description
value any Value to convert
smart boolean Whether to coerce value based on strings 'true' or 'false'

RETURNS

boolean

USAGE

// examples of `true` cases:
toBoolean(true)
toBoolean(1)
toBoolean('true')
toBoolean('false')
toBoolean(new Date())
toBoolean({ one: 1 })
toBoolean([1, 2, 3])
// examples of `false` cases:
toBoolean(false)
toBoolean(null)
toBoolean(undefined)
toBoolean('')
toBoolean(0)
toBoolean({})
toBoolean([])

toEmptyutilities v1.0.0

toEmpty(type)
expand signatures

Return an empty value matching the kind supplied by type, which is either a string representing its kind or any object.

ARGUMENTS

name type description
type ``

RETURNS

any

USAGE

toEmpty('array')
// -> []
toEmpty('object')
// -> {}
toEmpty('boolean')
// -> false
toEmpty(null)
// -> null
toEmpty([1, 2, 3, 4])
// -> []

toNumberutilitiesnumbers v1.0.0

toNumber(value, round)
expand signatures

Convert the given value to a number. For example, this function applied to a collection of almost any kind will return the number of elements in the collection.

ARGUMENTS

name type description
value any Value to convert
round boolean Whether to round the output to an integer

RETURNS

number

USAGE

toNumber(1)
// -> 1
toNumber(1.3345)
// -> 1.3345
const now = new Date
toNumber(now) === now.valueOf()
// -> true
toNumber({ one: 1, two: 2 })
// -> 2
toNumber([1, 2, 3])
// -> 3
toNumber('string')
// -> 6
toNumber(39.354, true)
// -> 39

toObjectutilitiescollections v1.0.0

toObject(value)
expand signatures

Ensure an object is returned, by converting value if possible or by returning an empty object otherwise. If value is already an object it is simply returned. null & undefined will produce an empty object.

ARGUMENTS

name type description
value any Value to convert

RETURNS

object

USAGE

toObject(['one', 'two', 'three'])
// -> { one: 'one', two: 'two', three: 'three' }
toObject(3)
// -> { '3': 3 }
toObject(new Map([['keyOne', 'valueOne'], ['keyTwo', 'valueTwo']]))
// -> { keyOne: 'valueOne', keyTwo: 'valueTwo' }
toObject(true)
// -> { 'true': true }
toObject('fly')
// -> { 'fly': 'fly' }
toObject(null)
// -> { 'null': null }
toObject(undefined)
// -> { 'undefined': undefined }
toObject(new Date)
// -> {}

SEE ALSO

toObjectWithutilitiescollections v1.0.0

toObjectWith(value, fn)
expand signatures

Ensure an object is returned, by converting value if possible or by returning an empty object otherwise. If value is already an object it is simply returned. null & undefined will produce an empty object.

Works just like toObject, but receives a function that allows for transforming the values of the resulting object.

ARGUMENTS

name type description
value any Value to convert
fn Function Function accepting incoming elements and returning values of the output object

RETURNS

object

USAGE

toObjectWith(['one', 'two', 'three'], value => value)
// -> { one: 'one', two: 'two', three: 'three' }
toObjectWith(['one', 'two', 'three'], value => {
switch (value) {
case 'one': return [1]
case 'two': return [2]
case 'three': return [3]
}
})
// -> { one: [1], two: [2], three: [3] }

SEE ALSO