stunsail ·

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

all <T> (collection: T, fn: StringIterator<boolean>): boolean
all <T> (collection: T[], fn: ArrayIterator<T, boolean>): boolean
all <K, V> (collection: Map<K, V>, fn: MapIterator<K, V, boolean>): boolean
all <T> (collection: Set<T>, fn: SetIterator<T, boolean>): boolean
all <T> (collection: T, fn: ObjectIterator<T, boolean>): boolean

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

• any

anycollectionslogic v1.0.0

any(collection, fn)

expand signatures

any <T> (collection: T, fn: StringIterator<boolean>): boolean
any <T> (collection: T[], fn: ArrayIterator<T, boolean>): boolean
any <K, V> (collection: Map<K, V>, fn: MapIterator<K, V, boolean>): boolean
any <T> (collection: Set<T>, fn: SetIterator<T, boolean>): boolean
any <T> (collection: T, fn: ObjectIterator<T, boolean>): boolean

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

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

• all

applyfunctions v1.0.0

apply(fn, args)

expand signatures

apply <T, F> (fn: F, args: T[]): ReturnType<F>

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.

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

camelCase (string: string): string

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

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'

SEE ALSO

• kebabCase
• snakeCase
• textCase

capfunctions v1.0.0

cap(fn)

expand signatures

cap <F, T1> (fn: F): (arg: T1) => ReturnType<F>
cap <F> (fn: F, limit: 0): () => ReturnType<F>
cap <F, T1> (fn: F, limit: 1): (arg: T1) => ReturnType<F>
cap <F, T1, T2> (fn: F, limit: 2): (...args: [T1, T2]) => ReturnType<F>
cap <F, T1, T2, T3> (fn: F, limit: 3): (...args: [T1, T2, T3]) => ReturnType<F>
cap <F, T1, T2, T3, T4> (fn: F, limit: 4): (...args: [T1, T2, T3, T4]) => ReturnType<F>
cap <F, T1, T2, T3, T4, T5> (fn: F, limit: 5): (...args: [T1, T2, T3, T4, T5]) => ReturnType<F>
cap <F, T1, T2, T3, T4, T5, T6> (fn: F, limit: 6): (...args: [T1, T2, T3, T4, T5, T6]) => ReturnType<F>

ARGUMENTS

RETURNS

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

clamp (value: number, lower: number, upper: number): number

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

count <T> (collection: T, search: T, maxOccurrences: number): number
count <T> (collection: GenericCollection<T>, search: T): number

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

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

defaults <T> (object: T, extension: any): T
defaults <T, U> (object: T, extension: U): T & U

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.

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

each <T> (collection: T, fn: StringIterator<any>): void
each <T> (collection: T[], fn: ArrayIterator<T, any>): void
each <K, V> (collection: Map<K, V>, fn: MapIterator<K, V, any>): void
each <T> (collection: Set<T>, fn: SetIterator<T, any>): void
each <T> (collection: T, fn: ObjectIterator<T, any>): void

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

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

SEE ALSO

• filter
• map
• reduce

filtercollections v1.0.0

filter(collection, fn)

expand signatures

filter <T> (collection: string, fn: StringIterator<boolean>): string
filter <T, R> (collection: T[], fn: ArrayIterator<T, boolean>): R[]
filter <K, V, R> (collection: Map<K, V>, fn: MapIterator<K, V, boolean>): R
filter <T, R> (collection: Set<T>, fn: SetIterator<T, boolean>): Set<R>
filter <T, R> (collection: T, fn: ObjectIterator<T, boolean>): Partial<R>

ARGUMENTS

RETURNS

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

SEE ALSO

• each
• map
• reduce

firstcollections v1.0.0

first(collection)

expand signatures

first <T> (collection: ArrayLike<T> | Set<T>): T | undefined

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

• last

getobjects v1.0.0

get(object, path)

expand signatures

get <K, V> (object: Record<K, V>, path: string | PathLinks): V | undefined

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

• get
• getOr
• has

getOrobjects v1.0.0

getOr(object, path, defaultValue)

expand signatures

getOr <K, V> (object: Record<K, V>, path: string | PathLinks, defaultValue: V): V

