swiss-ak (Swiss Army Knife)

A collection of useful little things that I like to reuse across projects

Table of Contents

times

A collection of Tools for calculating simple times. Each unit (e.g. second) has: a type (second), a constant (SECOND) and a function for getting multiples (seconds(x: second) => ms)

unit	type	constant	function
millisecond	`ms`	`MILLISECOND`	`milliseconds(x: ms) => ms`
second	`second`	`SECOND`	`seconds(x: second) => ms`
minute	`minute`	`MINUTE`	`minutes(x: minute) => ms`
hour	`hour`	`HOUR`	`hours(x: hour) => ms`
day	`day`	`DAY`	`days(x: day) => ms`
week	`week`	`WEEK`	`weeks(x: week) => ms`
month	`month`	`MONTH`	`months(x: month) => ms`
year	`year`	`YEAR`	`years(x: year) => ms`
decade	`decade`	`DECADE`	`decades(x: decade) => ms`
century	`century`	`CENTURY`	`centuries(x: century) => ms`
millennium	`millennium`	`MILLENNIUM`	`millenniums(x: millennium) => ms`

[↑ Back to top ↑]

waiters

Async functions that return promises at or after a given time.

'Accurate/pinged' waiters ping at intermediary points to resolve at a more accurate time.

Name	Description	Example
wait	Standard wait promise (using setTimeout)	`minutes(2)` = in 2 minutes
waitFor	Accurate (pinged) wait the given ms	`minutes(2)` = in 2 minutes
waitUntil	Accurate (pinged) wait until given time	`Date.now() + minutes(2)` = in 2 minutes
waitEvery	Accurate (pinged) wait for next 'every X' event	`hours(1)` = next full hour (e.g. 17:00, 22:00)
interval	Accurate (pinged) interval for every 'every X' event	`hours(1)` = every hour, on the hour

waiters
- wait
- waitUntil
- waitFor
- waitEvery
- stopInterval
- interval

[↑ Back to top ↑]

wait

wait(time: ms): Promise<unknown>
waiters.wait(time: ms): Promise<unknown>

Standard wait promise (using setTimeout)

import { wait } from 'swiss-ak';

console.log(new Date().toTimeString()); // 12:30:10
await wait(minutes(2));
console.log(new Date().toTimeString()); // 12:32:10

#	Parameter Name	Required	Type
0	`time`	Yes	`ms`

Return Type
`Promise<unknown>`

[↑ Back to waiters ↑]

waitUntil

waitUntil(time: ms): Promise<null>
waiters.waitUntil(time: ms): Promise<null>

Accurate (pinged) wait until given time

import { waitUntil } from 'swiss-ak';

console.log(new Date().toTimeString()); // 12:30:10
await waitUntil(Date.now() + minutes(10));
console.log(new Date().toTimeString()); // 12:40:10

#	Parameter Name	Required	Type
0	`time`	Yes	`ms`

Return Type
`Promise<null>`

[↑ Back to waiters ↑]

waitFor

waitFor(time: ms): Promise<null>
waiters.waitFor(time: ms): Promise<null>

Accurate (pinged) wait the given ms

import { waitFor } from 'swiss-ak';

console.log(new Date().toTimeString()); // 12:30:10
await waitFor(minutes(5));
console.log(new Date().toTimeString()); // 12:35:10

#	Parameter Name	Required	Type
0	`time`	Yes	`ms`

Return Type
`Promise<null>`

[↑ Back to waiters ↑]

waitEvery

waitEvery(timing: ms, offset: ms): Promise<null>
waiters.waitEvery(timing: ms, offset: ms): Promise<null>

Accurate (pinged) wait for next 'every X' event

import { waitEvery } from 'swiss-ak';

console.log(new Date().toTimeString()); // 12:30:10
await waitEvery(hours(2));
console.log(new Date().toTimeString()); // 14:00:00

#	Parameter Name	Required	Type
0	`timing`	Yes	`ms`
1	`offset`	No	`ms`

Return Type
`Promise<null>`

[↑ Back to waiters ↑]

stopInterval

stopInterval(intID: number): void
waiters.stopInterval(intID: number): void

import { interval, stopInterval } from 'swiss-ak';

console.log(new Date().toTimeString()); // 12:30:10
interval((intID, count) => {
  console.log(new Date().toTimeString()); // 13:00:00, 14:00:00, 15:00:00
  if (count === 3) {
    stopInterval(intID);
  }
}, hours(1));

#	Parameter Name	Required	Type
0	`intID`	Yes	`number`

Return Type
`void`

[↑ Back to waiters ↑]

interval

interval(action: (intID?: number, count?: number) => any, timing: ms): number
waiters.interval(action: (intID?: number, count?: number) => any, timing: ms): number

Accurate (pinged) interval for every 'every X' event

import { interval, stopInterval } from 'swiss-ak';

console.log(new Date().toTimeString()); // 12:30:10
interval((intID, count) => {
  console.log(new Date().toTimeString()); // 13:00:00, 14:00:00, 15:00:00
  if (count === 3) {
    stopInterval(intID);
  }
}, hours(1));

#	Parameter Name	Required	Type
0	`action`	Yes	`(intID?: number, count?: number) => any`
1	`timing`	Yes	`ms`

Return Type
`number`

[↑ Back to waiters ↑]

fn

A collection of useful higher-order functions.

fn
- noop
- noact
- result
- resolve
- reject
- filters
  - exists
  - isTruthy
  - isFalsy
  - isEmpty
  - isNotEmpty
  - isEqual
  - isNotEqual
  - dedupe
  - dedupeMapped
- maps
  - toString
  - toNumber
  - toBool
  - toProp
  - toFixed
- sorts
  - asc
  - desc
  - byProp
  - nearestTo
  - furthestFrom
  - array
  - arrayAsc
  - arrayDesc
- reduces
  - combine
  - combineProp
  - mode
  - modeMapped
- everys
  - isAllEqual
  - isUnique
- groups
  - bySize
  - byNumGroups

[↑ Back to top ↑]

noop

fn.noop(): void

No operation. Do nothing, return nothing.

const run = condition ? doSomething : fn.noop;
run();

Return Type
`void`

[↑ Back to fn ↑]

noact

fn.noact(item: T): T

No action. Returns the first argument it receives.

const items = stuff
  .map(condition ? mapSomething : fn.noact)

#	Parameter Name	Required	Type
0	`item`	No	`T`

Return Type
`T`

[↑ Back to fn ↑]

result

fn.result(item: T): () => T

Returns a function that returns the first argument.

const items = stuff
  .filter(condition ? mapSomething : fn.result(true))

#	Parameter Name	Required	Type
0	`item`	No	`T`

Return Type
`() => T`

[↑ Back to fn ↑]

resolve

fn.resolve(item: T): () => Promise<T>

Returns an async function that resolves to the first argument

Like fn.result, but wrapped in a Promise

#	Parameter Name	Required	Type
0	`item`	No	`T`

Return Type
`() => Promise<T>`

[↑ Back to fn ↑]

reject

fn.reject(item: T): () => Promise<T>

Returns an async function that rejects with the first argument

#	Parameter Name	Required	Type
0	`item`	No	`T`

Return Type
`() => Promise<T>`

[↑ Back to fn ↑]

filters

fn.filters;

Collection of functions that can be used with Array.filter

[↑ Back to fn ↑]

exists

fn.exists(item: T): boolean
fn.filters.exists(item: T): boolean
filters.exists(item: T): boolean

Returns true if item isn't null or undefined.

[null, 1, undefined, 2].filter(fn.exists); // [1, 2]

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`boolean`

[↑ Back to fn ↑]

isTruthy

fn.isTruthy(item: T): boolean
fn.filters.isTruthy(item: T): boolean
filters.isTruthy(item: T): boolean

Returns true if item is truthy.

[0, 1, 2].filter(fn.isTruthy); // [1, 2]
['', 'a', 'b'].filter(fn.isTruthy); // ['a', 'b']

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`boolean`

[↑ Back to fn ↑]

isFalsy

fn.isFalsy(item: T): boolean
fn.filters.isFalsy(item: T): boolean
filters.isFalsy(item: T): boolean

Returns true if item is falsy.

[0, 1, 2].filter(fn.isFalsy); // [0]
['', 'a', 'b'].filter(fn.isFalsy); // ['']

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`boolean`

[↑ Back to fn ↑]

isEmpty

fn.isEmpty(item: T[] | string): boolean
fn.filters.isEmpty(item: T[] | string): boolean
filters.isEmpty(item: T[] | string): boolean

Returns true if item's length is 0

['', 'a', 'b'].filter(fn.isEmpty); // ['']
[[], [1], [2]].filter(fn.isEmpty); // [[]]

#	Parameter Name	Required	Type
0	`item`	Yes	`T[] \| string`

Return Type
`boolean`

[↑ Back to fn ↑]

isNotEmpty

fn.isNotEmpty(item: T[] | string): boolean
fn.filters.isNotEmpty(item: T[] | string): boolean
filters.isNotEmpty(item: T[] | string): boolean

Returns true if item's length is 1 or more

['', 'a', 'b'].filter(fn.isNotEmpty); // ['a', 'b']
[[], [1], [2]].filter(fn.isNotEmpty); // [[1], [2]]

#	Parameter Name	Required	Type
0	`item`	Yes	`T[] \| string`

Return Type
`boolean`

[↑ Back to fn ↑]

isEqual

fn.isEqual(item: T): (other: T) => boolean
fn.filters.isEqual(item: T): (other: T) => boolean
filters.isEqual(item: T): (other: T) => boolean

Returns a function that returns true if the item is equal to provided value.

[0, 1, 2].filter(fn.isEqual(1)); // [1]

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`(other: T) => boolean`

[↑ Back to fn ↑]

isNotEqual

fn.isNotEqual(item: T): (other: T) => boolean
fn.filters.isNotEqual(item: T): (other: T) => boolean
filters.isNotEqual(item: T): (other: T) => boolean

Returns a function that returns true if the item is not equal to provided value.

[0, 1, 2].filter(fn.isNotEqual(1)); // [0, 2]

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`(other: T) => boolean`

[↑ Back to fn ↑]

dedupe

fn.dedupe(item: T, index: number, array: T[]): boolean
fn.filters.dedupe(item: T, index: number, array: T[]): boolean
filters.dedupe(item: T, index: number, array: T[]): boolean

Removes duplicate items from an array.

[0, 1, 2, 1, 0].filter(fn.dedupe); // [0, 1, 2]

#	Parameter Name	Required	Type
0	`item`	Yes	`T`
1	`index`	Yes	`number`
2	`array`	Yes	`T[]`

Return Type
`boolean`

[↑ Back to fn ↑]

dedupeMapped

fn.dedupeMapped(mapFn: (value?: T, index?: number, array?: T[]) => U): (item: T, index: number, array: T[]) => boolean
fn.filters.dedupeMapped(mapFn: (value?: T, index?: number, array?: T[]) => U): (item: T, index: number, array: T[]) => boolean
filters.dedupeMapped(mapFn: (value?: T, index?: number, array?: T[]) => U): (item: T, index: number, array: T[]) => boolean

Removes duplicate items from an array based on a mapped value.

[2, 4, 6, 8, 10, 12].filter(fn.dedupeMapped((v) => v % 3)); // [ 2, 4, 6 ] (maps to [ 2, 1, 0, 2, 1, 0 ])

#	Parameter Name	Required	Type
0	`mapFn`	Yes	`(value?: T, index?: number, array?: T[]) => U`

Return Type
`(item: T, index: number, array: T[]) => boolean`

[↑ Back to fn ↑]

maps

fn.maps;

Collection of functions that can be used with Array.map

[↑ Back to fn ↑]

toString

fn.toString(item: T): string
fn.maps.toString(item: T): string
maps.toString(item: T): string

Maps the item to a string.

[0, 1, 2].map(fn.toString); // ['0', '1', '2']

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`string`

[↑ Back to fn ↑]

toNumber

fn.toNumber(item: T): number
fn.maps.toNumber(item: T): number
maps.toNumber(item: T): number

Maps the item to a number.

['0', '1', '2'].map(fn.toNumber); // [0, 1, 2]

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`number`

[↑ Back to fn ↑]

toBool

fn.toBool(item: T): boolean
fn.maps.toBool(item: T): boolean
maps.toBool(item: T): boolean

Maps the item to a boolean.

[0, 1, 2].map(fn.toBool); // [false, true, true]
['true', 'false', '', 'text'].map(fn.toBool); // [true, false, false, true]

#	Parameter Name	Required	Type
0	`item`	Yes	`T`

Return Type
`boolean`

[↑ Back to fn ↑]

toProp

fn.toProp(prop: string | number): (item: O) => P
fn.maps.toProp(prop: string | number): (item: O) => P
maps.toProp(prop: string | number): (item: O) => P

Maps the item to a given property of the item

[{name: 'Jack'}, {name: 'Jill'}].map(fn.toProp('name')); // ['Jack', 'Jill']

#	Parameter Name	Required	Type
0	`prop`	Yes	`string \| number`

Return Type
`(item: O) => P`

[↑ Back to fn ↑]

toFixed

fn.toFixed(precision: number): (num: number) => number
fn.maps.toFixed(precision: number): (num: number) => number
maps.toFixed(precision: number): (num: number) => number

Map the items (numbers) of an array to a fixed precision.

[1.234, 5.678, 9.012].map(fn.toFixed(2)); // [1.23, 5.68, 9.01]

#	Parameter Name	Required	Type
0	`precision`	Yes	`number`

Return Type
`(num: number) => number`

[↑ Back to fn ↑]

sorts

fn.sorts;

Collection of functions that can be used with Array.sort

[↑ Back to fn ↑]

asc

fn.asc(a: any, b: any): number
fn.sorts.asc(a: any, b: any): number
sorts.asc(a: any, b: any): number

Sort ascending.

[2, 4, 3, 1].sort(fn.asc); // [1, 2, 3, 4]

#	Parameter Name	Required	Type
0	`a`	Yes	`any`
1	`b`	Yes	`any`

Return Type
`number`

[↑ Back to fn ↑]

desc

fn.desc(a: any, b: any): number
fn.sorts.desc(a: any, b: any): number
sorts.desc(a: any, b: any): number

Sort descending.

[2, 4, 3, 1].sort(fn.asc); // [4, 3, 2, 1]

#	Parameter Name	Required	Type
0	`a`	Yes	`any`
1	`b`	Yes	`any`

Return Type
`number`

[↑ Back to fn ↑]

byProp

fn.byProp(propName: string | number, sortFn: SortFn<T>): SortFn<O>
fn.sorts.byProp(propName: string | number, sortFn: SortFn<T>): SortFn<O>
sorts.byProp(propName: string | number, sortFn: SortFn<T>): SortFn<O>

Sort by a given property.

const people = [{age: 2}, {age: 4}, {age: 3}, {age: 1}];
people.sort(fn.byProp('age', fn.asc)); // [{age: 1}, {age: 2}, {age: 3}, {age: 4}]

#	Parameter Name	Required	Type	Default
0	`propName`	Yes	`string \| number`
1	`sortFn`	No	`SortFn<T>`	`asc`

Return Type
`SortFn<O>`

[↑ Back to fn ↑]

nearestTo

fn.nearestTo(target: T): (a: any, b: any) => number
fn.sorts.nearestTo(target: T): (a: any, b: any) => number
sorts.nearestTo(target: T): (a: any, b: any) => number

Sort by the nearest value to the given value.

Values get converted to numbers before comparison.

const people = [2, 4, 3, 1];
people.sort(fn.nearestTo(3)); // [3, 2, 4, 1]

#	Parameter Name	Required	Type
0	`target`	Yes	`T`

Return Type
`(a: any, b: any) => number`

[↑ Back to fn ↑]

furthestFrom

fn.furthestFrom(target: T): (a: any, b: any) => number
fn.sorts.furthestFrom(target: T): (a: any, b: any) => number
sorts.furthestFrom(target: T): (a: any, b: any) => number

Sort by the furthest value to the given value.

const people = [2, 4, 3, 1];
people.sort(fn.furthestFrom(3)); // [1, 2, 4, 3]

#	Parameter Name	Required	Type
0	`target`	Yes	`T`

Return Type
`(a: any, b: any) => number`

[↑ Back to fn ↑]

array

fn.array(sortFn: SortFn<T>): (a: T[], b: T[]) => number
fn.sorts.array(sortFn: SortFn<T>): (a: T[], b: T[]) => number
sorts.array(sortFn: SortFn<T>): (a: T[], b: T[]) => number

Sort an array of arrays by the given sort function.

Sorts by the first item in the array, then the second, etc. until a non-zero result is found.

#	Parameter Name	Required	Type	Default
0	`sortFn`	No	`SortFn<T>`	`asc`

Return Type
`(a: T[], b: T[]) => number`

[↑ Back to fn ↑]

arrayAsc

fn.arrayAsc;
fn.sorts.arrayAsc;
sorts.arrayAsc;

Sort an array of arrays in ascending order

Sorts by the first item in the array, then the second, etc. until a non-zero result is found.

[↑ Back to fn ↑]

arrayDesc

fn.arrayDesc;
fn.sorts.arrayDesc;
sorts.arrayDesc;

Sort an array of arrays in descending order

Sorts by the first item in the array, then the second, etc. until a non-zero result is found.

[↑ Back to fn ↑]

reduces

fn.reduces;

Collection of functions that can be used with Array.reduce

[↑ Back to fn ↑]

combine

fn.combine(a: T, b: T): T
fn.reduces.combine(a: T, b: T): T
reduces.combine(a: T, b: T): T

Adds or concats the items

[1, 2, 3].reduce(fn.combine); // 6
['a', 'b', 'c'].reduce(fn.combine); // 'abc'

#	Parameter Name	Required	Type
0	`a`	Yes	`T`
1	`b`	Yes	`T`

Return Type
`T`

[↑ Back to fn ↑]

combineProp

fn.combineProp(propName: string | number): (a: O | T, b: O) => T
fn.reduces.combineProp(propName: string | number): (a: O | T, b: O) => T
reduces.combineProp(propName: string | number): (a: O | T, b: O) => T

Adds or concats the given property of the items

const people = [{name: 'a', age: 1}, {name: 'b', age: 2}, {name: 'c', age: 3}];
people.reduce(fn.combineProp('age')); // 6
people.reduce(fn.combineProp('name')); // 'abc'

#	Parameter Name	Required	Type
0	`propName`	Yes	`string \| number`

Return Type
`(a: O \| T, b: O) => T`

[↑ Back to fn ↑]

mode

fn.mode(prev: T, curr: T, index: number, arr: T[]): T
fn.reduces.mode(prev: T, curr: T, index: number, arr: T[]): T
reduces.mode(prev: T, curr: T, index: number, arr: T[]): T

Returns the most common value in an array.

[1, 2, 3, 2, 1, 1].reduce(fn.mode); // 1

#	Parameter Name	Required	Type
0	`prev`	Yes	`T`
1	`curr`	Yes	`T`
2	`index`	Yes	`number`
3	`arr`	Yes	`T[]`

Return Type
`T`

[↑ Back to fn ↑]

modeMapped

fn.modeMapped(mapFn: (value: T, index: number, array: T[]) => U): (prev: T, curr: T, index: number, arr: T[]) => T
fn.reduces.modeMapped(mapFn: (value: T, index: number, array: T[]) => U): (prev: T, curr: T, index: number, arr: T[]) => T
reduces.modeMapped(mapFn: (value: T, index: number, array: T[]) => U): (prev: T, curr: T, index: number, arr: T[]) => T

Returns the most common value in an array, based on a given map function.

[2, 4, 6, 8, 9, 12].reduce(fn.modeMapped((v) => v % 3)); // 6 (maps to [ 2, 1, 0, 2, 0, 0 ])

#	Parameter Name	Required	Type
0	`mapFn`	Yes	`(value: T, index: number, array: T[]) => U`

Return Type
`(prev: T, curr: T, index: number, arr: T[]) => T`

[↑ Back to fn ↑]

everys

fn.everys;

Collection of functions that can be used with Array.every

[↑ Back to fn ↑]

isAllEqual

fn.isAllEqual(val: T, i: number, arr: T[]): boolean
fn.everys.isAllEqual(val: T, i: number, arr: T[]): boolean
everys.isAllEqual(val: T, i: number, arr: T[]): boolean

Returns if all the items are equal to one another.

[1, 1, 1].every(fn.isAllEqual); // true
[1, 2, 1].every(fn.isAllEqual); // false

