npm package: @simplehealth/toolkit
Description: $ npm install @simplehealth/toolkit
Author: SimpleHealth team
Latest version: 0.5.1

[![npm](https://img.shields.io/npm/v/@simplehealth/toolkit.svg)](https://www.npmjs.com/package/@simplehealth/toolkit)
[![Build Status](https://github.com/SimpleContacts/toolkit/workflows/test/badge.svg)](https://github.com/SimpleContacts/toolkit/actions)

General-purpose toolkit.

# Installation

    $ npm install @simplehealth/toolkit

# API

### `nn()`

```js
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()`

```js
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()`

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

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

---

### `keys()`

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

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

---

### `values()`

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

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

---

### `pairs()`

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

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

---

### `mapvAsync()`

```js
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`](#mapv),
but for promises. Uses `Promise.all()`. Any rejected promise will be thrown.

---

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

Filter the lookup table by key.

---

### `filterkv()`

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

Filter the mapping by value.

---

### `filterv()`

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

Filter the lookup table by value.

---

### `partition()`

```js
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()`

```js
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()`

```js
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()`

```js
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()`

```js
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()`

```js
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()`

```js
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()`

```js
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()`

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

Filter an array using an async predicate.

---

### `dropAsync()`

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

Does the inverse of [`filterAsync()`](#filterAsync).

---

### `keepDupesBy()`

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

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

---

### `minBy()`

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

---

### `maxBy()`

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

---

### `sum()`

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

---

### `clamp()`

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

Returns `value`, bounded by the minimum and maximum.

---

### `flatten()`

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

---

### `flatmap()`

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

---

### `flatmapAsync()`

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

Like [`flatmap()`](#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()`

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

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

---

### `uniq()`

```js
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()`

```js
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()`

```js
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()`

```js
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:

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

Will return:

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

---

### `head()`

```js
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()`

```js
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()`

```js
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()`

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

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

---

### `rstrip()`

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

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