ARGUMENTS

RETURNS

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

• get
• set
• has

getTypetypes v1.0.0

getType(value)

expand signatures

getType (value: unknown): 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

• isType

hasobjects v1.0.0

has(object, path)

expand signatures

has <K, V> (object: Record<K, V>, path: string | PathLinks): boolean

Convert the given string to camelCase.

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

• get
• getOr
• set

includescollections v1.0.0

includes(value, collection)

expand signatures

includes <T> (value: T, collection: GenericCollection<T>): boolean

ARGUMENTS

RETURNS

USAGE

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

SEE ALSO

• isOneOf

invariantlogic v1.0.0

invariant(condition, message)

expand signatures

invariant (condition: Falsy, message: string): never
invariant <T> (condition: T, message: string): T | never

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

isEqual <T> (a: T, b: T): boolean

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

isArray (value: unknown): value is unknown[]

ARGUMENTS

RETURNS

USAGE

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

isArrayLiketypeslogic v1.0.0

isArrayLike(value)

expand signatures

isArrayLike (value: unknown): value is ArrayLike<unknown>

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

isBoolean (value: unknown): value is boolean

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

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

isBuffer (value: unknown): value is Buffer

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	any	Value to test

RETURNS

boolean

USAGE

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

isDatetypeslogic v1.0.0

isDate(value)

expand signatures

isDate (value: unknown): value is Date

ARGUMENTS

RETURNS

USAGE

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

isEmptytypeslogic v1.0.0

isEmpty(value)

expand signatures

isEmpty (value: unknown): boolean

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

isError (value: unknown): value is Error

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

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

isFunction (value: unknown): value is Function

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.

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

isInRange (value: number, start: number, end: number): boolean

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

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

• range

isIterabletypeslogic v1.0.0

isIterable(value)

expand signatures

isIterable (value: unknown): value is Iterable<unknown>

ARGUMENTS

RETURNS

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

isMap (value: unknown): value is Map<unknown, unknown>

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

isNan (value: unknown): boolean

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

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

isNil (value: unknown): value is null | void

ARGUMENTS

RETURNS

USAGE

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

isNumbertypeslogic v1.0.0

isNumber(value)

expand signatures

isNumber (value: unknown): value is 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

isNumeric <T> (value: T): T extends number ? true : T extends string ? boolean : false

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

isObject (value: any): value is object

ARGUMENTS

RETURNS

USAGE

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

isOneOfcollections v1.0.0

isOneOf(value, collection)

expand signatures

isOneOf <T> (value: T, collection: GenericCollection<T>): boolean

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

• includes

isPrimitivetypeslogic v1.0.0

isPrimitive(value)

expand signatures

isPrimitive (value: unknown): value is Primitive

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

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

isSet (value: unknown): value is Set<unknown>

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
value	any	Value to test

RETURNS

boolean

USAGE

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

isStringtypeslogic v1.0.0

isString(value)

expand signatures

isString (value: unknown): value is string

ARGUMENTS

RETURNS

USAGE

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

isSubsetobjectslogic v1.0.0

isSubset(superset, subset)

expand signatures

isSubset <T> (superset: T, subset: object): boolean

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

• matches

isThenabletypeslogic v1.0.0

isThenable(value)

expand signatures

isThenable (value: unknown): value is PromiseLike<unknown>

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
value	any	Value to test

RETURNS

boolean

USAGE

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

isTypetypeslogic v1.0.0

isType(value, type)

expand signatures

isType (value: unknown, type: any): boolean

ARGUMENTS

RETURNS

USAGE

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

SEE ALSO

• getType

kebabCasestrings v1.0.0

kebabCase(string)

expand signatures

kebabCase (string: string): string

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'

SEE ALSO

• camelCase
• snakeCase
• textCase

lastcollections v1.0.0

last(collection)

expand signatures

last <T> (collection: ArrayLike<T> | Set<T>): T | undefined

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

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

• first

matchesobjectslogic v1.0.0

matches(object, compare)

expand signatures

matches <T> (object: T, compare: object): boolean

ARGUMENTS

RETURNS

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

• isSubset

oncefunctions v1.0.0

once(fn)

expand signatures

once <T> (fn: T): (...args: any[]) => ReturnType<T>

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

partition <T> (collection: T, fn: StringIterator<boolean>): Tuple<string>
partition <T> (collection: T[], fn: ArrayIterator<T, boolean>): Tuple<T[]>
partition <K, V> (collection: Map<K, V>, fn: MapIterator<K, V, boolean>): Tuple<Map<K, V>>
partition <T> (collection: Set<T>, fn: SetIterator<T, boolean>): Tuple<Set<T>>
partition <T> (collection: T, fn: ObjectIterator<T, boolean>): Tuple<Partial<T>>

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

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

pathDots (value: string | PathLinks): string

ARGUMENTS

RETURNS

USAGE

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

SEE ALSO

• pathLinks

pathLinksutilities v1.0.0

pathLinks(value)

expand signatures

pathLinks (value: string | PathLinks): PathLinks

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

• pathDots

pipeasyncfunctions v1.0.0

pipe(a, b)

expand signatures

pipe <A, B> (a: A, b: PipeFunction<Initial<A>, B>): Promise<B>
pipe <A, B, C> (a: A, b: PipeFunction<Initial<A>, B>, c: PipeFunction<B, C>): Promise<C>
pipe <A, B, C, D> (a: A, b: PipeFunction<Initial<A>, B>, c: PipeFunction<B, C>, d: PipeFunction<C, D>): Promise<D>
pipe <A, B, C, D, E> (a: A, b: PipeFunction<Initial<A>, B>, c: PipeFunction<B, C>, d: PipeFunction<C, D>, e: PipeFunction<D, E>): Promise<E>
pipe <A, B, C, D, E, F> (a: A, b: PipeFunction<Initial<A>, B>, c: PipeFunction<B, C>, d: PipeFunction<C, D>, e: PipeFunction<D, E>, f: PipeFunction<E, F>): Promise<F>
pipe <A, B, C, D, E, F, G> (a: A, b: PipeFunction<Initial<A>, B>, c: PipeFunction<B, C>, d: PipeFunction<C, D>, e: PipeFunction<D, E>, f: PipeFunction<E, F>, g: PipeFunction<F, G>): Promise<G>
pipe <A, B, C, D, E, F, G, H> (a: A, b: PipeFunction<Initial<A>, B>, c: PipeFunction<B, C>, d: PipeFunction<C, D>, e: PipeFunction<D, E>, f: PipeFunction<E, F>, g: PipeFunction<F, G>, h: PipeFunction<G, H>): Promise<H>
pipe <A, B, C, D, E, F, G, H, I> (a: A, b: PipeFunction<Initial<A>, B>, c: PipeFunction<B, C>, d: PipeFunction<C, D>, e: PipeFunction<D, E>, f: PipeFunction<E, F>, g: PipeFunction<F, G>, h: PipeFunction<G, H>, i: PipeFunction<H, I>): Promise<I>
pipe <T> (...args: (PipeFunction<any, unknown>)[]): Promise<T>

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

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

random (value: number, bound: number): number
random <T> (value: T[]): T
random <T> (value: ArrayLike<T>): T
random <T> (value: T): T[keyof T]

ARGUMENTS

RETURNS

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

range (...args: [number, number, number]): number[]

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

• isInRange

reducecollections v1.0.0

reduce(collection, fn, initial)

expand signatures

reduce <T, U> (collection: T, fn: StringAccumulator<T, U>, initial: U): U
reduce <T, U> (collection: T[], fn: ArrayAccumulator<T, U>, initial: U): U
reduce <K, V> (collection: Map<K, V>, fn: MapAccumulator<K, V, any>): Map<K, V>
reduce <T, U> (collection: Set<T>, fn: SetAccumulator<T, U>, initial: U): U
reduce <T> (collection: T, fn: ObjectAccumulator<T, T[keyof T]>): T
reduce <T, U> (collection: T, fn: ObjectAccumulator<T, U>, initial: U): U

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

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

• reduceWhile

reduceWhilecollections v1.0.0

reduceWhile(collection, predicate, fn, initial)

expand signatures

reduceWhile <T, U> (collection: T, predicate: (accumulator: T, value: U) => boolean, fn: StringAccumulator<T, U>, initial: U): U
reduceWhile <T, U> (collection: T[], predicate: (accumulator: T[], value: U) => boolean, fn: ArrayAccumulator<T, U>, initial: U): U
reduceWhile <K, V> (collection: Map<K, V>, predicate: (accumulator: Map<K, V>, value: V) => boolean, fn: MapAccumulator<K, V, any>): Map<K, V>
reduceWhile <T, U> (collection: Set<T>, predicate: (accumulator: Set<T>, value: U) => boolean, fn: SetAccumulator<T, U>, initial: U): U
reduceWhile <T> (collection: T, predicate: (accumulator: T, value: T[keyof T]) => boolean, fn: ObjectAccumulator<T, T[keyof T]>): T
reduceWhile <T, U> (collection: T, predicate: (accumulator: T, value: U) => boolean, fn: ObjectAccumulator<T, U>, initial: U): U

ARGUMENTS

RETURNS

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

• reduce

sleepasyncutilities v1.0.0

sleep(ms)

expand signatures

sleep (ms: number): Promise<void>

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

snakeCase (string: string): string

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

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'

SEE ALSO

• camelCase
• kebabCase
• textCase

mapcollections v1.0.0

map(collection, fn)

expand signatures

map <T> (collection: T, fn: StringIterator<T>): T
map <T, R> (collection: T[], fn: ArrayIterator<T, R>): R[]
map <K, V, R> (collection: Map<K, V>, fn: MapIterator<K, V, R>): Map<K, R>
map <T, R> (collection: Set<T>, fn: SetIterator<T, R>): Set<R>
map <T, R> (collection: T, fn: ObjectIterator<T, R[keyof R]>): R

ARGUMENTS

RETURNS

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

SEE ALSO

• each
• filter
• reduce

setobjects v1.0.0

set(object, path, value)

expand signatures

set <K, V> (object: Record<K, V>, path: string | PathLinks, value: V): Record<K, V>

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

• get
• getOr
• has

textCasestrings v1.0.0

textCase(string)

expand signatures

textCase (string: string): string

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

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'

SEE ALSO

• camelCase
• kebabCase
• snakeCase

toArrayutilitiescollections v1.0.0

toArray(value, begin, end)

expand signatures

toArray <T> (value: T[], begin: number, end: number): T[]

message defaults to 'Invariant Violation'.

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

toBoolean (value: true, smart: boolean): true
toBoolean (value: Falsy, smart: boolean): false

ARGUMENTS

RETURNS

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

toEmpty <T> (type: T[]): T[]
toEmpty <K, V> (type: Record<K, V>): Record<K, V>
toEmpty <K, V> (type: Map<K, V>): Map<K, V>
toEmpty <T> (type: Set<T>): Set<T>
toEmpty <T> (type: string): T
toEmpty (type: boolean): false
toEmpty (type: number): 0
toEmpty (type: null): null
toEmpty (type: undefined): undefined

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

toNumber (value: unknown, round: boolean): number

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

toObject (value: null | undefined): __type
toObject <T> (value: T): Record<ValidPropertyKey<T>, T>
toObject <T> (value: T): Record<MapKey<T>, MapValue<T>>
toObject <T> (value: T): Record<IterableValue<T>, IterableValue<T>>
toObject <T> (value: T): T

ARGUMENTS

RETURNS

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

• toObjectWith

toObjectWithutilitiescollections v1.0.0

toObjectWith(value, fn)

expand signatures

toObjectWith (value: null | undefined, fn: (value: never) => any): __type
toObjectWith <T, U> (value: T, fn: (value: T) => U): Record<ValidPropertyKey<T>, U>
toObjectWith <T, U> (value: T, fn: (value: MapValue<T>) => U): Record<MapKey<T>, U>
toObjectWith <T, U> (value: T, fn: (value: IterableValue<T>) => U): Record<IterableValue<T>, U>
toObjectWith <T> (value: T, fn: (...args: any[]) => any): T

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

• toObject