#	Parameter Name	Required	Type
0	`val`	Yes	`T`
1	`i`	Yes	`number`
2	`arr`	Yes	`T[]`

Return Type
`boolean`

[↑ Back to fn ↑]

isUnique

fn.isUnique(val: T, i: number, arr: T[]): boolean
fn.everys.isUnique(val: T, i: number, arr: T[]): boolean
everys.isUnique(val: T, i: number, arr: T[]): boolean

Returns true if the item is unique in the array.

[1, 1, 1].every(fn.isUnique); // false
[1, 2, 1].every(fn.isUnique); // false
[1, 2, 3].every(fn.isUnique); // true

#	Parameter Name	Required	Type
0	`val`	Yes	`T`
1	`i`	Yes	`number`
2	`arr`	Yes	`T[]`

Return Type
`boolean`

[↑ Back to fn ↑]

groups

fn.groups;

Collection of functions that can be used with ArrayTools.group

[↑ Back to fn ↑]

bySize

fn.bySize(size: number): (value: T, index: number, array: T[]) => number
fn.groups.bySize(size: number): (value: T, index: number, array: T[]) => number
groups.bySize(size: number): (value: T, index: number, array: T[]) => number

Group an array into groups of a given size.

Note: The last group may be smaller than the given size.

Note: The groups a distributed in order, so the first group will be filled up first, then the next, etc.

const nums = [1, 2, 3, 4, 5, 6, 7, 8];
ArrayTools.group(nums, fn.bySize(3)); // [[1, 2, 3], [4, 5, 6], [7, 8]]

#	Parameter Name	Required	Type
0	`size`	Yes	`number`

Return Type
`(value: T, index: number, array: T[]) => number`

[↑ Back to fn ↑]

byNumGroups

fn.byNumGroups(numGroups: number): (value: T, index: number, array: T[]) => any
fn.groups.byNumGroups(numGroups: number): (value: T, index: number, array: T[]) => any
groups.byNumGroups(numGroups: number): (value: T, index: number, array: T[]) => any

Group an array into a certain number of groups as evenly as possible.

Note: The groups a distributed in order, so the first group will be filled up first, then the next, etc.

const nums = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
ArrayTools.group(nums, byNumGroups(3)); // [[1, 2, 3, 4], [5, 6, 7], [8, 9, 10]]

#	Parameter Name	Required	Type
0	`numGroups`	Yes	`number`

Return Type
`(value: T, index: number, array: T[]) => any`

[↑ Back to fn ↑]

ArrayTools

A collection of useful array functions.

ArrayTools
- create
- filled
- range
- zip
- zipMax
- sortByMapped
- randomise
- reverse
- entries
- repeat
- roll
- sortNumberedText
- partition
- groupObj
- group
- findAndRemove
- findLastAndRemove
- filterAndRemove
- utils
  - isNumString
  - partitionNums

[↑ Back to top ↑]

create

create(length: number, value: T): T[]
ArrayTools.create(length: number, value: T): T[]

Create an array of the given length, where each value is the given value

#	Parameter Name	Required	Type	Default
0	`length`	No	`number`	`1`
1	`value`	No	`T`	`1 as T`

Return Type
`T[]`

[↑ Back to ArrayTools ↑]

filled

filled(length: number, value: T): T[]
ArrayTools.filled(length: number, value: T): T[]

Create an array of the given length, where each value is the given value

#	Parameter Name	Required	Type	Default
0	`length`	No	`number`	`1`
1	`value`	Yes	`T`

Return Type
`T[]`

[↑ Back to ArrayTools ↑]

range

range(length: number, multiplier: number, offset: number): number[]
ArrayTools.range(length: number, multiplier: number, offset: number): number[]

Returns an array of the given length, where each value is equal to it's index e.g. [0, 1, 2, ..., length]

ArrayTools.range(3);  // [0, 1, 2]
ArrayTools.range(5);  // [0, 1, 2, 3, 4]
ArrayTools.range(10); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

ArrayTools.range(3, 2);  // [0, 2, 4]
ArrayTools.range(5, 2);  // [0, 2, 4, 6, 8]
ArrayTools.range(10, 10); // [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]

#	Parameter Name	Required	Type	Default
0	`length`	No	`number`	`1`
1	`multiplier`	No	`number`	`1`
2	`offset`	No	`number`	`0`

Return Type
`number[]`

[↑ Back to ArrayTools ↑]

zip

zip(...arrs: T[]): ZippedArrays<T>[]
ArrayTools.zip(...arrs: T[]): ZippedArrays<T>[]

Converts multiple arrays into an array of 'tuples' for each value at the corresponding indexes.

Limited to the length of the shortest provided array

Inspired by python's 'zip'

ArrayTools.zip([1, 2, 3, 4], ['a', 'b', 'c']); // [ [1, 'a'], [2, 'b'], [3, 'c'] ]

#	Parameter Name	Required	Type
0…	`arrs`	No	`T[]`

Return Type
`ZippedArrays<T>[]`

[↑ Back to ArrayTools ↑]

zipMax

zipMax(...arrs: T[]): ZippedArrays<T>[]
ArrayTools.zipMax(...arrs: T[]): ZippedArrays<T>[]

Converts multiple arrays into an array of 'tuples' for each value at the corresponding indexes.

Unlike zip, it will match the length of the longest provided array, filling in any missing values with undefined

Inspired by python's 'zip'

ArrayTools.zipMax([1, 2, 3, 4], ['a', 'b', 'c']); //[ [ 1, 'a' ], [ 2, 'b' ], [ 3, 'c' ], [ 4, undefined ] ]

#	Parameter Name	Required	Type
0…	`arrs`	No	`T[]`

Return Type
`ZippedArrays<T>[]`

[↑ Back to ArrayTools ↑]

sortByMapped

sortByMapped(arr: T[], mapFn: (value: T, index: number, array: T[]) => M, sortFn: (a: M, b: M) => number): T[]
ArrayTools.sortByMapped(arr: T[], mapFn: (value: T, index: number, array: T[]) => M, sortFn: (a: M, b: M) => number): T[]

Sort an array by a mapped form of the values, but returning the initial values

ArrayTools.sortByMapped(['2p', '3p', '1p'], (v) => Number(v.replace('p', ''))); // ['1p', '2p', '3p']
ArrayTools.sortByMapped(
  ['2p', '3p', '1p'],
  (v) => Number(v.replace('p', '')),
  (a, b) => b - a
); // ['3p', '2p', '1p']

#	Parameter Name	Required	Type	Default
0	`arr`	Yes	`T[]`
1	`mapFn`	Yes	`(value: T, index: number, array: T[]) => M`
2	`sortFn`	No	`(a: M, b: M) => number`	`fn.asc`

Return Type
`T[]`

[↑ Back to ArrayTools ↑]

randomise

randomise(arr: T[]): T[]
ArrayTools.randomise(arr: T[]): T[]

Returns a clone of the provided array with it's items in a random order

ArrayTools.randomise([1, 2, 3, 4, 5, 6]); // [ 5, 3, 4, 1, 2, 6 ]
ArrayTools.randomise([1, 2, 3, 4, 5, 6]); // [ 5, 1, 3, 2, 4, 6 ]
ArrayTools.randomise([1, 2, 3, 4, 5, 6]); // [ 6, 1, 4, 5, 2, 3 ]
ArrayTools.randomise([1, 2, 3, 4, 5, 6]); // [ 1, 4, 5, 2, 3, 6 ]
ArrayTools.randomise([1, 2, 3, 4, 5, 6]); // [ 2, 6, 1, 3, 4, 5 ]

#	Parameter Name	Required	Type
0	`arr`	Yes	`T[]`

Return Type
`T[]`

[↑ Back to ArrayTools ↑]

reverse

reverse(arr: T[]): T[]
ArrayTools.reverse(arr: T[]): T[]

Returns a new array with the order reversed without affecting original array

const arr1 = [1, 2, 3];
arr1            // [1, 2, 3]
arr1.reverse(); // [3, 2, 1]
arr1            // [3, 2, 1]

const arr2 = [1, 2, 3];
arr2            // [1, 2, 3]
ArrayTools.reverse(arr2);  // [3, 2, 1]
arr2            // [1, 2, 3]

#	Parameter Name	Required	Type
0	`arr`	Yes	`T[]`

Return Type
`T[]`

[↑ Back to ArrayTools ↑]

entries

entries(arr: T[]): [number, T][]
ArrayTools.entries(arr: T[]): [number, T][]

Returns array of 'tuples' of index/value pairs

const arr = ['a', 'b', 'c'];
ArrayTools.entries(arr); // [ [0, 'a'], [1, 'b'], [2, 'c'] ]

for (let [index, value] of entries(arr)) {
 console.log(index); // 0, 1, 2
 console.log(value); // 'a', 'b', 'c'
}

#	Parameter Name	Required	Type
0	`arr`	Yes	`T[]`

Return Type
`[number, T][]`

[↑ Back to ArrayTools ↑]

repeat

repeat(maxLength: number, ...items: T[]): T[]
ArrayTools.repeat(maxLength: number, ...items: T[]): T[]

Returns an array with the given items repeated

ArrayTools.repeat(5, 'a'); // [ 'a', 'a', 'a', 'a', 'a' ]
ArrayTools.repeat(5, 'a', 'b'); // [ 'a', 'b', 'a', 'b', 'a' ]

#	Parameter Name	Required	Type
0	`maxLength`	Yes	`number`
1…	`items`	No	`T[]`

Return Type
`T[]`

[↑ Back to ArrayTools ↑]

roll

roll(distance: number, arr: T[]): T[]
ArrayTools.roll(distance: number, arr: T[]): T[]

'Roll' the array by a given amount so that is has a new first item. Length and contents remain the same, but the order is changed

ArrayTools.roll(1, [0, 1, 2, 3, 4, 5, 6, 7]); // [ 1, 2, 3, 4, 5, 6, 7, 0 ]
ArrayTools.roll(4, [0, 1, 2, 3, 4, 5, 6, 7]); // [ 4, 5, 6, 7, 0, 1, 2, 3 ]

#	Parameter Name	Required	Type
0	`distance`	Yes	`number`
1	`arr`	Yes	`T[]`

Return Type
`T[]`

[↑ Back to ArrayTools ↑]

sortNumberedText

sortNumberedText(texts: string[], ignoreCase: boolean): string[]
ArrayTools.sortNumberedText(texts: string[], ignoreCase: boolean): string[]

Alphabetically sorts a list of strings, but keeps multi-digit numbers in numerical order (rather than alphabetical)

const names = ['name1', 'name10', 'name2', 'foo20', 'foo10', 'foo9'];
names.sort(); // [ 'foo10', 'foo20', 'foo9', 'name1', 'name10', 'name2' ]
ArrayTools.sortNumberedText(names); // [ 'foo9', 'foo10', 'foo20', 'name1', 'name2', 'name10' ]

#	Parameter Name	Required	Type	Default
0	`texts`	Yes	`string[]`
1	`ignoreCase`	No	`boolean`	`true`

Return Type
`string[]`

[↑ Back to ArrayTools ↑]

partition

partition(array: T[], partitionSize: number): T[][]
ArrayTools.partition(array: T[], partitionSize: number): T[][]

Breaks an array into smaller arrays of a given size

