General-purpose toolkit.

Installation

$ npm install @simplehealth/toolkit

API

nn()

function nn<T>(value: T, msg?: string): $NonMaybeType<T>

NN means "not nullish". Guarantees that a value at runtime will not be null or undefined at runtime.

compact()

function compact<T>(items: $ReadOnlyArray<T>): Array<$NonMaybeType<T>>

Removes null and undefined values from an array, but keeps all other elements, even if they're falsey. This is different from the idiomatic arr.filter(Boolean), which will also drop falsey values.

allEqual()

function allEqual<T: Scalar>(items: $ReadOnlyArray<T>): boolean

Returns whether all the items in the given array have the same value.

keys()

function keys<T>(obj: ReadOnlyLUT<T>): Array<string>

Returns all keys from the given object. Alias for Object.keys(), for consistency with values() and pairs().

values()

function values<T>(obj: ReadOnlyLUT<T>): Array<T>

Return values from the given object. Like Object.values(), but type-safe.

pairs()

function pairs<T>(obj: ReadOnlyLUT<T>): Array<[string, T]>

Return [key, value] pairs from the given object. Like Object.entries(), but type-safe.

mapvAsync()

async function mapvAsync<T, V, O: ReadOnlyLUT<T>>(obj: O, mapper: (value: T) => Promise<V>): Promise<$ObjMap<O, (T) => V>>

Change the values of an object, while keeping the keys the same. Same as mapv, but for promises. Uses Promise.all(). Any rejected promise will be thrown.

export function filterk<T>(obj: ReadOnlyLUT<T>, filterFn: (string) => boolean): LUT<T>

Filter the lookup table by key.

filterkv()

function filterkv<V, K: Keyish>(obj: { +[K]: V }, filterFn: (K, V) => boolean): { [K]: V }

Filter the mapping by value.

filterv()

function filterv<T>(obj: ReadOnlyLUT<T>, filterFn: (T) => boolean): LUT<T>

Filter the lookup table by value.

partition()

function partition<T>(items: $ReadOnlyArray<T>, predicate: (T) => boolean): [Array<T>, Array<T>]

Partition the array into two arrays, one containing all elements matching the predicate, and one with all elements that did not match the predicate.

mapk()

function mapk<V>(obj: { +[string]: V }, mapper: (key: string) => string): { [string]: V }

Change any key value in the object. Will attach the corresponding value to the new key if it changed.

mapkv()

function mapkv<V1, V2, O: ReadOnlyLUT<V1>>(obj: O, mapper: (key: string, value: V1) => [Keyish, V2]): $ObjMap<O, (V1) => V2>

Change any key-value pair in the object. You can change the key, the value, or both. If multiple invocations of the mapper function produce the same "key" value, then it is undefined which one will be in the result LUT.

mapv()

function mapv<T, V, O: ReadOnlyLUT<T>>(obj: O, mapper: (value: T, key: string) => V): $ObjMap<O, (T) => V>

Change the values of an object, while keeping the keys the same.

indexBy()

function indexBy<T, K: Keyish>(items: $ReadOnlyArray<T>, keyFn: (T) => K): LUT<T, K>

Build a lookup table from the items in the given array. If multiple items get mapped to the same key, it's undefined which one "wins".

indexByKV()

function indexByKV<T, V, K: Keyish>(items: $ReadOnlyArray<T>, keyValFn: (item: T) => [K, V]): LUT<V, K>

Like indexBy(), but allows mutating the value while building up the lookup table.

groupBy()

function groupBy<T, K: Keyish>(items: $ReadOnlyArray<T>, keyFn: (item: T) => K): LUT<Array<T>, K>

Groups the items in the given array. The callback function's return value defines the group key.

groupByKV()

function groupByKV<T, V, K: Keyish>(items: $ReadOnlyArray<T>, keyValFn: (item: T) => [K, V]): LUT<Array<V>, K>

Groups the items in the given array and transform their values in one go. The callback function's return value describes both the group key and the value to store.

filterAsync()

async function filterAsync<T>(arr: $ReadOnlyArray<T>, predicate: (T) => Promise<boolean>): Promise<Array<T>>

Filter an array using an async predicate.

dropAsync()

async function dropAsync<T>(arr: $ReadOnlyArray<T>, predicate: (T) => Promise<boolean>): Promise<Array<T>>

Does the inverse of filterAsync().

keepDupesBy()

function keepDupesBy<T>(arr: $ReadOnlyArray<T>, keyFn: (T) => Keyish): Array<T>

Keeps only elements that have duplicates (as defined by the key function).

minBy()

function minBy<T>(arr: $ReadOnlyArray<T>, keyFn: (T) => Keyish | Date): T | void

maxBy()

function maxBy<T>(arr: $ReadOnlyArray<T>, keyFn: (T) => Keyish | Date): T | void

sum()

function sum(input: $ReadOnlyArray<number>): number

clamp()

function clamp(value: number, minimum: number, maximum: number): number

Returns value, bounded by the minimum and maximum.

flatten()

function flatten<T>(listOfLists: $ReadOnlyArray<$ReadOnlyArray<T>>): Array<T>

flatmap()

function flatmap<T, V>(items: $ReadOnlyArray<T>, mapFn: (T) => $ReadOnlyArray<V>): Array<V>

flatmapAsync()

async function flatmapAsync<T, V>(items: $ReadOnlyArray<T>, mapFn: (T) => Promise<Array<V>>): Promise<Array<V>>

Like flatmap(), but with an async mapper function. Runs all mapper functions in parallel, so be careful to run this on lists with many items.

common()

function common<T>(inputs: $ReadOnlyArray<$ReadOnlyArray<T>>): Array<T>

Return only the elements that are present in all given arrays.

uniq()

function uniq<T: Scalar>(items: $ReadOnlyArray<T>): Array<T>

Reduce function to a set of elements only in the array once. Does a "shallow" comparison so don't be passing in OBJECTS PLEASE.

uniqBy()

function uniqBy<T, K: Scalar>(items: $ReadOnlyArray<T>, keyFn: (T) => K): Array<T>

Filters the given array by dropping duplicate values. If multiple items map get mapped to the same key, only the first occurrence "wins".

consistentPick()

function consistentPick<T: Scalar>(items: $ReadOnlyArray<T>): T

When all values in an array are expected to be equal, returns that value or else throws.

lut()

function lut<K: Keyish, V>(entries: $ReadOnlyArray<[K, V]>): LUT<V>

Turns a "zipped" list of pairs into a LUT, using the first entry as the key, and the second entry as the value. For example:

[
  [123, 'Alice'],
  [345, 'Bob'],
];

Will return:

{
  123: "Alice",
  345: "Bob",
}

head()

function head<T>(items: $ReadOnlyArray<T>): T | void

Returns the first element in the array. This type-safe version will correctly project that the returned item can possibly be undefined. Usually Flow doesn't catch this.

nth()

function nth<T>(items: $ReadOnlyArray<T>, n: number): T | void

Like items[n], but type-safe. This type-safe version will correctly project that the returned item can possibly be undefined.

get()

function get<T, K: Keyish>(lookupTable: ReadOnlyLUT<T, K>, key: K): T | void

Returns the value for the given key in the LUT. This type-safe version will correctly project that the returned item can possibly be undefined. Usually Flow doesn't catch this.

lstrip()

function lstrip(str: string, prefix: string): string

Strips prefix (repeatedly) off str if it exists, otherwise returns str untouched.

rstrip()

function rstrip(str: string, suffix: string): string

Strips suffix (repeatedly) off str if it exists, otherwise returns str untouched.