ArrayTools.partition([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 3); // [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ], [ 10 ] ]

#	Parameter Name	Required	Type	Default
0	`array`	Yes	`T[]`
1	`partitionSize`	No	`number`	`Math.ceil(array.length / 2)`

Return Type
`T[][]`

[↑ Back to ArrayTools ↑]

groupObj

groupObj(array: T[], mapFn: (item: T, index: number, arr: T[]) => string | number): { [id: string]: T[]; [id: number]: T[]; }
ArrayTools.groupObj(array: T[], mapFn: (item: T, index: number, arr: T[]) => string | number): { [id: string]: T[]; [id: number]: T[]; }

Group items from an array into an object of arrays, based on a given map function.

const arr = [
  { group: 1, name: 'a' },
  { group: 2, name: 'b' },
  { group: 1, name: 'c' },
];
ArrayTools.groupObj(arr, item => item.group); // {
//   1: [ { group: 1, name: 'a' }, { group: 1, name: 'c' } ],
//   2: [ { group: 2, name: 'b' } ]
// }

#	Parameter Name	Required	Type
0	`array`	Yes	`T[]`
1	`mapFn`	Yes	`(item: T, index: number, arr: T[]) => string \| number`

Return Type
`{ [id: string]: T[]; [id: number]: T[]; }`

[↑ Back to ArrayTools ↑]

group

group(array: T[], mapFn: (item: T, index: number, arr: T[]) => string | number): T[][]
ArrayTools.group(array: T[], mapFn: (item: T, index: number, arr: T[]) => string | number): T[][]

Group items from an array into an array of arrays, based on a given map function.

const arr = [
  { group: 1, name: 'a' },
  { group: 2, name: 'b' },
  { group: 1, name: 'c' },
];
ArrayTools.group(arr, item => item.group); // [
//   [ { group: 1, name: 'a' }, { group: 1, name: 'c' } ],
//   [ { group: 2, name: 'b' } ]
// ]

#	Parameter Name	Required	Type
0	`array`	Yes	`T[]`
1	`mapFn`	Yes	`(item: T, index: number, arr: T[]) => string \| number`

Return Type
`T[][]`

[↑ Back to ArrayTools ↑]

findAndRemove

ArrayTools.findAndRemove(array: T[], predicate: (item: T, index: number, arr: T[]) => any, ...insertItems: T[]): T

Find the first item in an array that matches a given predicate, and remove it from the array

Note: This function mutates the provided array

#	Parameter Name	Required	Type	Description
0	`array`	Yes	`T[]`	the array to mutate
1	`predicate`	Yes	`(item: T, index: number, arr: T[]) => any`	a function that returns true/truthy if the item should be removed
2…	`insertItems`	No	`T[]`	items to insert in place of the removed item

Return Type
`T`	removed item (undefined if not found)

[↑ Back to ArrayTools ↑]

findLastAndRemove

ArrayTools.findLastAndRemove(array: T[], predicate: (item: T, index: number, arr: T[]) => any, ...insertItems: T[]): T

Find the last item in an array that matches a given predicate, and remove it from the array

Note: This function mutates the provided array

#	Parameter Name	Required	Type	Description
0	`array`	Yes	`T[]`	the array to mutate
1	`predicate`	Yes	`(item: T, index: number, arr: T[]) => any`	a function that returns true/truthy if the item should be removed
2…	`insertItems`	No	`T[]`	items to insert in place of the removed item

Return Type
`T`	removed item (undefined if not found)

[↑ Back to ArrayTools ↑]

filterAndRemove

ArrayTools.filterAndRemove(array: T[], predicate: (item: T, index: number, arr: T[]) => any): T[]

Find the items in an array that matches a given predicate, and remove them from the array

Note: This function mutates the provided array

#	Parameter Name	Required	Type	Description
0	`array`	Yes	`T[]`	the array to mutate
1	`predicate`	Yes	`(item: T, index: number, arr: T[]) => any`	a function that returns true/truthy if the item should be removed

Return Type
`T[]`	removed items

[↑ Back to ArrayTools ↑]

utils

ArrayTools.utils;

Small helper functions that may help, but aren't important enough to be in ArrayTools directly

[↑ Back to ArrayTools ↑]

isNumString

ArrayTools.utils.isNumString(text: string): boolean

Returns true if the given string is a number

#	Parameter Name	Required	Type
0	`text`	Yes	`string`

Return Type
`boolean`

[↑ Back to ArrayTools ↑]

partitionNums

ArrayTools.utils.partitionNums(ignoreCase: boolean): (name: string) => (string | number)[]

Splits a string into an array of strings and numbers

#	Parameter Name	Required	Type
0	`ignoreCase`	Yes	`boolean`

Return Type
`(name: string) => (string \| number)[]`

[↑ Back to ArrayTools ↑]

ObjectTools

A collection of functions for working with objects

ObjectTools
- remodel
- remodelEach
- map
- mapValues
- mapKeys
- filter
- clean
- invert

[↑ Back to top ↑]

remodel

ObjectTools.remodel(obj: T, func: (entries: [string, V][]) => [string, W][]): O

Apply a function to the entries of an object

const input = {'foo': 2, 'bar': 1, 'baz': 4}
ObjectTools.remodel(input, (entries) => entries.filter(([k, v]) => v % 2 === 0)) // { foo: 2, baz: 4 }

#	Parameter Name	Required	Type
0	`obj`	Yes	`T`
1	`func`	Yes	`(entries: [string, V][]) => [string, W][]`

Return Type
`O`

[↑ Back to ObjectTools ↑]

remodelEach

ObjectTools.remodelEach(obj: T, func: (entry: [string, V], index: number, entries: [string, V][]) => [string, W]): O

Apply a function to each of the entries of an object

Note: similar to ObjectTools.map, but the function parameters are different. Prefer ObjectTools.map where possible.

const input = {'foo': 2, 'bar': 1, 'baz': 4}
ObjectTools.remodelEach(input, ([k, v]) => [k, v * 2]) // { foo: 4, bar: 2, baz: 8 }

#	Parameter Name	Required	Type
0	`obj`	Yes	`T`
1	`func`	Yes	`(entry: [string, V], index: number, entries: [string, V][]) => [string, W]`

Return Type
`O`

[↑ Back to ObjectTools ↑]

map

ObjectTools.map(obj: T, func: (key: string, value: V, index: number) => [string, W]): any

Maps the keys and values of an object in a similar way to Array.map

ObjectTools.map({a: 1, b: 2, c: 3}, (key, value) => [key, key + value]); // {a: 'a1', b: 'b2', c: 'c3'}

#	Parameter Name	Required	Type
0	`obj`	Yes	`T`
1	`func`	Yes	`(key: string, value: V, index: number) => [string, W]`

Return Type
`any`

[↑ Back to ObjectTools ↑]

mapValues

ObjectTools.mapValues(obj: T, func: (key: string, value: V, index: number) => W): any

Maps the values of an object in a similar way to Array.map

ObjectTools.map({a: 1, b: 2, c: 3}, (key, value) => key.repeat(value)); // {a: 'a', b: 'bb', c: 'ccc'}

#	Parameter Name	Required	Type
0	`obj`	Yes	`T`
1	`func`	Yes	`(key: string, value: V, index: number) => W`

Return Type
`any`

[↑ Back to ObjectTools ↑]

mapKeys

ObjectTools.mapKeys(obj: T, func: (key: string, value: V, index: number) => string): T

Maps the values of an object in a similar way to Array.map

ObjectTools.map({a: 1, b: 2, c: 3}, (key, value) => key.repeat(value)); // {a: 1, bb: 2, ccc: 3}

#	Parameter Name	Required	Type
0	`obj`	Yes	`T`
1	`func`	Yes	`(key: string, value: V, index: number) => string`

Return Type
`T`

[↑ Back to ObjectTools ↑]

filter

ObjectTools.filter(obj: T, func: (key: string, value: V, index: number) => boolean): O

Removes entries from an object based on a predicate function

ObjectTools.filter({a: 1, b: 2, c: 3}, (k, v) => v % 2 === 0) // { b: 2 }

#	Parameter Name	Required	Type
0	`obj`	Yes	`T`
1	`func`	Yes	`(key: string, value: V, index: number) => boolean`

Return Type
`O`

[↑ Back to ObjectTools ↑]

clean

ObjectTools.clean(obj: T): O

Removes properties with undefined values

ObjectTools.clean({a: 1, b: undefined, c: 3}) // { a: 1, c: 3 }

#	Parameter Name	Required	Type
0	`obj`	Yes	`T`

Return Type
`O`

[↑ Back to ObjectTools ↑]

invert

ObjectTools.invert(obj: Ti): To

Inverts the keys and values of an object

ObjectTools.invert({ a: 'foo', b: 'bar' }); // { foo: 'a', bar: 'b'}

#	Parameter Name	Required	Type
0	`obj`	Yes	`Ti`

Return Type
`To`

[↑ Back to ObjectTools ↑]

StringTools

A collection of string utilities

StringTools

[↑ Back to top ↑]

capitalise

StringTools.capitalise(input: string, forceRestToLowerCase: boolean): string

Capitalises the first letter of each word in a string

StringTools.capitalise('hello world'); // 'Hello World'

#	Parameter Name	Required	Type	Default
0	`input`	No	`string`	`''`
1	`forceRestToLowerCase`	No	`boolean`	`true`

Return Type
`string`

[↑ Back to StringTools ↑]

angloise

StringTools.angloise(input: string): string

Remove accents from a string

StringTools.angloise('éèêë'); // 'eeee'

#	Parameter Name	Required	Type
0	`input`	Yes	`string`

Return Type
`string`

[↑ Back to StringTools ↑]

clean

StringTools.clean(input: string): string

Remove accents and non alphanumerics from a string

StringTools.clean('éèêë_--ab0'); // 'eeeeab0'

#	Parameter Name	Required	Type	Default
0	`input`	No	`string`	`''`

Return Type
`string`

[↑ Back to StringTools ↑]

repeat

StringTools.repeat(maxLength: number, repeated: string): string

Repeat the given string n times

StringTools.repeat(5, '-') // '-----'
StringTools.repeat(1, '-') // '-'
StringTools.repeat(0, '-') // ''
StringTools.repeat(-1, '-') // ''

#	Parameter Name	Required	Type
0	`maxLength`	Yes	`number`
1	`repeated`	Yes	`string`

Return Type
`string`

[↑ Back to StringTools ↑]

makeRegExpSafe

StringTools.makeRegExpSafe(text: string): string

Makes a string safe to use in a RegExp

const textWithSpecChars = '$^*+?.()|{}[]\\';
const longText = `A long line with ${textWithSpecChars} in it`; // 'A long line with $^*+?.()|{}[]\ in it'

const safeText = makeRegExpSafe(textWithSpecChars); // '\$\^\*\+\?\.\(\)\|\{\}\[\]\\'
const regex = new RegExp(safeText);
longText.replace(regex, 'foobar'); // 'A long line with foobar in it'

longText.replace(new RegExp(makeRegExpSafe(textWithSpecChars)), 'foobar'); // 'A long line with foobar in it'

#	Parameter Name	Required	Type
0	`text`	Yes	`string`

Return Type
`string`

[↑ Back to StringTools ↑]

replaceAll

StringTools.replaceAll(text: string, searchValue: string | RegExp, replacer: string | ((substring: string, ...args: any[]) => string)): string

'Polyfill' replacement for String.prototype.replaceAll, but uses String.prototype.replace (better backwards compatibility)

Accepts a string or RegExp as the searchValue, and a string or function as the replacer.

const input = 'the quick brown fox jumps over the lazy dog';

StringTools.replaceAll(input, /A|E|I|O|U/i, (match) => match.toUpperCase()) // 'thE qUIck brOwn fOx jUmps OvEr thE lAzy dOg'
StringTools.replaceAll(input, /A|E|I|O|U/i, '#') // 'th# q##ck br#wn f#x j#mps #v#r th# l#zy d#g'
StringTools.replaceAll(input, 'o', (match) => match.toUpperCase()) // 'the quick brOwn fOx jumps Over the lazy dOg'
StringTools.replaceAll(input, 'o', '#') // 'the quick br#wn f#x jumps #ver the lazy d#g'

#	Parameter Name	Required	Type
0	`text`	Yes	`string`
1	`searchValue`	Yes	`string \| RegExp`
2	`replacer`	Yes	`string \| ((substring: string, ...args: any[]) => string)`

Return Type
`string`

[↑ Back to StringTools ↑]

randomId

StringTools.randomId(prefix: string, suffix: string): string

Generate a random ID.

Provides a random string of 10 alphanumeric characters, with the option to prefix and/or suffix the string.

Note: This is a very simple random ID generator, and is not suitable for use in security contexts, and does not guarantee uniqueness.

StringTools.randomId(); // 'du9876optw'
StringTools.randomId(); // '7xf8kewrkf'
StringTools.randomId(); // 'bums15yb9n'
StringTools.randomId(); // '8tcl55y4u1'
StringTools.randomId(); // '41pxan1bog'
StringTools.randomId(); // '122pa9czh4'
StringTools.randomId(); // 'iu7xappxtz'

StringTools.randomId('foo-'); // 'foo-xpynpfiz06'
StringTools.randomId('', '-bar'); // 'dpyq3i2uwq-bar'
StringTools.randomId('foo-', '-bar'); // 'foo-wapluosnf6-bar'

#	Parameter Name	Required	Type	Default
0	`prefix`	No	`string`	`''`
1	`suffix`	No	`string`	`''`

Return Type
`string`

[↑ Back to StringTools ↑]

clx

clx(...args: ClxType[]): string
StringTools.clx(...args: ClxType[]): string

Composes a className from a list of strings, conditional objects and arrays.

Accepts the different ways of supplying classes in AngularJS (ng-class) and returns a single string (so suitable for React).

clx('hello') // 'hello'
clx('foo', 'bar') // 'foo bar'
clx('foo', conditionA && 'bar') // 'foo'
clx('abc', conditionB && 'def') // 'abc def'
clx({'lorem': conditionA, 'ipsum': conditionB}) // 'ipsum'

#	Parameter Name	Required	Type
0…	`args`	No	`ClxType[]`

Return Type
`string`

[↑ Back to StringTools ↑]

Case Manipulators

toCamelCase

StringTools.toCamelCase(input: string | string[], capitaliseFirst: boolean): string
StringTools.fromSlugCase.toCamelCase(input: string | string[], capitaliseFirst: boolean): string
StringTools.fromSnakeCase.toCamelCase(input: string | string[], capitaliseFirst: boolean): string
StringTools.fromSpaced.toCamelCase(input: string | string[], capitaliseFirst: boolean): string
StringTools.fromCamelCase.toCamelCase(input: string | string[], capitaliseFirst: boolean): string

Convert a string to camel case (e.g. thisIsCamelCase)

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string \| string[]`
1	`capitaliseFirst`	No	`boolean`	`false`

Return Type
`string`

[↑ Back to StringTools ↑]

toLowerCamelCase

StringTools.toLowerCamelCase(input: string | string[]): string
StringTools.fromSlugCase.toLowerCamelCase(input: string | string[]): string
StringTools.fromSnakeCase.toLowerCamelCase(input: string | string[]): string
StringTools.fromSpaced.toLowerCamelCase(input: string | string[]): string
StringTools.fromCamelCase.toLowerCamelCase(input: string | string[]): string

Convert a string to lower camel case (e.g. thisIsLowerCamelCase)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toUpperCamelCase

StringTools.toUpperCamelCase(input: string | string[]): string
StringTools.fromSlugCase.toUpperCamelCase(input: string | string[]): string
StringTools.fromSnakeCase.toUpperCamelCase(input: string | string[]): string
StringTools.fromSpaced.toUpperCamelCase(input: string | string[]): string
StringTools.fromCamelCase.toUpperCamelCase(input: string | string[]): string

Convert a string to upper camel case (e.g. ThisIsLowerCamelCase)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toCharacterSeparated

StringTools.toCharacterSeparated(input: string | string[], char: string, toUpper: boolean): string
StringTools.fromSlugCase.toCharacterSeparated(input: string | string[], char: string, toUpper: boolean): string
StringTools.fromSnakeCase.toCharacterSeparated(input: string | string[], char: string, toUpper: boolean): string
StringTools.fromSpaced.toCharacterSeparated(input: string | string[], char: string, toUpper: boolean): string
StringTools.fromCamelCase.toCharacterSeparated(input: string | string[], char: string, toUpper: boolean): string

Convert a string to text where words are separated by a given character (e.g. this#is#character#separated)

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string \| string[]`
1	`char`	No	`string`	`','`
2	`toUpper`	No	`boolean`	`false`

Return Type
`string`

[↑ Back to StringTools ↑]

toSlugCase

StringTools.toSlugCase(input: string | string[], toUpper: boolean): string
StringTools.fromSlugCase.toSlugCase(input: string | string[], toUpper: boolean): string
StringTools.fromSnakeCase.toSlugCase(input: string | string[], toUpper: boolean): string
StringTools.fromSpaced.toSlugCase(input: string | string[], toUpper: boolean): string
StringTools.fromCamelCase.toSlugCase(input: string | string[], toUpper: boolean): string

Convert a string to camel case (e.g. this-is-slug-case)

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string \| string[]`
1	`toUpper`	No	`boolean`	`false`

Return Type
`string`

[↑ Back to StringTools ↑]

toLowerSlugCase

StringTools.toLowerSlugCase(input: string | string[]): string
StringTools.fromSlugCase.toLowerSlugCase(input: string | string[]): string
StringTools.fromSnakeCase.toLowerSlugCase(input: string | string[]): string
StringTools.fromSpaced.toLowerSlugCase(input: string | string[]): string
StringTools.fromCamelCase.toLowerSlugCase(input: string | string[]): string

Convert a string to lower slug case (e.g. this-is-lower-slug-case)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toUpperSlugCase

StringTools.toUpperSlugCase(input: string | string[]): string
StringTools.fromSlugCase.toUpperSlugCase(input: string | string[]): string
StringTools.fromSnakeCase.toUpperSlugCase(input: string | string[]): string
StringTools.fromSpaced.toUpperSlugCase(input: string | string[]): string
StringTools.fromCamelCase.toUpperSlugCase(input: string | string[]): string

Convert a string to upper camel case (e.g. THIS-IS-UPPER-SLUG-CASE)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toSnakeCase

StringTools.toSnakeCase(input: string | string[], toUpper: boolean): string
StringTools.fromSlugCase.toSnakeCase(input: string | string[], toUpper: boolean): string
StringTools.fromSnakeCase.toSnakeCase(input: string | string[], toUpper: boolean): string
StringTools.fromSpaced.toSnakeCase(input: string | string[], toUpper: boolean): string
StringTools.fromCamelCase.toSnakeCase(input: string | string[], toUpper: boolean): string

Convert a string to snake case (e.g. this_is_snake_case)

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string \| string[]`
1	`toUpper`	No	`boolean`	`false`

Return Type
`string`

[↑ Back to StringTools ↑]

toLowerSnakeCase

StringTools.toLowerSnakeCase(input: string | string[]): string
StringTools.fromSlugCase.toLowerSnakeCase(input: string | string[]): string
StringTools.fromSnakeCase.toLowerSnakeCase(input: string | string[]): string
StringTools.fromSpaced.toLowerSnakeCase(input: string | string[]): string
StringTools.fromCamelCase.toLowerSnakeCase(input: string | string[]): string

Convert a string to lower snake case (e.g. this_is_lower_snake_case)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toUpperSnakeCase

StringTools.toUpperSnakeCase(input: string | string[]): string
StringTools.fromSlugCase.toUpperSnakeCase(input: string | string[]): string
StringTools.fromSnakeCase.toUpperSnakeCase(input: string | string[]): string
StringTools.fromSpaced.toUpperSnakeCase(input: string | string[]): string
StringTools.fromCamelCase.toUpperSnakeCase(input: string | string[]): string

Convert a string to upper snake case (e.g. THIS_IS_UPPER_SNAKE_CASE)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toSpaced

StringTools.toSpaced(input: string | string[], toUpper: boolean): string
StringTools.fromSlugCase.toSpaced(input: string | string[], toUpper: boolean): string
StringTools.fromSnakeCase.toSpaced(input: string | string[], toUpper: boolean): string
StringTools.fromSpaced.toSpaced(input: string | string[], toUpper: boolean): string
StringTools.fromCamelCase.toSpaced(input: string | string[], toUpper: boolean): string

Convert a string to spaced case (e.g. this is spaced case)

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string \| string[]`
1	`toUpper`	No	`boolean`	`false`

Return Type
`string`

[↑ Back to StringTools ↑]

toLowerSpaced

StringTools.toLowerSpaced(input: string | string[]): string
StringTools.fromSlugCase.toLowerSpaced(input: string | string[]): string
StringTools.fromSnakeCase.toLowerSpaced(input: string | string[]): string
StringTools.fromSpaced.toLowerSpaced(input: string | string[]): string
StringTools.fromCamelCase.toLowerSpaced(input: string | string[]): string

Convert a string to lower spaced case (e.g. this is lower spaced case)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toUpperSpaced

StringTools.toUpperSpaced(input: string | string[]): string
StringTools.fromSlugCase.toUpperSpaced(input: string | string[]): string
StringTools.fromSnakeCase.toUpperSpaced(input: string | string[]): string
StringTools.fromSpaced.toUpperSpaced(input: string | string[]): string
StringTools.fromCamelCase.toUpperSpaced(input: string | string[]): string

Convert a string to upper spaced case (e.g. THIS IS UPPER SPACED CASE)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

toCapitalisedSpaced

StringTools.toCapitalisedSpaced(input: string | string[]): string
StringTools.fromSlugCase.toCapitalisedSpaced(input: string | string[]): string
StringTools.fromSnakeCase.toCapitalisedSpaced(input: string | string[]): string
StringTools.fromSpaced.toCapitalisedSpaced(input: string | string[]): string
StringTools.fromCamelCase.toCapitalisedSpaced(input: string | string[]): string

Convert a string to capitalised spaced case (e.g. This Is Capitalised Spaced Case)

#	Parameter Name	Required	Type
0	`input`	Yes	`string \| string[]`

Return Type
`string`

[↑ Back to StringTools ↑]

fromSlugCase

StringTools.fromSlugCase.toLowerCamelCase;
StringTools.fromSlugCase.toUpperCamelCase;
StringTools.fromSlugCase.toCamelCase;
StringTools.fromSlugCase.toLowerSlugCase;
StringTools.fromSlugCase.toUpperSlugCase;
StringTools.fromSlugCase.toSlugCase;
StringTools.fromSlugCase.toLowerSnakeCase;
StringTools.fromSlugCase.toUpperSnakeCase;
StringTools.fromSlugCase.toSnakeCase;
StringTools.fromSlugCase.toLowerSpaced;
StringTools.fromSlugCase.toUpperSpaced;
StringTools.fromSlugCase.toCapitalisedSpaced;
StringTools.fromSlugCase.toSpaced;
StringTools.fromSlugCase.toCharacterSeparated;

Has the following methods:

[↑ Back to StringTools ↑]

fromSnakeCase

StringTools.fromSnakeCase.toLowerCamelCase;
StringTools.fromSnakeCase.toUpperCamelCase;
StringTools.fromSnakeCase.toCamelCase;
StringTools.fromSnakeCase.toLowerSlugCase;
StringTools.fromSnakeCase.toUpperSlugCase;
StringTools.fromSnakeCase.toSlugCase;
StringTools.fromSnakeCase.toLowerSnakeCase;
StringTools.fromSnakeCase.toUpperSnakeCase;
StringTools.fromSnakeCase.toSnakeCase;
StringTools.fromSnakeCase.toLowerSpaced;
StringTools.fromSnakeCase.toUpperSpaced;
StringTools.fromSnakeCase.toCapitalisedSpaced;
StringTools.fromSnakeCase.toSpaced;
StringTools.fromSnakeCase.toCharacterSeparated;

Has the following methods:

[↑ Back to StringTools ↑]

fromSpaced

StringTools.fromSpaced.toLowerCamelCase;
StringTools.fromSpaced.toUpperCamelCase;
StringTools.fromSpaced.toCamelCase;
StringTools.fromSpaced.toLowerSlugCase;
StringTools.fromSpaced.toUpperSlugCase;
StringTools.fromSpaced.toSlugCase;
StringTools.fromSpaced.toLowerSnakeCase;
StringTools.fromSpaced.toUpperSnakeCase;
StringTools.fromSpaced.toSnakeCase;
StringTools.fromSpaced.toLowerSpaced;
StringTools.fromSpaced.toUpperSpaced;
StringTools.fromSpaced.toCapitalisedSpaced;
StringTools.fromSpaced.toSpaced;
StringTools.fromSpaced.toCharacterSeparated;

Has the following methods:

[↑ Back to StringTools ↑]

fromCamelCase

StringTools.fromCamelCase.toLowerCamelCase;
StringTools.fromCamelCase.toUpperCamelCase;
StringTools.fromCamelCase.toCamelCase;
StringTools.fromCamelCase.toLowerSlugCase;
StringTools.fromCamelCase.toUpperSlugCase;
StringTools.fromCamelCase.toSlugCase;
StringTools.fromCamelCase.toLowerSnakeCase;
StringTools.fromCamelCase.toUpperSnakeCase;
StringTools.fromCamelCase.toSnakeCase;
StringTools.fromCamelCase.toLowerSpaced;
StringTools.fromCamelCase.toUpperSpaced;
StringTools.fromCamelCase.toCapitalisedSpaced;
StringTools.fromCamelCase.toSpaced;
StringTools.fromCamelCase.toCharacterSeparated;

Has the following methods:

[↑ Back to StringTools ↑]

matchBrackets

Tools for matching corresponding brackets in a string

[↑ Back to StringTools ↑]

unique

StringTools.matchBrackets.unique(input: string, replaceSymbols: Partial<BracketReplaceSymbols>): string

Replace brackets with symbols and with a unique ID for each bracket pair of each type

const example = '{name: "Jane", info: { age: 31, interests: ["Tennis", "Board Games"] }}';
const uniqued = matchBrackets.unique(example);
uniqued; // '❴0✧name: "Jane", info: ❴1✧ age: 31, interests: ❲0✧"Tennis", "Board Games"❳0✧ ❵1✧❵0✧'

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string`
1	`replaceSymbols`	No	`Partial<BracketReplaceSymbols>`	`{}`

Return Type
`string`

[↑ Back to StringTools ↑]

depth

StringTools.matchBrackets.depth(input: string, replaceSymbols: Partial<BracketReplaceSymbols>): string

Replace brackets with symbols and with a numbers for how deep each bracket pair is for that bracket type

const example = '{name: "Jane", info: { age: 31, interests: ["Tennis", "Board Games"] }}';
const depthed = matchBrackets.depth(example);
depthed; // '❴0✧name: "Jane", info: ❴1✧ age: 31, interests: ❲0✧"Tennis", "Board Games"❳0✧ ❵1✧❵0✧'

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string`
1	`replaceSymbols`	No	`Partial<BracketReplaceSymbols>`	`{}`

Return Type
`string`

[↑ Back to StringTools ↑]

clean

StringTools.matchBrackets.clean(input: string, replaceSymbols: Partial<BracketReplaceSymbols>): string

Return a string that's been matched with unique or depth and replace the symbols with the original brackets. Also works with substrings of such strings.

const example = '{name: "Jane", info: { age: 31, interests: ["Tennis", "Board Games"] }}';
const uniqued = matchBrackets.unique(example);
uniqued; // '❴0✧name: "Jane", info: ❴1✧ age: 31, interests: ❲0✧"Tennis", "Board Games"❳0✧ ❵1✧❵0✧'

const cleaned = matchBrackets.clean(uniqued);
cleaned; // '{name: "Jane", info: { age: 31, interests: ["Tennis", "Board Games"] }}'

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string`
1	`replaceSymbols`	No	`Partial<BracketReplaceSymbols>`	`{}`

Return Type
`string`

[↑ Back to StringTools ↑]

grabDepth

StringTools.matchBrackets.grabDepth(input: string, bracketType: '()' | '[]' | '{}' | '<>' | 'round' | 'square' | 'curly' | 'angle', depthID: number, replaceSymbols: Partial<BracketReplaceSymbols>): string[]

Obtain all the bracketed substrings of the given bracket type from a string at a given depth.

const example = `[
  [
    [1, 2, 3],
    [4, 5, 6]
  ],
  [
    [7, 8, 9]
  ]
]`;
const grabbed = matchBrackets.grabDepth(example, 'square', 2);
grabbed; // [ '[1, 2, 3]', '[4, 5, 6]', '[7, 8, 9]' ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string`
1	`bracketType`	No	`'()' \| '[]' \| '{}' \| '<>' \| 'round' \| 'square' \| 'curly' \| 'angle'`	`'round'`
2	`depthID`	No	`number`	`0`
3	`replaceSymbols`	No	`Partial<BracketReplaceSymbols>`	`{}`

Return Type
`string[]`

[↑ Back to StringTools ↑]

grabUnique

StringTools.matchBrackets.grabUnique(input: string, bracketType: '()' | '[]' | '{}' | '<>' | 'round' | 'square' | 'curly' | 'angle', uniqueID: number, replaceSymbols: Partial<BracketReplaceSymbols>): string

Obtain all the bracketed substring of the given bracket type from a string with the given unique ID. e.g. if uniqueID is 3, it will return the bracketed substring for the 4th instance of the opening bracket (see StringTools.matchBrackets.unique)

const example = `[
  [
    [1, 2, 3],
    [4, 5, 6]
  ],
  [
    [7, 8, 9]
  ]
]`;
const grabbed = matchBrackets.grabUnique(example, 'square', 3);
grabbed; // '[4, 5, 6]'

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string`
1	`bracketType`	No	`'()' \| '[]' \| '{}' \| '<>' \| 'round' \| 'square' \| 'curly' \| 'angle'`	`'round'`
2	`uniqueID`	No	`number`	`0`
3	`replaceSymbols`	No	`Partial<BracketReplaceSymbols>`	`{}`

Return Type
`string`

[↑ Back to StringTools ↑]

grab

StringTools.matchBrackets.grab(input: string, bracketType: '()' | '[]' | '{}' | '<>' | 'round' | 'square' | 'curly' | 'angle', replaceSymbols: Partial<BracketReplaceSymbols>): string[]

Grab all the bracketed substrings from a string of the given bracket type.

const example = `[[[1, 2, 3], [4, 5, 6]], [[7, 8, 9]]]`;
matchBrackets.grab(example, 'square');
// [
//   '[[[1, 2, 3], [4, 5, 6]], [[7, 8, 9]]]',
//   '[[1, 2, 3], [4, 5, 6]]',
//   '[1, 2, 3]',
//   '[4, 5, 6]',
//   '[[7, 8, 9]]',
//   '[7, 8, 9]'
// ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string`
1	`bracketType`	No	`'()' \| '[]' \| '{}' \| '<>' \| 'round' \| 'square' \| 'curly' \| 'angle'`	`'round'`
2	`replaceSymbols`	No	`Partial<BracketReplaceSymbols>`	`{}`

Return Type
`string[]`

[↑ Back to StringTools ↑]

getReplaceSymbols

StringTools.matchBrackets.getReplaceSymbols(replaceSymbols: Partial<BracketReplaceSymbols>): BracketReplaceSymbols

Get a full set of replace symbols

matchBrackets.getReplaceSymbols();
// {
//   END: '✧',
//   '(': '❪',
//   ')': '❫',
//   '[': '❲',
//   ']': '❳',
//   '{': '❴',
//   '}': '❵',
//   '<': '❰',
//   '>': '❱'
// }

matchBrackets.getReplaceSymbols({
  END: '▣',
  '{': 'START_CURLY',
  '}': 'END_CURLY'
})
// {
//   END: '▣',
//   '(': '❪',
//   ')': '❫',
//   '[': '❲',
//   ']': '❳',
//   '{': 'START_CURLY',
//   '}': 'END_CURLY',
//   '<': '❰',
//   '>': '❱'
// }

#	Parameter Name	Required	Type	Default
0	`replaceSymbols`	No	`Partial<BracketReplaceSymbols>`	`{}`

Return Type
`BracketReplaceSymbols`

[↑ Back to StringTools ↑]

BracketReplaceSymbols

StringTools.matchBrackets.BracketReplaceSymbols;

Type for controlling the symbols used to replace brackets

{
  END: string;
  '(': string;
  ')': string;
  '[': string;
  ']': string;
  '{': string;
  '}': string;
  '<': string;
  '>': string;
}

[↑ Back to StringTools ↑]

MathsTools

A collection of mathematical functions.

Note: The field is 'Mathematics', and so it is 'MathsTools' not ~~'MathTools'~~

MathsTools
- fixFloat
- addAll
- round
  - floorTo
  - roundTo
  - ceilTo
- lerp
- lerpArray
- lerpObj
- clamp
- getOrdinal

[↑ Back to top ↑]

fixFloat

ff(num: number): number
MathsTools.ff(num: number): number
MathsTools.fixFloat(num: number): number

Fixes floating point errors that may occur when adding/subtracting/multiplying/dividing real/float numbers

Can also be used to round numbers to a given precision

Note: 'fixFloat' is not a great name, but it's what I've always called it, so I'm sticking with it. 'ff' is a shorthand alias.

0.1 + 0.2 // 0.30000000000000004
MathsTools.fixFloat(0.1 + 0.2) // 0.3

#	Parameter Name	Required	Type
0	`num`	Yes	`number`

Return Type
`number`

[↑ Back to MathsTools ↑]

addAll

MathsTools.addAll(...nums: number[]): number

Adds all numbers together. Each argument is a number (use spread operator to pass in an array) similar to Math.min/Math.max

MathsTools.addAll(1, 2, 3, 4, 5); // 15

#	Parameter Name	Required	Type
0…	`nums`	No	`number[]`

Return Type
`number`

[↑ Back to MathsTools ↑]

round

floorTo

MathsTools.floorTo(to: number, value: number): number
MathsTools.round.floorTo(to: number, value: number): number

Floors a number down to the nearest multiple of the given number.

MathsTools.round.floorTo(10, 102); // 100
MathsTools.round.floorTo(5, 53); // 50
MathsTools.round.floorTo(0.1, 0.25); // 0.2

#	Parameter Name	Required	Type
0	`to`	Yes	`number`
1	`value`	Yes	`number`

Return Type
`number`

[↑ Back to MathsTools ↑]

roundTo

MathsTools.round.to(to: number, value: number): number
MathsTools.roundTo(to: number, value: number): number
MathsTools.round.roundTo(to: number, value: number): number

Floors a number down to the nearest multiple of the given number.

MathsTools.round.to(10, 102); // 100
MathsTools.round.to(5, 53); // 55
MathsTools.round.to(0.1, 0.25); // 0.3

#	Parameter Name	Required	Type
0	`to`	Yes	`number`
1	`value`	Yes	`number`

Return Type
`number`

[↑ Back to MathsTools ↑]

ceilTo

MathsTools.ceilTo(to: number, value: number): number
MathsTools.round.ceilTo(to: number, value: number): number

Floors a number down to the nearest multiple of the given number.

MathsTools.round.ceilTo(10, 102); // 110
MathsTools.round.ceilTo(5, 53); // 55
MathsTools.round.ceilTo(0.1, 0.25); // 0.3

#	Parameter Name	Required	Type
0	`to`	Yes	`number`
1	`value`	Yes	`number`

Return Type
`number`

[↑ Back to MathsTools ↑]

lerp

MathsTools.lerp(progress: number, fromVal: number, toVal: number): number

Linearly interpolates between two values.

MathsTools.lerp(0.5, 0, 10); // 5

#	Parameter Name	Required	Type
0	`progress`	Yes	`number`
1	`fromVal`	Yes	`number`
2	`toVal`	Yes	`number`

Return Type
`number`

[↑ Back to MathsTools ↑]

lerpArray

MathsTools.lerpArray(progress: number, fromArr: number[], toArr: number[]): number[]

Linearly interpolates between the values of 2 arrays.

MathsTools.lerpArray(0.5, [0, 0, 0], [10, 100, 1000]) // [5, 50, 500]

#	Parameter Name	Required	Type
0	`progress`	Yes	`number`
1	`fromArr`	Yes	`number[]`
2	`toArr`	Yes	`number[]`

Return Type
`number[]`

[↑ Back to MathsTools ↑]

lerpObj

MathsTools.lerpObj(progress: number, fromObj: T, toObj: T): T

Linearly interpolates between the values of 2 arrays.

MathsTools.lerpObj(0.5, {'ARS': 0, 'CHE': 0, 'FUL': 0}, {'ARS': 100, 'CHE': 10, 'FUL': 20}) // {'ARS': 50, 'CHE': 5, 'FUL': 10}

#	Parameter Name	Required	Type
0	`progress`	Yes	`number`
1	`fromObj`	Yes	`T`
2	`toObj`	Yes	`T`

Return Type
`T`

[↑ Back to MathsTools ↑]

clamp

MathsTools.clamp(value: number, min: number, max: number): number

Clamps a value between a min and max.

MathsTools.clamp(5, 0, 10); // 5
MathsTools.clamp(-5, 0, 10); // 0

#	Parameter Name	Required	Type
0	`value`	Yes	`number`
1	`min`	Yes	`number`
2	`max`	Yes	`number`

Return Type
`number`

[↑ Back to MathsTools ↑]

getOrdinal

MathsTools.getOrdinal(num: number): "th" | "st" | "nd" | "rd"

Gets the ordinal suffix for a number.

Note: all numbers are treated as positive. Note: all decimals are 'th' (e.g. 1.2 is '1.2th') as they are tenth, hundredth, thousandth, etc.

MathsTools.getOrdinal(1); // 'st'
MathsTools.getOrdinal(2); // 'nd'
MathsTools.getOrdinal(3); // 'rd'
MathsTools.getOrdinal(4); // 'th'

MathsTools.getOrdinal(11); // 'th'
MathsTools.getOrdinal(12); // 'th'
MathsTools.getOrdinal(13); // 'th'
MathsTools.getOrdinal(14); // 'th'

MathsTools.getOrdinal(21); // 'st'
MathsTools.getOrdinal(22); // 'nd'
MathsTools.getOrdinal(23); // 'rd'
MathsTools.getOrdinal(24); // 'th'

#	Parameter Name	Required	Type	Default
0	`num`	No	`number`	`0`

Return Type
`"th" \| "st" \| "nd" \| "rd"`

[↑ Back to MathsTools ↑]

PromiseTools

A collection of promise utilities

PromiseTools
- getDeferred
- all
- allLimit
- each
- eachLimit
- map
- mapLimit
- allObj
- allLimitObj
- PromiseFunc
- PromiseItem
- DeferredPromise

[↑ Back to top ↑]

getDeferred

getDeferred(): DeferredPromise<T>
PromiseTools.getDeferred(): DeferredPromise<T>

A deferred promise

import { getDeferred } from 'swiss-ak';

const run = () => {
  const deferred = getDeferred<number>();

  doSomethingWithACallback('a', 'b', (err: Error, result: number) => {
    // callback (just an example - don't actually do this this way)
    if (err) return deferred.reject(err);
    deferred.resolve(result);
  });

  return deferred.promise;
};

const luckyNumber: number = await run();

Return Type
`DeferredPromise<T>`

[↑ Back to PromiseTools ↑]

all

all(items: PromiseTools.PromiseItem<T>[]): Promise<T[]>
PromiseTools.all(items: PromiseTools.PromiseItem<T>[]): Promise<T[]>

Similar to Promise.all, but accepts values, functions, and promises.

#	Parameter Name	Required	Type
0	`items`	Yes	`PromiseTools.PromiseItem<T>[]`

Return Type
`Promise<T[]>`

[↑ Back to PromiseTools ↑]

allLimit

allLimit(limit: number, items: PromiseTools.PromiseItem<T>[], noThrow: boolean): Promise<T[]>
PromiseTools.allLimit(limit: number, items: PromiseTools.PromiseItem<T>[], noThrow: boolean): Promise<T[]>

Like Promise.all, but limits the numbers of concurrently running items.

Takes an array of functions (that return Promises), rather than an array of Promises

import { PromiseTools, timer, ms, seconds } from 'swiss-ak';

const give = async (delay: ms, result: number, label: string) => {
  await waitFor(delay);
  timer.end(label);
  return result;
};

timer.start('allLimit', 'a', 'b', 'c', 'd');

const results = PromiseTools.allLimit<number>(2, [
  give(seconds(5), 1, 'a'),
  give(seconds(5), 2, 'b'),
  give(seconds(5), 3, 'c'),
  give(seconds(5), 4, 'd')
]);

timer.end('allLimit');

console.log(results); // [ 1, 2, 3, 4 ]

timer.log();
// Times:
// 	allLimit: 10s
// 	a: 5s
// 	b: 5s
// 	c: 10s
// 	d: 10s

#	Parameter Name	Required	Type	Default
0	`limit`	Yes	`number`
1	`items`	Yes	`PromiseTools.PromiseItem<T>[]`
2	`noThrow`	No	`boolean`	`false`

Return Type
`Promise<T[]>`

[↑ Back to PromiseTools ↑]

each

each(items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<any>): Promise<void>
PromiseTools.each(items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<any>): Promise<void>

Run an async function against each item in an array

import { PromiseTools, ms, seconds, wait } from 'swiss-ak';

const arr = [1, 2, 3, 4];

await PromiseTools.each<number>(arr, async (val: number) => {
  await wait(seconds(2));
  sendToSomewhere(val);
});
console.log(''); // after 2 seconds

#	Parameter Name	Required	Type
0	`items`	Yes	`Ti[]`
1	`func`	Yes	`(item: Ti, index: number, array: Ti[]) => Promise<any>`

Return Type
`Promise<void>`

[↑ Back to PromiseTools ↑]

eachLimit

eachLimit(limit: number, items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<any>): Promise<void>
PromiseTools.eachLimit(limit: number, items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<any>): Promise<void>

Run an async function against each item in an array, limiting the number of items that can run concurrently.

See PromiseTools.allLimit for information about limited functions.

import { PromiseTools, ms, seconds, wait } from 'swiss-ak';

const arr = [1, 2, 3, 4];

await PromiseTools.eachLimit<number>(2, arr, async (val: number) => {
  await wait(seconds(2));
  sendToSomewhere(val);
});
console.log(''); // after 4 seconds

#	Parameter Name	Required	Type
0	`limit`	Yes	`number`
1	`items`	Yes	`Ti[]`
2	`func`	Yes	`(item: Ti, index: number, array: Ti[]) => Promise<any>`

Return Type
`Promise<void>`

[↑ Back to PromiseTools ↑]

map

map(items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<To>): Promise<To[]>
PromiseTools.map(items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<To>): Promise<To[]>

Run an async map function against each item in an array, mapping the results to a returned array

import { PromiseTools, ms, seconds, wait } from 'swiss-ak';

const arr = [1, 2, 3, 4];

const mapped = await PromiseTools.map<number>(arr, async (val: number) => {
  await wait(seconds(2));
  return val * 2;
});

console.log(mapped); // [2, 4, 6, 8] (after 2 seconds)

#	Parameter Name	Required	Type
0	`items`	Yes	`Ti[]`
1	`func`	Yes	`(item: Ti, index: number, array: Ti[]) => Promise<To>`

Return Type
`Promise<To[]>`

[↑ Back to PromiseTools ↑]

mapLimit

mapLimit(limit: number, items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<To>): Promise<To[]>
PromiseTools.mapLimit(limit: number, items: Ti[], func: (item: Ti, index: number, array: Ti[]) => Promise<To>): Promise<To[]>

Run an async map function against each item in an array, mapping the results to a returned array, and limiting the number of items that can run concurrently.

See PromiseTools.allLimit for information about limited functions.

import { PromiseTools, ms, seconds, wait } from 'swiss-ak';

const arr = [1, 2, 3, 4];

const mapped = await PromiseTools.mapLimit<number>(2, arr, async (val: number) => {
  await wait(seconds(2));
  return val * 2;
});

console.log(mapped); // [2, 4, 6, 8] (after 4 seconds)

#	Parameter Name	Required	Type
0	`limit`	Yes	`number`
1	`items`	Yes	`Ti[]`
2	`func`	Yes	`(item: Ti, index: number, array: Ti[]) => Promise<To>`

Return Type
`Promise<To[]>`

[↑ Back to PromiseTools ↑]

allObj

allObj(input: T): Promise<UnWrapPromiseObject<T>>
PromiseTools.allObj(input: T): Promise<UnWrapPromiseObject<T>>

Like Promise.all, but pass/receive objects rather than arrays

import { PromiseTools, timer, ms, seconds } from 'swiss-ak';

const give = async (delay: ms, result: number, label: string) => {
  await waitFor(delay);
  timer.end(label);
  return result;
};

timer.start('allObj', 'a', 'b', 'c');

const results = PromiseTools.allObj<number>({
  a: give(seconds(10), 1, 'a'),
  b: give(seconds(15), 2, 'b'),
  c: give(seconds(20), 3, 'c')
});

timer.end('allObj');

console.log(results); // { a: 1, b: 2, c: 3 }

timer.log();
// Times:
// 	allObj: 20s
// 	a: 10s
// 	b: 15s
// 	c: 20s

#	Parameter Name	Required	Type
0	`input`	Yes	`T`

Return Type
`Promise<UnWrapPromiseObject<T>>`

[↑ Back to PromiseTools ↑]

allLimitObj

allLimitObj(limit: number, input: T, noThrow: boolean): Promise<UnWrapPromiseObject<T>>
PromiseTools.allLimitObj(limit: number, input: T, noThrow: boolean): Promise<UnWrapPromiseObject<T>>

A mix of allObj and allLimit.

Takes an array of functions (that return Promises), and limits the numbers of concurrently running items.

import { PromiseTools, timer, ms, seconds } from 'swiss-ak';

const give = async (delay: ms, result: number, label: string) => {
  await waitFor(delay);
  timer.end(label);
  return result;
};

timer.start('allLimitObj', 'a', 'b', 'c', 'd');

const results = PromiseTools.allLimitObj<number>(2, {
  a: give(seconds(5), 1, 'a'),
  b: give(seconds(5), 2, 'b'),
  c: give(seconds(5), 3, 'c'),
  d: give(seconds(5), 4, 'd')
});

timer.end('allLimitObj');

console.log(results); // { a: 1, b: 2, c: 3, d: 4 }

timer.log();
// Times:
// 	allLimitObj: 10s
// 	a: 5s
// 	b: 5s
// 	c: 10s
// 	d: 10s

#	Parameter Name	Required	Type	Default
0	`limit`	Yes	`number`
1	`input`	Yes	`T`
2	`noThrow`	No	`boolean`	`false`

Return Type
`Promise<UnWrapPromiseObject<T>>`

[↑ Back to PromiseTools ↑]

PromiseFunc

PromiseFunc<T>;

A function that returns a promise

[↑ Back to PromiseTools ↑]

PromiseItem

PromiseItem<T>;

A promise, a function that returns a promise (see PromiseFunc), or a value

Accepted by PromiseTools.all, PromiseTools.allLimit, PromiseTools.allObj, and PromiseTools.allLimitObj in place of promises

[↑ Back to PromiseTools ↑]

DeferredPromise

DeferredPromise;
PromiseTools.DeferredPromise;

A deferred promise

[↑ Back to PromiseTools ↑]

ColourTools

A collection of functions for working with colours.

ColourTools
- ColourValues
- HSLValues
- namedColours
- parse
- toHex
- getLuminance
- toYUV
- toHSL
- fromHSL
- invertColour
- getContrastedColour
- getLimitedColour

[↑ Back to top ↑]

ColourValues

ColourTools.ColourValues;

A type with 3 numbers:

red [0-255]
green [0-255]
blue [0-255]

[↑ Back to ColourTools ↑]

HSLValues

ColourTools.HSLValues;

A type with 3 numbers:

hue [0-360]
saturation [0-100]
lightness [0-100]

[↑ Back to ColourTools ↑]

namedColours

ColourTools.namedColours;

A dictionary of different colour names and their RGB values

Name	RGB	Hex
aliceblue	240, 248, 255	#f0f8ff
antiquewhite	250, 235, 215	#faebd7
aqua	0, 255, 255	#00ffff
aquamarine	127, 255, 212	#7fffd4
azure	240, 255, 255	#f0ffff
beige	245, 245, 220	#f5f5dc
bisque	255, 228, 196	#ffe4c4
black	0, 0, 0	#000000
blanchedalmond	255, 235, 205	#ffebcd
blue	0, 0, 255	#0000ff
blueviolet	138, 43, 226	#8a2be2
brown	165, 42, 42	#a52a2a
burlywood	222, 184, 135	#deb887
cadetblue	95, 158, 160	#5f9ea0
chartreuse	127, 255, 0	#7fff00
chocolate	210, 105, 30	#d2691e
coral	255, 127, 80	#ff7f50
cornflowerblue	100, 149, 237	#6495ed
cornsilk	255, 248, 220	#fff8dc
crimson	220, 20, 60	#dc143c
cyan	0, 255, 255	#00ffff
darkblue	0, 0, 139	#00008b
darkcyan	0, 139, 139	#008b8b
darkgoldenrod	184, 134, 11	#b8860b
darkgray	169, 169, 169	#a9a9a9
darkgreen	0, 100, 0	#006400
darkgrey	169, 169, 169	#a9a9a9
darkkhaki	189, 183, 107	#bdb76b
darkmagenta	139, 0, 139	#8b008b
darkolivegreen	85, 107, 47	#556b2f
darkorange	255, 140, 0	#ff8c00
darkorchid	153, 50, 204	#9932cc
darkred	139, 0, 0	#8b0000
darksalmon	233, 150, 122	#e9967a
darkseagreen	143, 188, 143	#8fbc8f
darkslateblue	72, 61, 139	#483d8b
darkslategray	47, 79, 79	#2f4f4f
darkslategrey	47, 79, 79	#2f4f4f
darkturquoise	0, 206, 209	#00ced1
darkviolet	148, 0, 211	#9400d3
deeppink	255, 20, 147	#ff1493
deepskyblue	0, 191, 255	#00bfff
dimgray	105, 105, 105	#696969
dimgrey	105, 105, 105	#696969
dodgerblue	30, 144, 255	#1e90ff
firebrick	178, 34, 34	#b22222
floralwhite	255, 250, 240	#fffaf0
forestgreen	34, 139, 34	#228b22
fractal	128, 128, 128	#808080
fuchsia	255, 0, 255	#ff00ff
gainsboro	220, 220, 220	#dcdcdc
ghostwhite	248, 248, 255	#f8f8ff
gold	255, 215, 0	#ffd700
goldenrod	218, 165, 32	#daa520
gray0	0, 0, 0	#000000
gray1	3, 3, 3	#030303
gray2	5, 5, 5	#050505
gray3	8, 8, 8	#080808
gray4	10, 10, 10	#0a0a0a
gray5	13, 13, 13	#0d0d0d
gray6	15, 15, 15	#0f0f0f
gray7	18, 18, 18	#121212
gray8	20, 20, 20	#141414
gray9	23, 23, 23	#171717
gray10	26, 26, 26	#1a1a1a
gray11	28, 28, 28	#1c1c1c
gray12	31, 31, 31	#1f1f1f
gray13	33, 33, 33	#212121
gray14	36, 36, 36	#242424
gray15	38, 38, 38	#262626
gray16	41, 41, 41	#292929
gray17	43, 43, 43	#2b2b2b
gray18	46, 46, 46	#2e2e2e
gray19	48, 48, 48	#303030
gray20	51, 51, 51	#333333
gray21	54, 54, 54	#363636
gray22	56, 56, 56	#383838
gray23	59, 59, 59	#3b3b3b
gray24	61, 61, 61	#3d3d3d
gray25	64, 64, 64	#404040
gray26	66, 66, 66	#424242
gray27	69, 69, 69	#454545
gray28	71, 71, 71	#474747
gray29	74, 74, 74	#4a4a4a
gray30	77, 77, 77	#4d4d4d
gray31	79, 79, 79	#4f4f4f
gray32	82, 82, 82	#525252
gray33	84, 84, 84	#545454
gray34	87, 87, 87	#575757
gray35	89, 89, 89	#595959
gray36	92, 92, 92	#5c5c5c
gray37	94, 94, 94	#5e5e5e
gray38	97, 97, 97	#616161
gray39	99, 99, 99	#636363
gray40	102, 102, 102	#666666
gray41	105, 105, 105	#696969
gray42	107, 107, 107	#6b6b6b
gray43	110, 110, 110	#6e6e6e
gray44	112, 112, 112	#707070
gray45	115, 115, 115	#737373
gray46	117, 117, 117	#757575
gray47	120, 120, 120	#787878
gray48	122, 122, 122	#7a7a7a
gray49	125, 125, 125	#7d7d7d
gray50	127, 127, 127	#7f7f7f
gray51	130, 130, 130	#828282
gray52	133, 133, 133	#858585
gray53	135, 135, 135	#878787
gray54	138, 138, 138	#8a8a8a
gray55	140, 140, 140	#8c8c8c
gray56	143, 143, 143	#8f8f8f
gray57	145, 145, 145	#919191
gray58	148, 148, 148	#949494
gray59	150, 150, 150	#969696
gray60	153, 153, 153	#999999
gray61	156, 156, 156	#9c9c9c
gray62	158, 158, 158	#9e9e9e
gray63	161, 161, 161	#a1a1a1
gray64	163, 163, 163	#a3a3a3
gray65	166, 166, 166	#a6a6a6
gray66	168, 168, 168	#a8a8a8
gray67	171, 171, 171	#ababab
gray68	173, 173, 173	#adadad
gray69	176, 176, 176	#b0b0b0
gray70	179, 179, 179	#b3b3b3
gray71	181, 181, 181	#b5b5b5
gray72	184, 184, 184	#b8b8b8
gray73	186, 186, 186	#bababa
gray74	189, 189, 189	#bdbdbd
gray75	191, 191, 191	#bfbfbf
gray76	194, 194, 194	#c2c2c2
gray77	196, 196, 196	#c4c4c4
gray78	199, 199, 199	#c7c7c7
gray79	201, 201, 201	#c9c9c9
gray80	204, 204, 204	#cccccc
gray81	207, 207, 207	#cfcfcf
gray82	209, 209, 209	#d1d1d1
gray83	212, 212, 212	#d4d4d4
gray84	214, 214, 214	#d6d6d6
gray85	217, 217, 217	#d9d9d9
gray86	219, 219, 219	#dbdbdb
gray87	222, 222, 222	#dedede
gray88	224, 224, 224	#e0e0e0
gray89	227, 227, 227	#e3e3e3
gray90	229, 229, 229	#e5e5e5
gray91	232, 232, 232	#e8e8e8
gray92	235, 235, 235	#ebebeb
gray93	237, 237, 237	#ededed
gray94	240, 240, 240	#f0f0f0
gray95	242, 242, 242	#f2f2f2
gray96	245, 245, 245	#f5f5f5
gray97	247, 247, 247	#f7f7f7
gray98	250, 250, 250	#fafafa
gray99	252, 252, 252	#fcfcfc
gray100	255, 255, 255	#ffffff
gray	126, 126, 126	#7e7e7e
green	0, 128, 0	#008000
greenyellow	173, 255, 47	#adff2f
grey	128, 128, 128	#808080
honeydew	240, 255, 240	#f0fff0
hotpink	255, 105, 180	#ff69b4
indianred	205, 92, 92	#cd5c5c
indigo	75, 0, 130	#4b0082
ivory	255, 255, 240	#fffff0
khaki	240, 230, 140	#f0e68c
lavender	230, 230, 250	#e6e6fa
lavenderblush	255, 240, 245	#fff0f5
lawngreen	124, 252, 0	#7cfc00
lemonchiffon	255, 250, 205	#fffacd
lightblue	173, 216, 230	#add8e6
lightcoral	240, 128, 128	#f08080
lightcyan	224, 255, 255	#e0ffff
lightgoldenrodyellow	250, 250, 210	#fafad2
lightgray	211, 211, 211	#d3d3d3
lightgreen	144, 238, 144	#90ee90
lightgrey	211, 211, 211	#d3d3d3
lightpink	255, 182, 193	#ffb6c1
lightsalmon	255, 160, 122	#ffa07a
lightseagreen	32, 178, 170	#20b2aa
lightskyblue	135, 206, 250	#87cefa
lightslategray	119, 136, 153	#778899
lightslategrey	119, 136, 153	#778899
lightsteelblue	176, 196, 222	#b0c4de
lightyellow	255, 255, 224	#ffffe0
lime	0, 255, 0	#00ff00
limegreen	50, 205, 50	#32cd32
linen	250, 240, 230	#faf0e6
magenta	255, 0, 255	#ff00ff
maroon	128, 0, 0	#800000
mediumaquamarine	102, 205, 170	#66cdaa
mediumblue	0, 0, 205	#0000cd
mediumorchid	186, 85, 211	#ba55d3
mediumpurple	147, 112, 219	#9370db
mediumseagreen	60, 179, 113	#3cb371
mediumslateblue	123, 104, 238	#7b68ee
mediumspringgreen	0, 250, 154	#00fa9a
mediumturquoise	72, 209, 204	#48d1cc
mediumvioletred	199, 21, 133	#c71585
midnightblue	25, 25, 112	#191970
mintcream	245, 255, 250	#f5fffa
mistyrose	255, 228, 225	#ffe4e1
moccasin	255, 228, 181	#ffe4b5
navajowhite	255, 222, 173	#ffdead
navy	0, 0, 128	#000080
none	0, 0, 0	#000000
oldlace	253, 245, 230	#fdf5e6
olive	128, 128, 0	#808000
olivedrab	107, 142, 35	#6b8e23
orange	255, 165, 0	#ffa500
orangered	255, 69, 0	#ff4500
orchid	218, 112, 214	#da70d6
palegoldenrod	238, 232, 170	#eee8aa
palegreen	152, 251, 152	#98fb98
paleturquoise	175, 238, 238	#afeeee
palevioletred	219, 112, 147	#db7093
papayawhip	255, 239, 213	#ffefd5
peachpuff	255, 218, 185	#ffdab9
peru	205, 133, 63	#cd853f
pink	255, 192, 203	#ffc0cb
plum	221, 160, 221	#dda0dd
powderblue	176, 224, 230	#b0e0e6
purple	128, 0, 128	#800080
red	255, 0, 0	#ff0000
rosybrown	188, 143, 143	#bc8f8f
royalblue	65, 105, 225	#4169e1
saddlebrown	139, 69, 19	#8b4513
salmon	250, 128, 114	#fa8072
sandybrown	244, 164, 96	#f4a460
seagreen	46, 139, 87	#2e8b57
seashell	255, 245, 238	#fff5ee
sienna	160, 82, 45	#a0522d
silver	192, 192, 192	#c0c0c0
skyblue	135, 206, 235	#87ceeb
slateblue	106, 90, 205	#6a5acd
slategray	112, 128, 144	#708090
slategrey	112, 128, 144	#708090
snow	255, 250, 250	#fffafa
springgreen	0, 255, 127	#00ff7f
steelblue	70, 130, 180	#4682b4
tan	210, 180, 140	#d2b48c
teal	0, 128, 128	#008080
thistle	216, 191, 216	#d8bfd8
tomato	255, 99, 71	#ff6347
turquoise	64, 224, 208	#40e0d0
violet	238, 130, 238	#ee82ee
wheat	245, 222, 179	#f5deb3
white	255, 255, 255	#ffffff
whitesmoke	245, 245, 245	#f5f5f5
yellow	255, 255, 0	#ffff00
yellowgreen	154, 205, 50	#9acd32

ColourTools.namedColours.blue // [0, 0, 255]
ColourTools.namedColours.red // [255, 0, 0]
ColourTools.namedColours.green // [0, 255, 0]

ColourTools.namedColours.azure // [240, 255, 255]
ColourTools.namedColours.darkorange // [255, 140, 0]
ColourTools.namedColours.dodgerblue // [30, 144, 255]

[↑ Back to ColourTools ↑]

parse

ColourTools.parse(input: string): ColourValues

Parse a string into a colour object (RGB array) Not extensive. Currently limited to:

3 char hexes
6 char hexes
comma separated RGB values
named colours (from namedColours dictionary)

ColourTools.parse('#FF0000') // [255, 0, 0]
ColourTools.parse('rgb(255, 0, 0)') // [255, 0, 0]
ColourTools.parse('red') // [255, 0, 0]

#	Parameter Name	Required	Type
0	`input`	Yes	`string`

Return Type
`ColourValues`

[↑ Back to ColourTools ↑]

toHex

ColourTools.toHex(colour: ColourValues): string

Convert a colour object (RGB array) to a hex string

ColourTools.toHex([255, 0, 0]) // '#FF0000'

#	Parameter Name	Required	Type
0	`colour`	Yes	`ColourValues`

Return Type
`string`

[↑ Back to ColourTools ↑]

getLuminance

ColourTools.getLuminance(rgb: ColourValues): number

IMPORTANT: This is not the same as the HSL lightness value.

Get the luminance value of a given colour.

Between 0 and 255. Calculated using the formula: (RED × 0.299) + (GREEN × 0.587) + (BLUE × 0.114)

Is the Y (Luma) component of the YUV444 color model.

ColourTools.getLuminance([255, 0, 0]); // 76.245
ColourTools.getLuminance([0, 255, 0]); // 149.685
ColourTools.getLuminance([0, 0, 255]); // 29.07

#	Parameter Name	Required	Type
0	`rgb`	Yes	`ColourValues`

Return Type
`number`

[↑ Back to ColourTools ↑]

toYUV

ColourTools.toYUV(rgb: ColourValues): ColourValues

Convert a colour object (RGB array) to a YUV array.

See https://en.wikipedia.org/wiki/YUV#Y%E2%80%B2UV444_to_RGB888_conversion

ColourTools.toYUV([255, 0, 0]); // [76.245, 112.439, -38.094]

#	Parameter Name	Required	Type
0	`rgb`	Yes	`ColourValues`

Return Type
`ColourValues`

[↑ Back to ColourTools ↑]

toHSL

ColourTools.toHSL(colour: ColourValues, round: boolean): HSLValues

Convert a RGB array to a HSL array.

Adapted from https://www.30secondsofcode.org/js/s/rgb-to-hsl

ColourTools.toHSL([255, 0, 0]); // [0, 100, 50]
ColourTools.toHSL([0, 255, 0]); // [120, 100, 50]

#	Parameter Name	Required	Type	Default
0	`colour`	Yes	`ColourValues`
1	`round`	No	`boolean`	`true`

Return Type
`HSLValues`

[↑ Back to ColourTools ↑]

fromHSL

ColourTools.fromHSL(hsl: HSLValues, round: boolean): ColourValues

Convert a HSL array to a RGB array.

Adapted from https://www.30secondsofcode.org/js/s/hsl-to-rgb

ColourTools.fromHSL([0, 100, 50]); // [255, 0, 0]
ColourTools.fromHSL([120, 100, 50]); // [0, 255, 0]

#	Parameter Name	Required	Type	Default
0	`hsl`	Yes	`HSLValues`
1	`round`	No	`boolean`	`true`

Return Type
`ColourValues`

[↑ Back to ColourTools ↑]

invertColour

ColourTools.invertColour(rgb: ColourValues): ColourValues

Get the opposite colour of a given colour.

ColourTools.invertColour([255, 0, 0]); // [0, 255, 255]
ColourTools.invertColour([0, 255, 0]); // [ 255, 0, 255 ]
ColourTools.invertColour([0, 0, 255]); // [ 255, 255, 0 ]

#	Parameter Name	Required	Type
0	`rgb`	Yes	`ColourValues`

Return Type
`ColourValues`

[↑ Back to ColourTools ↑]

getContrastedColour

ColourTools.getContrastedColour(colour: ColourValues): ColourValues

Get the colour that contrasts the most with a given colour. (White or black)

Returned colour can be used as a text colour on top of the provided colour

ColourTools.getContrastedColour([255, 0, 0]); // [255, 255, 255]
ColourTools.getContrastedColour([255, 255, 0]); // [0, 0, 0]

#	Parameter Name	Required	Type
0	`colour`	Yes	`ColourValues`

Return Type
`ColourValues`

[↑ Back to ColourTools ↑]

getLimitedColour

ColourTools.getLimitedColour(colour: ColourValues, checkFn: (hsl: HSLValues) => boolean, adjustFn: (hsl: HSLValues) => HSLValues): ColourValues

Adjust a colour if a certain condition is met. Used for lightening/darkening colours that are too light/dark

All values in functions are HSL

ColourTools.getLimitedColour([255, 255, 255], ([h,s,l]) => l > 90, ([h,s,l]) => [h, s, 90]); // [ 230, 230, 230 ]
ColourTools.getLimitedColour([128, 128, 128], ([h,s,l]) => l > 90, ([h,s,l]) => [h, s, 90]); // [ 128, 128, 128 ]

#	Parameter Name	Required	Type
0	`colour`	Yes	`ColourValues`
1	`checkFn`	Yes	`(hsl: HSLValues) => boolean`
2	`adjustFn`	Yes	`(hsl: HSLValues) => HSLValues`

Return Type
`ColourValues`

[↑ Back to ColourTools ↑]

TimeTools

A collection of time-related utility functions.

TimeTools
- toReadableDuration

[↑ Back to top ↑]

toReadableDuration

TimeTools.toReadableDuration(duration: ms, longNames: boolean, maxUnits: number): string

Converts a duration in milliseconds to a human readable string.

TimeTools.toReadableDuration(20); // '20ms'
TimeTools.toReadableDuration(seconds(59)); // '59s'
TimeTools.toReadableDuration(seconds(60)); // '1m'
TimeTools.toReadableDuration(hours(23)); // '23h'
TimeTools.toReadableDuration(hours(24)); // '1d'
TimeTools.toReadableDuration(days(10)); // '10d'

TimeTools.toReadableDuration(20, true) // '20 milliseconds'
TimeTools.toReadableDuration(seconds(59), true) // '59 seconds'
TimeTools.toReadableDuration(seconds(60), true) // '1 minute'
TimeTools.toReadableDuration(hours(23), true) // '23 hours'
TimeTools.toReadableDuration(hours(24), true) // '1 day'
TimeTools.toReadableDuration(days(10), true) // '10 days'

const realisticDuration = days(10) + hours(2) + seconds(31) + 512; // 871231512
TimeTools.toReadableDuration(realisticDuration, true, 4) // '10 days, 2 hours, 31 seconds & 512 milliseconds'
TimeTools.toReadableDuration(realisticDuration, true) // '10 days, 2 hours & 31 seconds'
TimeTools.toReadableDuration(realisticDuration, true, 2) // '10 days & 2 hours'

#	Parameter Name	Required	Type	Default
0	`duration`	Yes	`ms`
1	`longNames`	No	`boolean`	`false`
2	`maxUnits`	No	`number`	`3`

Return Type
`string`

[↑ Back to TimeTools ↑]

ErrorTools

Functions for handling errors.

ErrorTools
- tryOr
- retry
- retryOr

[↑ Back to top ↑]

tryOr

tryOr(orValue: T, func: (...args: A) => Promise<T>, ...args: A[]): Promise<T>
ErrorTools.tryOr(orValue: T, func: (...args: A) => Promise<T>, ...args: A[]): Promise<T>

Try to execute a function and return its result if it succeeds, or return the default value if it fails.

const result = tryOr('default', () => getSomething());

#	Parameter Name	Required	Type
0	`orValue`	Yes	`T`
1	`func`	Yes	`(...args: A) => Promise<T>`
2…	`args`	No	`A[]`

Return Type
`Promise<T>`

[↑ Back to ErrorTools ↑]

retry

retry(maxTries: number, delay: ms, suppress: boolean, run: (attemptNumber) => T): Promise<T>
ErrorTools.retry(maxTries: number, delay: ms, suppress: boolean, run: (attemptNumber) => T): Promise<T>

Try to execute a function and return its result if it succeeds, or retry a given number of times until it succeeds.

const result = tryOr(5, seconds(1), true, () => getSomething());

#	Parameter Name	Required	Type	Default
0	`maxTries`	No	`number`	`10`
1	`delay`	No	`ms`	`0`
2	`suppress`	No	`boolean`	`true`
3	`run`	No	`(attemptNumber) => T`	`fn.result(undefined as T)`

Return Type
`Promise<T>`

[↑ Back to ErrorTools ↑]

retryOr

retryOr(orValue: T, maxTries: number, delay: ms, run: () => T | Promise<T>): Promise<T>
ErrorTools.retryOr(orValue: T, maxTries: number, delay: ms, run: () => T | Promise<T>): Promise<T>

Combination of retry and tryOr.

Try to execute a function and return its result if it succeeds, or retry a given number of times until it succeeds. Return the default value if it fails too many times

const result = retryOr('default', 5, seconds(1), () => getSomething());

#	Parameter Name	Required	Type	Default
0	`orValue`	Yes	`T`
1	`maxTries`	No	`number`	`10`
2	`delay`	No	`ms`	`0`
3	`run`	No	`() => T \| Promise<T>`	`fn.result(orValue)`

Return Type
`Promise<T>`

[↑ Back to ErrorTools ↑]

progressBar

A progress bar that can be used in the terminal.

NOTE: This is eventually be moved to swiss-node

progressBar
- Progress Bar
  - getProgressBar
    - getBar
    - update
    - next
    - set
    - reset
    - start
    - finish
    - max
  - Options
    - getFullOptions
- Multi-Bar Manager
  - getMultiBarManager
    - add
    - addNew
    - remove
    - update
    - getBars
  - Options
    - getFullMultiBarManagerOptions
- utils
  - printLn
  - multiPrintFn

[↑ Back to top ↑]

Progress Bar

getProgressBar

getProgressBar(max: number, options: progressBar.ProgressBarOptions): ProgressBar
progressBar.getProgressBar(max: number, options: progressBar.ProgressBarOptions): ProgressBar

Usage:

import chalk from 'chalk'
import {getProgressBar} from 'swiss-ak';

console.log('-'.repeat(20) + ' < 20 Chars');

const progress = getProgressBar(5, {
  prefix: 'ABC',
  maxWidth: 20,
  chalk,
  wrapperFn: chalk.green
});
for (let i = 1; i <= 5; i++) {
  progress.set(i);
}
progress.finish();

Output:

-------------------- < 20 Chars
ABC ▕      ▏ [0 / 5]
ABC ▕█     ▏ [1 / 5]
ABC ▕██    ▏ [2 / 5]
ABC ▕████  ▏ [3 / 5]
ABC ▕█████ ▏ [4 / 5]
ABC ▕██████▏ [5 / 5]

#	Parameter Name	Required	Type	Default
0	`max`	No	`number`
1	`options`	No	`progressBar.ProgressBarOptions`	`{}`

Return Type
`ProgressBar`

[↑ Back to progressBar ↑]

getBar

getProgressBar().getBar(applyWrap: boolean): string

Get the output string of the progress bar

#	Parameter Name	Required	Type	Default	Description
0	`applyWrap`	No	`boolean`	`false`	Whether or not to apply the wrapperFn to the output

Return Type
`string`	output string

[↑ Back to progressBar ↑]

update

getProgressBar().update(): string

Trigger the progress bar to update/rerender

Return Type
`string`	output string

[↑ Back to progressBar ↑]

next

getProgressBar().next(): string

Set the progress bar to the next value

Return Type
`string`	output string

[↑ Back to progressBar ↑]

set

getProgressBar().set(newCurrent: number): string

Set the progress bar to a specific value

#	Parameter Name	Required	Type
0	`newCurrent`	Yes	`number`

Return Type
`string`	output string

[↑ Back to progressBar ↑]

reset

getProgressBar().reset(): string

Set the progress bar to 0

Return Type
`string`	output string

[↑ Back to progressBar ↑]

start

getProgressBar().start(): string

Start displaying the progress bar

Return Type
`string`	output string

[↑ Back to progressBar ↑]

finish

getProgressBar().finish(): string

Stop displaying the progress bar

Return Type
`string`	output string

[↑ Back to progressBar ↑]

max

getProgressBar().max;

Readonly number value of the max value (provided to getProgressBar as first argument)

[↑ Back to progressBar ↑]

Options

progressBar.ProgressBarOptions;

All options are optional.

Property	Default	Description
prefix	`''`	String to show to left of progress bar
prefixWidth	`0`	Min width of prefix - `10` => `Example˽˽˽`
maxPrefixWidth	`Infinity`	Max width of prefix
maxWidth	`process.stdout.columns` or `100`	The maximum width the entire string may extend
wrapperFn	nothing	Function to wrap the printed string (eg `chalk.cyan)`
barWrapFn	nothing	Function to wrap the bar
barProgWrapFn	nothing	Function to wrap the 'complete' segment of the bar
barCurrentWrapFn	nothing	Function to wrap the 'current' segment of the bar
barEmptyWrapFn	nothing	Function to wrap the empty/track part of the line
prefixWrapFn	nothing	Function to wrap the prefix
countWrapFn	nothing	Function to wrap the count
percentWrapFn	nothing	Function to wrap the percent
showCount	`true`	Show numerical values of the count - `[11 / 15]`
showPercent	`false`	Show percentage completed - `( 69%)`
countWidth	`0`	Min width of nums for showCount - `3` => `[˽˽1 / ˽15]`
progChar	`'█'`	Character to use for progress section of bar
emptyChar	`' '`	Character to use for empty (rail) section of bar
startChar	`'▕'`	Character to start the progress bar with
endChar	`'▏'`	Character to end the progress bar with
showCurrent	`false`	Show the 'current' segment of the bar seperately
currentChar	`'▞'`	Character to use the the 'current' segment
print	`true`	Whether or not to print/output/log the progress bar
printFn	progressBar.utils.printLn	Function to use to print the progress bar

[↑ Back to progressBar ↑]

getFullOptions

progressBar.getFullOptions(opts: ProgressBarOptions): ProgressBarOptionsFull

Fill in any missing Progress Bar options with defaults.

Not needed for getProgressBar as it calls this internally.

progressBar.getFullOptions({});
// {
//   prefix: "",
//   prefixWidth: 0,
//   maxPrefixWidth: Infinity,
//   maxWidth: 214,
//   wrapperFn: [Function],
//   barWrapFn: [Function],
//   barProgWrapFn: [Function],
//   barCurrentWrapFn: [Function],
//   barEmptyWrapFn: [Function],
//   prefixWrapFn: [Function],
//   countWrapFn: [Function],
//   percentWrapFn: [Function],
//   showCount: true,
//   showPercent: false,
//   countWidth: 0,
//   progChar: "█",
//   emptyChar: " ",
//   startChar: "▕",
//   endChar: "▏",
//   showCurrent: false,
//   currentChar: "▞",
//   print: true,
//   printFn: [Function],
// }

#	Parameter Name	Required	Type	Default
0	`opts`	No	`ProgressBarOptions`	`{}`

Return Type
`ProgressBarOptionsFull`

[↑ Back to progressBar ↑]

Multi-Bar Manager

getMultiBarManager

getMultiBarManager(options: progressBar.MultiBarManagerOptions): MultiBarManager
progressBar.getMultiBarManager(options: progressBar.MultiBarManagerOptions): MultiBarManager

Returns a manager for multiple progress bars.

const manager = getMultiBarManager({});

const bar1 = manager.addNew(100, { prefix: 'Bar 1' });
const bar2 = manager.addNew(100, { prefix: 'Bar 2' });
const bar3 = manager.addNew(100, { prefix: 'Bar 3' });

bar1.set(25);
bar2.set(50);
bar3.set(75);

// Bar 1▕██████████████                                          ▏ [ 25 / 100]
// Bar 2▕████████████████████████████                            ▏ [ 50 / 100]
// Bar 3▕██████████████████████████████████████████              ▏ [ 75 / 100]

#	Parameter Name	Required	Type	Default
0	`options`	No	`progressBar.MultiBarManagerOptions`	`{}`

Return Type
`MultiBarManager`

[↑ Back to progressBar ↑]

add

getMultiBarManager().add(bar: ProgressBar, removeWhenFinished: boolean): void

Add a given progress bar to the manager

const manager = getMultiBarManager({ overrideOptions: { maxWidth: 75 } });

const bar1 = getProgressBar(100, { prefix: 'Bar 1' });
manager.add(bar1);
const bar2 = getProgressBar(100, { prefix: 'Bar 2' });
manager.add(bar2);
const bar3 = getProgressBar(100, { prefix: 'Bar 3' });
manager.add(bar3);

bar1.set(25);
bar2.set(50);
bar3.set(75);

// Bar 1▕██████████████                                          ▏ [ 25 / 100]
// Bar 2▕████████████████████████████                            ▏ [ 50 / 100]
// Bar 3▕██████████████████████████████████████████              ▏ [ 75 / 100]

#	Parameter Name	Required	Type	Default
0	`bar`	Yes	`ProgressBar`
1	`removeWhenFinished`	No	`boolean`	`opts.removeFinished`

Return Type
`void`

[↑ Back to progressBar ↑]

addNew

getMultiBarManager().addNew(max: number, options: progressBar.ProgressBarOptions): ProgressBar

Create a new progress bar and add it to the manager

const manager = getMultiBarManager({});

const bar1 = manager.addNew(100, { prefix: 'Bar 1' });
const bar2 = manager.addNew(100, { prefix: 'Bar 2' });
const bar3 = manager.addNew(100, { prefix: 'Bar 3' });

bar1.set(25);
bar2.set(50);
bar3.set(75);

// Bar 1▕██████████████                                          ▏ [ 25 / 100]
// Bar 2▕████████████████████████████                            ▏ [ 50 / 100]
// Bar 3▕██████████████████████████████████████████              ▏ [ 75 / 100]

#	Parameter Name	Required	Type	Default
0	`max`	No	`number`
1	`options`	No	`progressBar.ProgressBarOptions`	`{}`

Return Type
`ProgressBar`

[↑ Back to progressBar ↑]

remove

getMultiBarManager().remove(bar: ProgressBar): void

Remove a given progress bar from the manager

const manager = getMultiBarManager({ overrideOptions: { maxWidth: 75 } });

const bar1 = manager.addNew(100, { prefix: 'Bar 1' });
const bar2 = manager.addNew(100, { prefix: 'Bar 2' });
const bar3 = manager.addNew(100, { prefix: 'Bar 3' });

bar1.set(25);
bar2.set(50);
bar3.set(75);

manager.remove(bar2);

// Bar 1▕██████████████                                          ▏ [ 25 / 100]
// Bar 3▕██████████████████████████████████████████              ▏ [ 75 / 100]

#	Parameter Name	Required	Type
0	`bar`	Yes	`ProgressBar`

Return Type
`void`

[↑ Back to progressBar ↑]

update

getMultiBarManager().update(): void

Re-render the progress bars

const manager = getMultiBarManager({ overrideOptions: { maxWidth: 75 } });

const bar1 = manager.addNew(100, { prefix: 'Bar 1' });
const bar2 = manager.addNew(100, { prefix: 'Bar 2' });

bar1.set(25);
bar2.set(50);

manager.update();

// Bar 1▕██████████████                                          ▏ [ 25 / 100]
// Bar 2▕████████████████████████████                            ▏ [ 50 / 100]

Return Type
`void`

[↑ Back to progressBar ↑]

getBars

getMultiBarManager().getBars(): ProgressBar[]

Get an array of all the progress bars currently managed by the manager

const manager = getMultiBarManager({ overrideOptions: { maxWidth: 75 } });

const bar1 = manager.addNew(100, { prefix: 'Bar 1' });
const bar2 = manager.addNew(100, { prefix: 'Bar 2' });
const bar3 = manager.addNew(100, { prefix: 'Bar 3' });

bar1.set(25);
bar2.set(50);
bar3.set(75);

console.log(manager.getBars()); // [ bar1, bar2, bar3 ]

manager.remove(bar2);

console.log(manager.getBars()); // [ bar1, bar3 ]

Return Type
`ProgressBar[]`

[↑ Back to progressBar ↑]

Options

progressBar.MultiBarManagerOptions;

The options for MultiBar Managers

All options are optional.

Property	Default	Description
numSlots	`undefined`	Shorthand for setting both minSlots and maxSlots
minSlots	`0`	The min number of lines to print at a time
maxSlots	`Infinity`	The max number of lines to print at a time
removeFinished	`false`	Remove progress bars from the manager when they finish
alignBottom	`false`	Align the bars to the bottom of the print space
overrideOptions	`{}` (No overrides)	Override the options of the progress bars
variableOptions	`{}` (No variable options)	Override options differently for each bar
print	`true`	Whether or not to print the bars
printFn	progressBar.utils.multiPrintFn	The function to use to print the bars

[↑ Back to progressBar ↑]

getFullMultiBarManagerOptions

progressBar.getFullMultiBarManagerOptions(opts: MultiBarManagerOptions): MultiBarManagerOptionsFull

Fill in any missing MultiBar Manager options with defaults.

Not needed for getMultiBarManager as it calls this internally.

progressBar.getFullMultiBarManagerOptions({});
// {
//   numSlots: null,
//   minSlots: 0,
//   maxSlots: Infinity,
//   removeFinished: false,
//   alignBottom: false,
//   overrideOptions: {},
//   variableOptions: {},
//   print: true,
//   printFn: [Function],
// }

#	Parameter Name	Required	Type
0	`opts`	Yes	`MultiBarManagerOptions`

Return Type
`MultiBarManagerOptionsFull`

[↑ Back to progressBar ↑]

utils

progressBar.utils;

Small helper functions may help when using progress bars

[↑ Back to progressBar ↑]

printLn

progressBar.printLn(...text: any[]): void

Can use instead of console.log

Overwrites the previous line if possible (i.e. node);

Usage

import { printLn } from 'swiss-ak';

printLn('A');
printLn('B'); // Replaces the 'A' line
printLn('C'); // Replaces the 'B' line
printLn(); // Jumps a line
printLn('D'); // Replaces the empty line

Output

C
D

#	Parameter Name	Required	Type
0…	`text`	No	`any[]`

Return Type
`void`

[↑ Back to progressBar ↑]

multiPrintFn

The default printFn for MultiBarManagers

Clears previously printed lines and prints the output in their place

#	Parameter Name	Required	Type
0	`previousDrawnLines`	Yes	`number`
1	`output`	Yes	`string`

Return Type
`void`

[↑ Back to progressBar ↑]

Cachier

A simple caching tool to store and retrieve values by id.

Useful for storing values that are expensive to calculate, or that you want to reuse.

Cachier
- cachier
  - get
  - getOrSave
  - getOrRun
  - save
  - remove
  - clear
  - getAll
  - create
- Cachier

[↑ Back to top ↑]

cachier

cachier;

A generic cachier object for general purpose caching.

Call cachier.create<T>() to create a new isolated cachier object with a specific type.

// Initial save
cachier.save('foo', { name: 'foo' }); // { "name": "foo" }
cachier.get('foo'); // { "name": "foo" }

// Overwrite
cachier.save('foo', { name: 'bar' }); // { "name": "bar" }
cachier.get('foo'); // { "name": "bar" }

// Get if exists, otherwise save
cachier.getOrSave('foo', { name: 'baz' }); // { "name": "bar" }
cachier.get('foo'); // { "name": "bar" }

// Get if exists, otherwise run function to create and save
cachier.getOrRun('foo', () => ({ name: 'qux' })); // { "name": "bar" }
cachier.get('foo'); // { "name": "bar" }

// Remove
cachier.remove('foo');
cachier.get('foo'); // undefined

// Populate
cachier.save('foo', { name: 'foo' }); // { "name": "foo" }
cachier.save('bar', { name: 'bar' }); // { "name": "bar" }
cachier.save('baz', { name: 'baz' }); // { "name": "baz" }

// Get all
cachier.getAll(); // { "foo": { "name": "foo" }, "bar": { "name": "bar" }, "baz": { "name": "baz" } }

// Clear
cachier.clear();
cachier.getAll(); // {}

[↑ Back to Cachier ↑]

get

cachier.get(id: string): T
cachier.create().get(id: string): T

Get a cached item by id.

cachier.save('foo', { name: 'foo' });
cachier.get('foo'); // { "name": "foo" }

#	Parameter Name	Required	Type
0	`id`	Yes	`string`

Return Type
`T`

[↑ Back to Cachier ↑]

getOrSave

cachier.getOrSave(id: string, orValue: T): T
cachier.create().getOrSave(id: string, orValue: T): T

Get a cached item by id, or save a new item if it doesn't exist.

cachier.getOrSave('foo', { name: 'lorem' }); // { "name": "lorem" }
cachier.get('foo'); // { "name": "lorem" }

cachier.getOrSave('foo', { name: 'SOMETHING DIFFERENT' }); // { "name": "lorem" }
cachier.get('foo'); // { "name": "lorem" }

#	Parameter Name	Required	Type
0	`id`	Yes	`string`
1	`orValue`	Yes	`T`

Return Type
`T`

[↑ Back to Cachier ↑]

getOrRun

cachier.getOrRun(id: string, orFunc: (id?: string) => T): T
cachier.create().getOrRun(id: string, orFunc: (id?: string) => T): T

Get a cached item by id, or run a function to create a new item if it doesn't exist.

The created item will be cached and returned.

cachier.getOrRun('foo', () => ({ name: 'lorem' })); // { "name": "lorem" }
cachier.get('foo'); // { "name": "lorem" }

cachier.getOrRun('foo', () => ({ name: 'SOMETHING DIFFERENT' })); // { "name": "lorem" }
cachier.get('foo'); // { "name": "lorem" }

#	Parameter Name	Required	Type
0	`id`	Yes	`string`
1	`orFunc`	Yes	`(id?: string) => T`

Return Type
`T`

[↑ Back to Cachier ↑]

save

cachier.save(id: string, item: T): T
cachier.create().save(id: string, item: T): T

Save an item to the cache.

cachier.save('foo', { name: 'foo' }); // { "name": "foo" }
cachier.get('foo'); // { "name": "foo" }

#	Parameter Name	Required	Type
0	`id`	Yes	`string`
1	`item`	Yes	`T`

Return Type
`T`

[↑ Back to Cachier ↑]

remove

cachier.remove(id: string): void
cachier.create().remove(id: string): void

Remove an item from the cache.

cachier.save('foo', { name: 'foo' });
cachier.get('foo'); // { "name": "foo" }

cachier.remove('foo');
cachier.get('foo'); // undefined

#	Parameter Name	Required	Type
0	`id`	Yes	`string`

Return Type
`void`

[↑ Back to Cachier ↑]

clear

cachier.clear(): void
cachier.create().clear(): void

Clear all items from the cache.

cachier.save('foo', { name: 'foo' });
cachier.getAll(); // { foo: { "name": "foo" } }

cachier.clear();
cachier.getAll(); // {}

Return Type
`void`

[↑ Back to Cachier ↑]

getAll

cachier.getAll(): ObjOfType<T>
cachier.create().getAll(): ObjOfType<T>

Get all items from the cache.

cachier.save('foo', { name: 'foo' });
cachier.save('bar', { name: 'bar' });
cachier.save('baz', { name: 'baz' });

cachier.getAll(); // { "foo": { "name": "foo" }, "bar": { "name": "bar" }, "baz": { "name": "baz" } }

Return Type
`ObjOfType<T>`

[↑ Back to Cachier ↑]

create

cachier.create<T>(): Cachier<U>
cachier.create().create<T>(): Cachier<U>

Create a new isolated cachier object with a specific type.

const numCache = cachier.create<number>();

numCache.save('bar', 123);
cachier.save('foo', { name: 'foo' });

numCache.getAll(); // { "bar": 123 }
cachier.getAll(); // { "foo": { "name": "foo" } }

Return Type
`Cachier<U>`

[↑ Back to Cachier ↑]

Cachier

Cachier<T>;

Type for a cachier object.

[↑ Back to Cachier ↑]

symbols

symbols;

A series of characters that can be used for display symbols

Name		Symbol
TAB	`symbols.TAB`
TICK	`symbols.TICK`	✔
CROSS	`symbols.CROSS`	✖
PLUS	`symbols.PLUS`	+
MINUS	`symbols.MINUS`	-
TIMES	`symbols.TIMES`	×
DIVIDE	`symbols.DIVIDE`	÷
ELLIPSIS	`symbols.ELLIPSIS`	…
BULLET	`symbols.BULLET`	•
BULLET_TRI	`symbols.BULLET_TRI`	‣
BULLET_HYP	`symbols.BULLET_HYP`	⁃
EJECT	`symbols.EJECT`	⏏
TILDE	`symbols.TILDE`	~
HOME	`symbols.HOME`	~
RADIO_EMPTY	`symbols.RADIO_EMPTY`	◯
RADIO_FULL	`symbols.RADIO_FULL`	◉
CURSOR	`symbols.CURSOR`	❯
CHEV_LFT	`symbols.CHEV_LFT`	‹
CHEV_RGT	`symbols.CHEV_RGT`	›
CHAIN	`symbols.CHAIN`	⫘
TRI_UPP	`symbols.TRI_UPP`	▲
TRI_DWN	`symbols.TRI_DWN`	▼
TRI_RGT	`symbols.TRI_RGT`	▶
TRI_LFT	`symbols.TRI_LFT`	◀
ARROW_UPP	`symbols.ARROW_UPP`	↑
ARROW_DWN	`symbols.ARROW_DWN`	↓
ARROW_RGT	`symbols.ARROW_RGT`	→
ARROW_LFT	`symbols.ARROW_LFT`	←
ARROW_UPP_RGT	`symbols.ARROW_UPP_RGT`	↗
ARROW_DWN_RGT	`symbols.ARROW_DWN_RGT`	↘
ARROW_DWN_LFT	`symbols.ARROW_DWN_LFT`	↙
ARROW_UPP_LFT	`symbols.ARROW_UPP_LFT`	↖
ARROW_STILL	`symbols.ARROW_STILL`	•
ARROW_FLIP_H	`symbols.ARROW_FLIP_H`	↔
ARROW_FLIP_V	`symbols.ARROW_FLIP_V`	↕
ARROW_ROTATE_UPP	`symbols.ARROW_ROTATE_UPP`	⤴
ARROW_ROTATE_DWN	`symbols.ARROW_ROTATE_DWN`	⤵
ARROW_ROTATE_LFT	`symbols.ARROW_ROTATE_LFT`	⤶
ARROW_ROTATE_RGT	`symbols.ARROW_ROTATE_RGT`	⤷
ARROW_ROTATE_CLOCK	`symbols.ARROW_ROTATE_CLOCK`	↻
ARROW_ROTATE_ANTI_CLOCK	`symbols.ARROW_ROTATE_ANTI_CLOCK`	↺
FRACTION_1_4	`symbols.FRACTION_1_4`	¼
FRACTION_1_2	`symbols.FRACTION_1_2`	½
FRACTION_3_4	`symbols.FRACTION_3_4`	¾
SUPERSCRIPT	`symbols.SUPERSCRIPT['1']`	¹
	`symbols.SUPERSCRIPT['2']`	²
	`symbols.SUPERSCRIPT['3']`	³
	`symbols.SUPERSCRIPT['4']`	⁴
	`symbols.SUPERSCRIPT['5']`	⁵
	`symbols.SUPERSCRIPT['6']`	⁶
	`symbols.SUPERSCRIPT['7']`	⁷
	`symbols.SUPERSCRIPT['8']`	⁸
	`symbols.SUPERSCRIPT['9']`	⁹
	`symbols.SUPERSCRIPT['0']`	⁰
	`symbols.SUPERSCRIPT['-']`	⁻
	`symbols.SUPERSCRIPT['+']`	⁺
	`symbols.SUPERSCRIPT['=']`	⁼
	`symbols.SUPERSCRIPT['(']`	⁽
	`symbols.SUPERSCRIPT[')']`	⁾
	`symbols.SUPERSCRIPT['i']`	ⁱ
	`symbols.SUPERSCRIPT['n']`	ⁿ
	`symbols.SUPERSCRIPT['o']`	°
	`symbols.SUPERSCRIPT['*']`	°
BLOCK	`symbols.BLOCK.full`	█
	`symbols.BLOCK.upperHalf`	▀
	`symbols.BLOCK.lowerOneEighth`	▁
	`symbols.BLOCK.lowerOneQuarter`	▂
	`symbols.BLOCK.lowerThreeEighths`	▃
	`symbols.BLOCK.lowerHalf`	▄
	`symbols.BLOCK.lowerFiveEighths`	▅
	`symbols.BLOCK.lowerThreeQuarters`	▆
	`symbols.BLOCK.lowerSevenEighths`	▇
	`symbols.BLOCK.leftSevenEighths`	▉
	`symbols.BLOCK.leftThreeQuarters`	▊
	`symbols.BLOCK.leftFiveEighths`	▋
	`symbols.BLOCK.leftHalf`	▌
	`symbols.BLOCK.leftThreeEighths`	▍
	`symbols.BLOCK.leftOneQuarter`	▎
	`symbols.BLOCK.leftOneEighth`	▏
	`symbols.BLOCK.rightHalf`	▐
	`symbols.BLOCK.upperOneEighth`	▔
	`symbols.BLOCK.rightOneEighth`	▕
SHADE	`symbols.SHADE.light`	░
	`symbols.SHADE.medium`	▒
	`symbols.SHADE.dark`	▓
QUADRANT	`symbols.QUADRANT.upperLeft`	▘
	`symbols.QUADRANT.upperRight`	▝
	`symbols.QUADRANT.lowerLeft`	▖
	`symbols.QUADRANT.lowerRight`	▗
	`symbols.QUADRANT.upperLeftLowerLeftLowerRight`	▙
	`symbols.QUADRANT.upperLeftLowerRight`	▚
	`symbols.QUADRANT.upperLeftUpperRightLowerLeft`	▛
	`symbols.QUADRANT.upperLeftUpperRightLowerRight`	▜
	`symbols.QUADRANT.upperRightLowerLeft`	▞
	`symbols.QUADRANT.upperRightLowerLeftLowerRight`	▟

symbols
- superscript

[↑ Back to top ↑]

superscript

superscript(num: number | string): string

Converts a string or number to superscript (where possible)

Known superscript characters: ¹²³⁴⁵⁶⁷⁸⁹⁰⁻⁺⁼⁽⁾ⁱⁿ°

Characters without a superscript equivalent will be replaced with a °

superscript(219) // '²¹⁹'
superscript(1234567890) // '¹²³⁴⁵⁶⁷⁸⁹⁰'

#	Parameter Name	Required	Type
0	`num`	Yes	`number \| string`

Return Type
`string`

[↑ Back to symbols ↑]

queue

A way of managing queues from different parts of the code.

queue
- QueueManager
- queue

[↑ Back to top ↑]

QueueManager

QueueManager;

Allows you to queue up functions to be executed in order.

Importantly, it allows you to add to the queue from another part of the code, without needing to access a promise directly.

const printDocument = async (id: number) => {
  // do something
  await wait(seconds(5));
}

const queue = new QueueManager();

const start = Date.now();

// happening async/concurrently
PromiseTools.each(range(5), async (i) => {
  await wait(seconds(Math.random() * 1));
  console.log(Date.now() - start, ' - trigger:', i, );
  await queue.add('printer', () => printDocument(i))
  console.log(Date.now() - start, ' - printed:', i);
})

// Output:

// 184 ' - trigger:' 0
// 355 ' - trigger:' 2
// 435 ' - trigger:' 4
// 448 ' - trigger:' 1
// 487 ' - trigger:' 3
// 5190 ' - printed:' 0
// 10195 ' - printed:' 2
// 15200 ' - printed:' 4
// 20205 ' - printed:' 1
// 25208 ' - printed:' 3

[↑ Back to queue ↑]

setDefaultPauseTime

queue.setDefaultPauseTime(time: ms): void
new QueueManager().setDefaultPauseTime(time: ms): void

Sets the default pause time for pauses between queue items.

#	Parameter Name	Required	Type
0	`time`	Yes	`ms`

Return Type
`void`

[↑ Back to queue ↑]

setPauseTime

queue.setPauseTime(id: string, time: ms): void
new QueueManager().setPauseTime(id: string, time: ms): void

Sets the pause time for pauses between queue items for the specified queue.

#	Parameter Name	Required	Type
0	`id`	Yes	`string`
1	`time`	Yes	`ms`

Return Type
`void`

[↑ Back to queue ↑]

add

queue.add(id: string, promiseItem: PromiseTools.PromiseItem<T>): Promise<T>
new QueueManager().add(id: string, promiseItem: PromiseTools.PromiseItem<T>): Promise<T>

Adds a function to the queue.

#	Parameter Name	Required	Type
0	`id`	Yes	`string`
1	`promiseItem`	Yes	`PromiseTools.PromiseItem<T>`

Return Type
`Promise<T>`

[↑ Back to queue ↑]

new

queue.new(defaultPauseTime: ms): QueueManager
new QueueManager().new(defaultPauseTime: ms): QueueManager
QueueManager.new(defaultPauseTime: ms): QueueManager

Creates a new QueueManager instance.

#	Parameter Name	Required	Type	Default
0	`defaultPauseTime`	No	`ms`	`0`

Return Type
`QueueManager`

[↑ Back to queue ↑]

queue

queue;

An instance of QueueManager

See QueueManager for more information.

[↑ Back to queue ↑]

timer

A debug tool for measuring the duration of code blocks.

timer
- Timer Instance
  - start
  - end
  - switch
  - getTable
  - log
  - reset
  - getDuration
  - names
  - displayNames
  - startTimes
  - endTimes
- getTimer
- timer

[↑ Back to top ↑]

Timer Instance

start

timer.start(...labels: string[]): void
getTimer().start(...labels: string[]): void

Start a timer

#	Parameter Name	Required	Type
0…	`labels`	Yes	`string[]`

Return Type
`void`

[↑ Back to timer ↑]

end

timer.end(...labels: string[]): void
getTimer().end(...labels: string[]): void

End a given timer

#	Parameter Name	Required	Type
0…	`labels`	Yes	`string[]`

Return Type
`void`

[↑ Back to timer ↑]

switch

timer.switch(endLabel: string | string[], startLabel: string | string[]): void
getTimer().switch(endLabel: string | string[], startLabel: string | string[]): void

Switch the timer The same as calling timer.end(endLabel) and timer.start(startLabel)

#	Parameter Name	Required	Type
0	`endLabel`	Yes	`string \| string[]`
1	`startLabel`	Yes	`string \| string[]`

Return Type
`void`

[↑ Back to timer ↑]

getTable

timer.getTable(prefix: string, customEntries: ((durations: TimerDurations<TName>) => CustomEntryObj)[] | CustomEntryDict<TimerDurations<TName>, TName>): string
getTimer().getTable(prefix: string, customEntries: ((durations: TimerDurations<TName>) => CustomEntryObj)[] | CustomEntryDict<TimerDurations<TName>, TName>): string

Get the timing table as a string

#	Parameter Name	Required	Type
0	`prefix`	No	`string`
1	`customEntries`	No	`((durations: TimerDurations<TName>) => CustomEntryObj)[] \| CustomEntryDict<TimerDurations<TName>, TName>`

Return Type
`string`	the timing table

[↑ Back to timer ↑]

log

timer.log(prefix: string, customEntries: ((durations: TimerDurations<TName>) => CustomEntryObj)[] | CustomEntryDict<TimerDurations<TName>, TName>): number
getTimer().log(prefix: string, customEntries: ((durations: TimerDurations<TName>) => CustomEntryObj)[] | CustomEntryDict<TimerDurations<TName>, TName>): number

Log the timing table

#	Parameter Name	Required	Type
0	`prefix`	No	`string`
1	`customEntries`	No	`((durations: TimerDurations<TName>) => CustomEntryObj)[] \| CustomEntryDict<TimerDurations<TName>, TName>`

Return Type
`number`	the number of lines logged

[↑ Back to timer ↑]

reset

timer.reset(): void
getTimer().reset(): void

Reset the timer

Return Type
`void`

[↑ Back to timer ↑]

getDuration

timer.getDuration(): ms
getTimer().getDuration(): ms

Get the duration of a given timer

Return Type
`ms`

[↑ Back to timer ↑]

names

timer.names;
getTimer().names;

The names of the timers

[↑ Back to timer ↑]

displayNames

timer.displayNames;
getTimer().displayNames;

The display names of the timers

[↑ Back to timer ↑]

startTimes

timer.startTimes;
getTimer().startTimes;

The start times of the timers

[↑ Back to timer ↑]

endTimes

timer.endTimes;
getTimer().endTimes;

The end times of the timers

[↑ Back to timer ↑]

getTimer

getTimer(name: string, verbose: boolean, wrapperFn: any, displayNames: TName): any

Usage:

const timer = getTimer('Example', false, colr.red, {
  TOTAL: 'TOTAL',
  INTRO: 'Action 1',
  ENDING: 'Action 2'
});
timer.start(timer.TOTAL, timer.INTRO);

await wait(seconds(4)); // do something async

timer.switch(timer.INTRO, timer.ENDING); // same as calling end(timer.INTRO) and start(timer.ENDING)

await wait(seconds(6)); // do something async

timer.end(timer.TOTAL, timer.ENDING);
timer.log();

Output:

Example Times:
	Action 1: 4s
	Action 2: 6s
	⎯⎯⎯⎯⎯⎯⎯
	TOTAL:    10s

#	Parameter Name	Required	Type	Default
0	`name`	No	`string`
1	`verbose`	No	`boolean`	`false`
2	`wrapperFn`	No	`any`	`colr.dark.white`
3	`displayNames`	No	`TName`

Return Type
`any`

[↑ Back to timer ↑]

timer

timer;

Usage:

timer.start('TOTAL', 'Intro');

await wait(seconds(4)); // do something async

timer.switch('Intro', 'Ending'); // same as calling timer.end('Intro') and timer.start('Ending')

await wait(seconds(6)); // do something async

timer.end('TOTAL', 'Ending');
timer.log();

Output:

Times:
	Intro:   4s
	Ending:  6s
	⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
	TOTAL:   10s

[↑ Back to timer ↑]

safe

A series of simple functions for ensuring that a value is safe to use.

Used internally for input validation.

safe
- num
- str
- bool
- func
- obj
- objWith
- arr
- prop
- arrOf
  - num
  - str
  - bool
  - func
  - obj
  - objWith
  - arr
  - prop
- ObjWithConfig
  - ObjWithPropConfig

[↑ Back to top ↑]

num

safe.num(input: number, isInt: boolean, min: number, max: number, fallback: number): number

Process a number value, ensuring that it is safe to use.

safe.num(10); // 10
safe.num(10000); // 10000
safe.num(-1); // -1
safe.num(true); // 0
safe.num('123'); // 0
safe.num(NaN); // 0
safe.num(Infinity); // 0
safe.num(null); // 0
safe.num(undefined); // 0

safe.num(10, true, 0, 100, 99); // 10
safe.num(10000, true, 0, 100, 99); // 100
safe.num(-1, true, 0, 100, 99); // 0
safe.num(true, true, 0, 100, 99); // 99
safe.num('123', true, 0, 100, 99); // 99
safe.num(NaN, true, 0, 100, 99); // 99
safe.num(Infinity, true, 0, 100, 99); // 100
safe.num(null, true, 0, 100, 99); // 99
safe.num(undefined, true, 0, 100, 99); // 99

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`number`
1	`isInt`	No	`boolean`	`false`
2	`min`	No	`number`
3	`max`	No	`number`
4	`fallback`	No	`number`	`0`

Return Type
`number`

[↑ Back to safe ↑]

str

safe.str(input: string, allowBasicStringify: boolean, fallback: string): string

Process a string value, ensuring that it is safe to use.

safe.str('foo'); // 'foo'
safe.str(''); // ''
safe.str(123); // ''
safe.str(true); // ''
safe.str({foo: 'bar'}); // ''
safe.str([]); // ''
safe.str(null); // ''
safe.str(undefined); // ''

safe.str('foo', true, 'bar'); // 'foo'
safe.str('', true, 'bar'); // ''
safe.str(123, true, 'bar'); // '123'
safe.str(true, true, 'bar'); // 'true'
safe.str({foo: 'bar'}, true, 'bar'); // 'bar'
safe.str([], true, 'bar'); // 'bar'
safe.str(null, true, 'bar'); // 'bar'
safe.str(undefined, true, 'bar'); // 'bar'

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string`
1	`allowBasicStringify`	No	`boolean`	`false`
2	`fallback`	No	`string`	`''`

Return Type
`string`

[↑ Back to safe ↑]

bool

safe.bool(input: boolean, fallback: boolean): boolean

Process a boolean value, ensuring that it is safe to use.

safe.bool(true); // true
safe.bool(false); // false
safe.bool(1); // true
safe.bool(0); // false
safe.bool(123); // false
safe.bool('true'); // true
safe.bool('false'); // false
safe.bool('foobar'); // false
safe.bool({foo: 'bar'}); // false
safe.bool([]); // false
safe.bool(null); // false
safe.bool(undefined); // false

safe.bool(true, true); // true
safe.bool(false, true); // false
safe.bool(1, true); // true
safe.bool(0, true); // false
safe.bool(123, true); // true
safe.bool('true', true); // true
safe.bool('false', true); // false
safe.bool('foobar', true); // true
safe.bool({foo: 'bar'}, true); // true
safe.bool([], true); // true
safe.bool(null, true); // true
safe.bool(undefined, true); // true

|  #  | Parameter Name | Required | Type      | Default |
|:---:|:---------------|:---------|:----------|:--------|
| *0* | `input`        | **Yes**  | `boolean` |         |
| *1* | `fallback`     | *No*     | `boolean` | `false` |

| Return Type |
|-------------|
| `boolean`   |

<p style="text-align: right" align="right"><a href="#safe"> [↑ Back to <b>safe</b> ↑] </a></p>

### <span id="safe_func">func</span>

```typescript
safe.func<T>(input: T, fallback: T): T

Process a function value, ensuring that it is safe to use.

safe.func((p: number) => 123); // (p: number) => 123
safe.func(true); // (() => {})
safe.func(false); // (() => {})
safe.func(123); // (() => {})
safe.func('foobar'); // (() => {})
safe.func({foo: 'bar'}); // (() => {})
safe.func([1, 2, 3]); // (() => {})
safe.func(null); // (() => {})
safe.func(undefined); // (() => {})

safe.func((p: number) => 123, (q: number) => 456); // (p: number) => 123
safe.func(true, (q: number) => 456); // (q: number) => 456
safe.func(false, (q: number) => 456); // (q: number) => 456
safe.func(123, (q: number) => 456); // (q: number) => 456
safe.func('foobar', (q: number) => 456); // (q: number) => 456
safe.func({foo: 'bar'}, (q: number) => 456); // (q: number) => 456
safe.func([1, 2, 3], (q: number) => 456); // (q: number) => 456
safe.func(null, (q: number) => 456); // (q: number) => 456
safe.func(undefined, (q: number) => 456); // (q: number) => 456

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T`
1	`fallback`	No	`T`	`(() => {}) as unknown as T`

Return Type
`T`

[↑ Back to safe ↑]

obj

safe.obj<T>(input: T, allowArrays: boolean, fallback: T): T

Process an object value, ensuring that it is safe to use.

safe.obj({foo: 'bar'}); // {foo: 'bar'}
safe.obj([1, 2, 3]); // [1, 2, 3]
safe.obj(true); // {}
safe.obj(false); // {}
safe.obj(123); // {}
safe.obj('foobar'); // {}
safe.obj(null); // {}
safe.obj(undefined); // {}

safe.obj({foo: 'bar'}, true, {baz: 123}); // {foo: 'bar'}
safe.obj([1, 2, 3], true, {baz: 123}); // [1, 2, 3]
safe.obj(true, true, {baz: 123}); // {baz: 123}
safe.obj(false, true, {baz: 123}); // {baz: 123}
safe.obj(123, true, {baz: 123}); // {baz: 123}
safe.obj('foobar', true, {baz: 123}); // {baz: 123}
safe.obj(null, true, {baz: 123}); // {baz: 123}
safe.obj(undefined, true, {baz: 123}); // {baz: 123}

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T`
1	`allowArrays`	No	`boolean`	`false`
2	`fallback`	No	`T`	`{} as T`

Return Type
`T`

[↑ Back to safe ↑]

objWith

safe.objWith<T>(input: T, objConfig: ObjWithConfig<T>, allowComposition: boolean): T

Process an object value, ensuring that it is safe to use, and has the neccesary properties.

You must provide a config object that defines the properties that are required, and how to process them. Each required property must have a fallback value, and can have an optional checkFn and safeFn.

fallback - the value to use if the property is missing or invalid
checkFn - a function that returns true if the property is missing or invalid (defaults to (v) => v === undefined)
safeFn - a function that returns the safe value to use (defaults to (v, f) => f)

const config1: ObjWithConfig<{ foo: string }> = {
  foo: {
    fallback: 'a',
    safeFn: (v, f) => safe.str(v, false, f),
  },
};
safe.objWith({foo: 'bar'}, config1); // { foo: 'bar' }
safe.objWith([1, 2, 3], config1); // { '0': 1, '1': 2, '2': 3, foo: 'a' }
safe.objWith(true, config1); // { foo: 'a' }
safe.objWith(false, config1); // { foo: 'a' }
safe.objWith(123, config1); // { foo: 'a' }
safe.objWith('foobar', config1); // { foo: 'a' }
safe.objWith(null, config1); // { foo: 'a' }
safe.objWith(undefined, config1); // { foo: 'a' }

const config2: ObjWithConfig<{ foo: string; bar: number }> = {
  ...config1,
  bar: {
    fallback: 78,
    safeFn: (v, f) => safe.num(v, true, 0, 100, f),
  },
};
safe.objWith({foo: 'bar', bar: 45}, config2); // { foo: 'bar', bar: 45 }
safe.objWith([1, 2, 3], config2); // { '0': 1, '1': 2, '2': 3, foo: 'a', bar: 78 }
safe.objWith(true, config2); // { foo: 'a', bar: 78 }
safe.objWith(false, config2); // { foo: 'a', bar: 78 }
safe.objWith(123, config2); // { foo: 'a', bar: 78 }
safe.objWith('foobar', config2); // { foo: 'a', bar: 78 }
safe.objWith(null, config2); // { foo: 'a', bar: 78 }
safe.objWith(undefined, config2); // { foo: 'a', bar: 78 }

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T`
1	`objConfig`	Yes	`ObjWithConfig<T>`
2	`allowComposition`	No	`boolean`	`true`

Return Type
`T`

[↑ Back to safe ↑]

arr

safe.arr<T>(input: T[], fallback: T[], minLength: number, maxLength: number): T[]

Process an array value, ensuring that it is safe to use.

safe.arr([1, 2, 3]); // [ 1, 2, 3 ]
safe.arr(true); // []
safe.arr(false); // []
safe.arr(123); // []
safe.arr('foobar'); // []
safe.arr({foo: 'bar'}); // []
safe.arr(null); // []
safe.arr(undefined); // []

safe.arr([1, 2, 3], [4, 5, 6]); // [ 1, 2, 3 ]
safe.arr(true, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arr(false, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arr(123, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arr('foobar', [4, 5, 6]); // [ 4, 5, 6 ]
safe.arr({foo: 'bar'}, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arr(null, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arr(undefined, [4, 5, 6]); // [ 4, 5, 6 ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T[]`
1	`fallback`	No	`T[]`	`[]`
2	`minLength`	No	`number`	`0`
3	`maxLength`	No	`number`	`Infinity`

Return Type
`T[]`

[↑ Back to safe ↑]

prop

safe.prop(input: string | number, fallback: string | number): string | number

Process a value (string or number) that is expected to be used as a property name, ensuring that it is safe to use.

Equivalent to typeof value === 'number' ? safe.num(value) : safe.str(value, true, '')

safe.prop('foo'); // 'foo'
safe.prop(''); // ''
safe.prop(123); // 123
safe.prop(true); // 'true'
safe.prop({foo: 'bar'}); // ''
safe.prop([]); // ''
safe.prop(null); // ''
safe.prop(undefined); // ''

safe.prop('foo', 'bar'); // 'foo'
safe.prop('', 'bar'); // ''
safe.prop(123, 'bar'); // 123
safe.prop(true, 'bar'); // 'true'
safe.prop({foo: 'bar'}, 'bar'); // 'bar'
safe.prop([], 'bar'); // 'bar'
safe.prop(null, 'bar'); // 'bar'
safe.prop(undefined, 'bar'); // 'bar'

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string \| number`
1	`fallback`	No	`string \| number`	`''`

Return Type
`string \| number`

[↑ Back to safe ↑]

arrOf

A series of functions for processing arrays of values.

[↑ Back to safe ↑]

num

safe.arrOf.num(input: number[], isInt: boolean, min: number, max: number, fallback: number, fallbackArr: number[], arrMinLength: number, arrMaxLength: number): number[]

Process an array of numbers, ensuring that they are safe to use.

safe.arrOf.num([1, 2, 3]); // [ 1, 2, 3 ]
safe.arrOf.num(['foo', 1, true, null, undefined, [], {}]); // [ 0, 1, 0, 0, 0, 0, 0 ]
safe.arrOf.num(true); // []
safe.arrOf.num(false); // []
safe.arrOf.num(123); // []
safe.arrOf.num('foobar'); // []
safe.arrOf.num({foo: 'bar'}); // []
safe.arrOf.num(null); // []
safe.arrOf.num(undefined); // []

safe.arrOf.num([1, 2, 3], true, 0, 100, 99, [4, 5, 6]); // [ 1, 2, 3 ]
safe.arrOf.num(['foo', 1, true, null, undefined, [], {}], true, 0, 100, 99, [4, 5, 6]); // [ 99, 1, 99, 99, 99, 99, 99 ]
safe.arrOf.num(true, true, 0, 100, 99, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arrOf.num(false, true, 0, 100, 99, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arrOf.num(123, true, 0, 100, 99, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arrOf.num('foobar', true, 0, 100, 99, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arrOf.num({foo: 'bar'}, true, 0, 100, 99, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arrOf.num(null, true, 0, 100, 99, [4, 5, 6]); // [ 4, 5, 6 ]
safe.arrOf.num(undefined, true, 0, 100, 99, [4, 5, 6]); // [ 4, 5, 6 ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`number[]`
1	`isInt`	No	`boolean`	`false`
2	`min`	No	`number`
3	`max`	No	`number`
4	`fallback`	No	`number`
5	`fallbackArr`	No	`number[]`	`[]`
6	`arrMinLength`	No	`number`	`0`
7	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`number[]`

[↑ Back to safe ↑]

str

safe.arrOf.str(input: string[], allowStringify: boolean, fallback: string, fallbackArr: string[], arrMinLength: number, arrMaxLength: number): string[]

Process an array of strings, ensuring that they are safe to use.

safe.arrOf.str(['foo', 'bar', 'baz']); // [ 'foo', 'bar', 'baz' ]
safe.arrOf.str(['foo', 1, true, null, undefined, [], {}]); // [ 'foo', '', '', '', '', '', '' ]
safe.arrOf.str(true); // []
safe.arrOf.str(false); // []
safe.arrOf.str(123); // []
safe.arrOf.str('foobar'); // []
safe.arrOf.str({foo: 'bar'}); // []
safe.arrOf.str(null); // []
safe.arrOf.str(undefined); // []

safe.arrOf.str(['foo', 'bar', 'baz'], true, 'LOREM', ['IPSUM']); // [ 'foo', 'bar', 'baz' ]
safe.arrOf.str(['foo', 1, true, null, undefined, [], {}], true, 'LOREM', ['IPSUM']); // [ 'foo', '1', 'true', 'LOREM', 'LOREM', 'LOREM', 'LOREM' ]
safe.arrOf.str(true, true, 'LOREM', ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.str(false, true, 'LOREM', ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.str(123, true, 'LOREM', ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.str('foobar', true, 'LOREM', ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.str({foo: 'bar'}, true, 'LOREM', ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.str(null, true, 'LOREM', ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.str(undefined, true, 'LOREM', ['IPSUM']); // [ 'IPSUM' ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`string[]`
1	`allowStringify`	No	`boolean`	`false`
2	`fallback`	No	`string`
3	`fallbackArr`	No	`string[]`	`[]`
4	`arrMinLength`	No	`number`	`0`
5	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`string[]`

[↑ Back to safe ↑]

bool

safe.arrOf.bool(input: boolean[], fallback: boolean, fallbackArr: boolean[], arrMinLength: number, arrMaxLength: number): boolean[]

Process an array of booleans, ensuring that they are safe to use.

safe.arrOf.bool([false, true, false]); // [ false, true, false ]
safe.arrOf.bool(['foo', 123, true, null, undefined, [], {}]); // [ false, false, true, false, false, false, false ]
safe.arrOf.bool(true); // []
safe.arrOf.bool(false); // []
safe.arrOf.bool(123); // []
safe.arrOf.bool('foobar'); // []
safe.arrOf.bool({foo: 'bar'}); // []
safe.arrOf.bool(null); // []
safe.arrOf.bool(undefined); // []

safe.arrOf.bool([false, true, false], true, [true, true]); // [ false, true, false ]
safe.arrOf.bool(['foo', 123, true, null, undefined, [], {}], true, [true, true]); // [ true, true, true, true, true, true, true ]
safe.arrOf.bool(true, true, [true, true]); // [ true, true ]
safe.arrOf.bool(false, true, [true, true]); // [ true, true ]
safe.arrOf.bool(123, true, [true, true]); // [ true, true ]
safe.arrOf.bool('foobar', true, [true, true]); // [ true, true ]
safe.arrOf.bool({foo: 'bar'}, true, [true, true]); // [ true, true ]
safe.arrOf.bool(null, true, [true, true]); // [ true, true ]
safe.arrOf.bool(undefined, true, [true, true]); // [ true, true ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`boolean[]`
1	`fallback`	No	`boolean`
2	`fallbackArr`	No	`boolean[]`	`[]`
3	`arrMinLength`	No	`number`	`0`
4	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`boolean[]`

[↑ Back to safe ↑]

func

safe.arrOf.func<T>(input: T[], fallback: T, fallbackArr: T[], arrMinLength: number, arrMaxLength: number): T[]

Process an array of functions, ensuring that they are safe to use.

safe.arrOf.func([(p) => 1]); // [(p) => 1]
safe.arrOf.func(['foo', 1, true, null, undefined, [], {}]); // [() => {}, () => {}, () => {}, () => {}, () => {}, () => {}, () => {}]
safe.arrOf.func(true); // []
safe.arrOf.func(false); // []
safe.arrOf.func(123); // []
safe.arrOf.func('foobar'); // []
safe.arrOf.func({foo: 'bar'}); // []
safe.arrOf.func(null); // []
safe.arrOf.func(undefined); // []

safe.arrOf.func([(p) => 1], (q) => 2, [(r) => 3]); // [(p) => 1]
safe.arrOf.func(['foo', 1, true, null, undefined, [], {}], (q) => 2, [(r) => 3]); // [(q) => 2, (q) => 2, (q) => 2, (q) => 2, (q) => 2, (q) => 2, (q) => 2]
safe.arrOf.func(true, (q) => 2, [(r) => 3]); //  [(r) => 3]
safe.arrOf.func(false, (q) => 2, [(r) => 3]); //  [(r) => 3]
safe.arrOf.func(123, (q) => 2, [(r) => 3]); //  [(r) => 3]
safe.arrOf.func('foobar', (q) => 2, [(r) => 3]); //  [(r) => 3]
safe.arrOf.func({foo: 'bar'}, (q) => 2, [(r) => 3]); //  [(r) => 3]
safe.arrOf.func(null, (q) => 2, [(r) => 3]); //  [(r) => 3]
safe.arrOf.func(undefined, (q) => 2, [(r) => 3]); //  [(r) => 3]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T[]`
1	`fallback`	No	`T`
2	`fallbackArr`	No	`T[]`	`[]`
3	`arrMinLength`	No	`number`	`0`
4	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`T[]`

[↑ Back to safe ↑]

obj

safe.arrOf.obj<T>(input: T[], allowArrays: boolean, fallback: T, fallbackArr: T[], arrMinLength: number, arrMaxLength: number): T[]

Process an array of objects, ensuring that they are safe to use.

safe.arrOf.obj([{foo: 1}, {bar: 2}]); // [ { foo: 1 }, { bar: 2 } ]
safe.arrOf.obj(['foo', 1, true, null, undefined, [], {}]); // [ {}, {}, {}, {}, {}, [], {} ]
safe.arrOf.obj(true); // []
safe.arrOf.obj(false); // []
safe.arrOf.obj(123); // []
safe.arrOf.obj('foobar'); // []
safe.arrOf.obj({foo: 'bar'}); // []
safe.arrOf.obj(null); // []
safe.arrOf.obj(undefined); // []

safe.arrOf.obj([{foo: 1}, {bar: 2}], true, {l: 3}, [{i: 4}]); // [ { foo: 1 }, { bar: 2 } ]
safe.arrOf.obj(['foo', 1, true, null, undefined, [], {}], true, {l: 3}, [{i: 4}]); // [ { l: 3 }, { l: 3 }, { l: 3 }, { l: 3 }, { l: 3 }, [], { } ]
safe.arrOf.obj(true, true, {l: 3}, [{i: 4}]); // [ { i: 4 } ]
safe.arrOf.obj(false, true, {l: 3}, [{i: 4}]); // [ { i: 4 } ]
safe.arrOf.obj(123, true, {l: 3}, [{i: 4}]); // [ { i: 4 } ]
safe.arrOf.obj('foobar', true, {l: 3}, [{i: 4}]); // [ { i: 4 } ]
safe.arrOf.obj({foo: 'bar'}, true, {l: 3}, [{i: 4}]); // [ { i: 4 } ]
safe.arrOf.obj(null, true, {l: 3}, [{i: 4}]); // [ { i: 4 } ]
safe.arrOf.obj(undefined, true, {l: 3}, [{i: 4}]); // [ { i: 4 } ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T[]`
1	`allowArrays`	No	`boolean`	`false`
2	`fallback`	No	`T`
3	`fallbackArr`	No	`T[]`	`[]`
4	`arrMinLength`	No	`number`	`0`
5	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`T[]`

[↑ Back to safe ↑]

objWith

safe.arrOf.objWith<T>(input: T[], objConfig: ObjWithConfig<T>, allowComposition: boolean, fallbackArr: T[], arrMinLength: number, arrMaxLength: number): T[]

Process an array of objects, ensuring that they are safe to use, and have the neccesary properties.

const config1: ObjWithConfig<{ foo: string }> = {
  foo: {
    fallback: 'a',
    safeFn: (v, f) => safe.str(v, false, f)
  }
};
safe.arrOf.objWith([{ foo: 1 }, { bar: 2 }], config1); // [ { foo: 'a' }, { bar: 2, foo: 'a' } ]
safe.arrOf.objWith(['foo', 1, true, null, undefined, [], {}], config1); // [{ foo: 'a' },{ foo: 'a' },{ foo: 'a' },{ foo: 'a' },{ foo: 'a' },{ foo: 'a' },{ foo: 'a' }]
safe.arrOf.objWith(true, config1); // []
safe.arrOf.objWith(false, config1); // []
safe.arrOf.objWith(123, config1); // []
safe.arrOf.objWith('foobar', config1); // []
safe.arrOf.objWith({ foo: 'bar' }, config1); // []
safe.arrOf.objWith(null, config1); // []

const config2: ObjWithConfig<{ foo: string, bar: number }> = {
  ...config1,
  bar: {
    fallback: 78,
    safeFn: (v, f) => safe.num(v, true, 0, 100, f)
  }
};
safe.arrOf.objWith([{ foo: 1 }, { bar: 2 }], config2); // [ { foo: 'a', bar: 78 }, { bar: 2, foo: 'a' } ]
safe.arrOf.objWith(['foo', 1, true, null, undefined, [], {}], config2); // [{ foo: 'a', bar: 78 },{ foo: 'a', bar: 78 },{ foo: 'a', bar: 78 },{ foo: 'a', bar: 78 },{ foo: 'a', bar: 78 },{ foo: 'a', bar: 78 },{ foo: 'a', bar: 78 }]
safe.arrOf.objWith(true, config2); // []
safe.arrOf.objWith(false, config2); // []
safe.arrOf.objWith(123, config2); // []
safe.arrOf.objWith('foobar', config2); // []
safe.arrOf.objWith({ foo: 'bar' }, config2); // []
safe.arrOf.objWith(null, config2); // []

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T[]`
1	`objConfig`	Yes	`ObjWithConfig<T>`
2	`allowComposition`	No	`boolean`	`true`
3	`fallbackArr`	No	`T[]`	`[]`
4	`arrMinLength`	No	`number`	`0`
5	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`T[]`

[↑ Back to safe ↑]

arr

safe.arrOf.arr<T>(input: T[][], fallback: T[], fallbackArr: T[][], arrMinLength: number, arrMaxLength: number): T[][]

Process an array of arrays, ensuring that they are safe to use.

safe.arrOf.arr([['foo'], ['bar']]); // [ [ 'foo' ], [ 'bar' ] ]
safe.arrOf.arr(['foo', 1, true, null, undefined, [], {}]); // [ [], [], [], [], [], [], [] ]
safe.arrOf.arr(true); // []
safe.arrOf.arr(false); // []
safe.arrOf.arr(123); // []
safe.arrOf.arr('foobar'); // []
safe.arrOf.arr({foo: 'bar'}); // []
safe.arrOf.arr(null); // []
safe.arrOf.arr(undefined); // []

safe.arrOf.arr([['foo'], ['bar']], ['baz'], [['IPSUM']]); // [ [ 'foo' ], [ 'bar' ] ]
safe.arrOf.arr(['foo', 1, true, null, undefined, [], {}], ['baz'], [['IPSUM']]); // [ [ 'baz' ], [ 'baz' ], [ 'baz' ], [ 'baz' ], [ 'baz' ], [], [ 'baz' ] ]
safe.arrOf.arr(true, ['baz'], [['IPSUM']]); // [ [ 'IPSUM' ] ]
safe.arrOf.arr(false, ['baz'], [['IPSUM']]); // [ [ 'IPSUM' ] ]
safe.arrOf.arr(123, ['baz'], [['IPSUM']]); // [ [ 'IPSUM' ] ]
safe.arrOf.arr('foobar', ['baz'], [['IPSUM']]); // [ [ 'IPSUM' ] ]
safe.arrOf.arr({foo: 'bar'}, ['baz'], [['IPSUM']]); // [ [ 'IPSUM' ] ]
safe.arrOf.arr(null, ['baz'], [['IPSUM']]); // [ [ 'IPSUM' ] ]
safe.arrOf.arr(undefined, ['baz'], [['IPSUM']]); // [ [ 'IPSUM' ] ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`T[][]`
1	`fallback`	No	`T[]`
2	`fallbackArr`	No	`T[][]`	`[]`
3	`arrMinLength`	No	`number`	`0`
4	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`T[][]`

[↑ Back to safe ↑]

prop

safe.arrOf.prop(input: (string | number)[], fallback: string | number, fallbackArr: (string | number)[], arrMinLength: number, arrMaxLength: number): (string | number)[]

Process an array of values that can be used as properties (string or number), ensuring that they are safe to use.

safe.arrOf.prop([['foo'], ['bar']]); // [ '', '' ]
safe.arrOf.prop(['foo', 1, true, null, undefined, [], {}]); // [ 'foo', 1, 'true', '', '', '', '' ]
safe.arrOf.prop(true); // []
safe.arrOf.prop(false); // []
safe.arrOf.prop(123); // []
safe.arrOf.prop('foobar'); // []
safe.arrOf.prop({foo: 'bar'}); // []
safe.arrOf.prop(null); // []
safe.arrOf.prop(undefined); // []

safe.arrOf.prop([['foo'], ['bar']], ['baz'], ['IPSUM']); // [ [ 'baz' ], [ 'baz' ] ]
safe.arrOf.prop(['foo', 1, true, null, undefined, [], {}], ['baz'], ['IPSUM']); // [ 'foo', 1, 'true', [ 'baz' ], [ 'baz' ], [ 'baz' ],[ 'baz' ] ]
safe.arrOf.prop(true, ['baz'], ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.prop(false, ['baz'], ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.prop(123, ['baz'], ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.prop('foobar', ['baz'], ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.prop({foo: 'bar'}, ['baz'], ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.prop(null, ['baz'], ['IPSUM']); // [ 'IPSUM' ]
safe.arrOf.prop(undefined, ['baz'], ['IPSUM']); // [ 'IPSUM' ]

#	Parameter Name	Required	Type	Default
0	`input`	Yes	`(string \| number)[]`
1	`fallback`	No	`string \| number`
2	`fallbackArr`	No	`(string \| number)[]`	`[]`
3	`arrMinLength`	No	`number`	`0`
4	`arrMaxLength`	No	`number`	`Infinity`

Return Type
`(string \| number)[]`

[↑ Back to safe ↑]

ObjWithConfig

safe.ObjWithConfig;

A type for defining the configuration of an object when using safe.objWith.

[↑ Back to safe ↑]

ObjWithPropConfig

safe.ObjWithPropConfig;

A type for defining what is required for a property of an object when using safe.objWith.

[↑ Back to safe ↑]

Types

Some commonly used typescript types

Types
- Prettify
- Partial
- DeepPartial
- KeysOnly
- Numbered
- OfType<O, T>
- ObjOfType
- RemapOf<O, T>

[↑ Back to top ↑]

Prettify

Prettify<T>;

Makes joined types more readable

type A = {name: string};
type B = {age: number};

type NormalAB = A & B; // A & B
type PrettyAB = Prettify<A & B>; // {name: string; age: number;}

[↑ Back to Types ↑]

Partial

Partial<T>;

Makes all properties in T optional.

interface ITest {
  a: string,
  b: boolean
};
type PartialTest = Partial<ITest>; // { a?: string, b?: boolean }

[↑ Back to Types ↑]

DeepPartial

DeepPartial<T>;

Like Partial, but makes all nested properties optional

interface ITest {
  a: string;
  b: {
    foo: number;
  };
  c: boolean;
};
type DeepPartialTest = DeepPartial<ITest>; // { a?: string, b?: { foo?: number }, c?: boolean }

[↑ Back to Types ↑]

KeysOnly

KeysOnly<T>;

Makes all the values equal to the keys of T

interface ITest {
  a: string,
  b: boolean
};
type KeysOnlyTest = KeysOnly<ITest>; // { a: 'a', b: 'b' }

[↑ Back to Types ↑]

Numbered

Numbered<T>;

Makes all the values numbers

interface ITest {
  a: string,
  b: boolean
};
type NumberedTest = Numbered<ITest>; // { a: number, b: number }

[↑ Back to Types ↑]

OfType<O, T>

OfType<O, T>;

Makes all the properties of object O have type T

Note: This is the same as RemapOf<O, T>

interface IExample {
  a: string;
  b: boolean;
}
OfType<IExample, number>; // { a: number; b: number; }

[↑ Back to Types ↑]

ObjOfType

ObjOfType<T>;

An object with any properties of type T

type Example = [number, number];
ObjOfType<Example>; // { [key: string]: Example; }

[↑ Back to Types ↑]

RemapOf<O, T>

RemapOf<O, T>;

Remap a given interface (O) with all properties of type T

Note: This is the same as OfType<O, T>

interface IExample {
  a: string;
  b: boolean;
}
RemapOf<IExample, number>; // { a: number; b: number; }

[↑ Back to Types ↑]

Notes

Over 9000 unit tests

[↑ Back to top ↑]

License

jackcannon/swiss-ak

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages