@execonline-inc/collections

: Utilities for working with collections of data

`collections`

The collections package provides functions to work with lists in various ways.

Functions

`bifurcateWhen`

This function splits an array once the provided function evaluates to true for an element of that array. The element that resulted in the true evaluation is the first element of the second returned array.

import { bifurcateWhen } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = bifurcateWhen((item: number): boolean => item === 3, list);
// [[1, 2], [3, 4, 5]]

`bifurcateBy`

This function splits an array by the evaluation of the provided function. Array elements that evaluate to true are returned as the first bifurcated array, those that evaluate to false are returned as the second bifurcated array.

import { bifurcateBy } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const isEven = (item: number): boolean => !(item % 2);
const result = bifurcateBy(isEven, list);
// [[2, 4], [1, 3, 5]]

`concat`

This curried function simply concatenates two arrays.

import { concat } from '@execonline-inc/collections';

const listA = [1, 2, 3];
const listB = [4, 5, 6];

const result = concat(listA)(listB);
// [1, 2, 3, 4, 5, 6]

`concatAll`

This function takes an array of arrays, and concatenates them all in order.

import { concatAll } from '@execonline-inc/collections';

const lists = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
];

const result: number[] = concatAll(lists);
// [1, 2, 3, 4, 5, 6, 7, 8, 9]

`drop`

drop creates a new array by dropping the specified number of items from the front of the array.

This function has a curried and non-curried form.

import { drop } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = drop(3)(list);
// [ 4, 5 ]

`dropUntil`

This function has a curried and non-curried form. It takes an evaluation function and an array.

The evaluation function is called on elements of the array until it evaluates to true. The element that caused the function to evaluate to true and subsequent elements of the array are returned in a new array.

import { dropUntil } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result: number[] = dropUntil((item: number): boolean => item === 3)(list);
// [3, 4, 5]

`uniqBy`

This curried function takes a transformation function and an array. Each element of the array is passed to the transformation function. Duplicate evaluations of this function exlude the corresponding original element from the returned array.

import { uniqBy } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result: number[] = uniqBy((item: number): string => (item > 3 ? String(item) : ''));
// [1, 4, 5]

`uniq`

This function returns only the unique elements of a given array.

import { uniq } from '@execonline-inc/collections';

const list = [1, 1, 2, 3, 3];
const result: number[] = uniq(list);
// [1, 2, 3]

`find`

find returns the first matching element in an Array.

Matching is determined by the function passed as the first argument. If it returns true, then a match has been identified.

If a match is found, the item is return wrapped in a Just. Otherwise, a Nothing is returned.

This function has a curried and non-curried form.

import { find } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [1, 2, 3];
const result: Maybe<number> = find((item: number): boolean => item === 2)(list);
// Just<2>

`findIndex`

findIndex takes an evaluation function and an array.

The evaluation function is called on elements of the array until it evaluates to true, at which point that element's index is returned as a Just. If no element is found, a Nothing iss returned.

This function has a curried and non-curried form.

import { findIndex } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [1, 2, 3];
const result: Maybe<number> = findIndex((item: number): boolean => item === 2)(list);
// Just<1>

`findR`

This curried function operates like find<T>, but returns a Result<NothingFound, T> instead of a Maybe<T>.

import { findR, NothingFound } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result: Result<NothingFound, number> = findR((item: number): boolean => item === 4)(list);
// Err<NothingFound>

`findItem`

This curried function finds the first item of the given ID in an array of objects of the interface { id: number }.

import { findItem } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [{ id: 1 }, { id: 2 }, { id: 3 }];
const result: Maybe<{ id: number }> = findItem(2)(list);
// Just<{ id: 2 }>

`findItemT`

This curried function wraps findItem functionality in a Task. It is particularly useful in chaining of tasks:

import { findItemT, ItemNotFound } from '@execonline-inc/collections';
import { Task } from 'taskarian';

const list = [{ id: 1 }, { id: 2 }, { id: 3 }];
const task = Task.succeed<ItemNotFound, { id: number }[]>(list);

const example: Task<ItemNotFound, { id: 2 }> = task.andThen(findItemT(2));

`findPayload`

findPayload accepts an ID and a list of payloads of a { payload: { id: number } } interface and returns the first payload with the matching ID as a Maybe.

This function has a curried and non-curried form

import { findPayload } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const payloads = [{ payload: { id: 1 } }, { payload: { id: 2 } }, { payload: { id: 3 } }];
const result: Maybe<{ payload: { id: number } }> = findPayload(2)(payloads);
// Just<{ payload: { id: 2 } }>

`findPayloadT`

Same as findItemT but with the functionality of findPayload.

import { findPayloadT, PayloadNotFound } from '@execonline-inc/collections';
import { Task } from 'taskarian';

const payloads = [{ payload: { id: 1 } }, { payload: { id: 2 } }, { payload: { id: 3 } }];
const task = Task.succeed<PayloadNotFound, { payload: { id: number } }[]>(payloads);

const example: Task<PayloadNotFound, { payload: { id: 2 } }> = task.andThen(findPayloadT(2));

`findPayloadByUuid`

Same as findPayload but takes a string as the UUID to find and a list of payloads of a { payload: { uuid: string } } interface.

import { findPayloadByUuid } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const payloads = [
  { payload: { uuid: 'cb08aa12-30f3-48b4-a6ec-bb95ca1e021d' } },
  { payload: { uuid: 'e1da03ff-46ff-49c9-bb69-a09ea68fbd76' } },
  { payload: { uuid: 'ea4c9aa3-b39b-4c3c-a931-b1bbc921970c' } },
];
const result: Maybe<{ payload: { id: number } }> = findPayloadByUuid(
  'cb08aa12-30f3-48b4-a6ec-bb95ca1e021d'
)(payloads);
// Just<{ payload: { uuid: 'cb08aa12-30f3-48b4-a6ec-bb95ca1e021d' } }>

`groupBy`

This curried function takes a function to derive the group key for each element and an array of items.

import { groupBy } from '@execonline-inc/collections';

const list = ['abc-123', 'abc-456', 'def-789'];
const result = groupBy((item: string): string => item.split('-').shift())(list);
// { 'abc': ['abc-123', 'abc-456'], 'def': ['def-789'] }

`toPairs`

This function takes an object and returns an array of key-value pairs.

import { toPairs } from '@execonline-inc/collections';

const obj = {
  abc: 123,
  def: 456,
};
const result = toPairs(obj);
// [['abc', 123], ['def', 456]]

`map`

This curried function takes a transformation function and a list of items to return a new list of items.

import { map } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result: number[] = map((item: number): number => item + 10)(list);
// [11, 12, 13]

`flatMap`

flatMap takes a list of items and a transformation function that returns an array for each item. The final return value is a flattened array of each of those resulting arrays.

This function has curried and non-curried form.

import { flatMap } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result = flatMap((item: number): number[] => [10, 100, 1000].map(n => n * item))(list);
// [10, 100, 1000, 20, 200, 2000, 30, 300, 3000]

`mapMaybe`

mapMaybe takes a list of items and a function that maps each item of the array to a Maybe. The final return value is an array of only the mapped values that were a Just.

This function has curried and non-curried form.

import { mapMaybe } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [1, 2, 3, 4, 5, 6];
const result = mapMaybe(
  (item: number): Maybe<number> => item % 2 ? nothing() : just(item);
)(list);
// [2, 4, 6]

`byId`

This curried function checks whether the given ID matches the ID in the given payload.

import { byId } from '@execonline-inc/collections';

const payload = { id: 123 };
const result: boolean = byId(123)(payload);

`byPayloadId`

This curried function checks whether the given ID matches the ID in the given resource.

import { byPayloadId } from '@execonline-inc/collections';

const resource = { payload: { id: 123 } };
const result: boolean = byPayloadId(123)(resource);

`byPayloadUuid`

This curried function checks whether the given UUID matches the UUID in the given resource.

import { byPayloadUuid } from '@execonline-inc/collections';

const resource = { payload: { id: '9f925583-7a8f-4459-979d-5ad2d5ede2f8' } };
const result: boolean = byPayloadUuid('9f925583-7a8f-4459-979d-5ad2d5ede2f8')(resource);

`sort`

sort provides stable sorting of an array using a given comparison function.

The comparison function should return:

< 0 to sort a before b
0 to consider a equal to b
> 0 to sort a after b

This function has a curried and non-curried form.

import { sort } from '@execonline-inc/collections';

const list = [
  { age: 30, name: 'Ava' },
  { age: 25, name: 'Bob' },
  { age: 20, name: 'Cas' },
  { age: 25, name: 'Dan' },
];
const result = sort((a, b) => a.age - b.age)(list);
// [{ age: 20, name: 'Cas' }, { age: 25, nam: 'Bob' }, { age: 25, name: 'Dan' }, { age: 30, name: 'Ava' }]

`take`

take creates a new array of the specified amount of items from the given array from its beginning.

This function has a curried and non-curried form.

import { take } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = take(3)(list);
// [1, 2, 3]

`first`

This function returns the first item from an array. When present, the item is wrapped in a Just, otherwise the return value is a Nothing.

import { first } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result = first(list);
// Just<1>

`last`

This function returns the last item from an array. When present, the item is wrapped in a Just, otherwise the return value is a Nothing.

import { last } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result = last(list);
// Just<3>

`takeLastUntil`

takeLastUntil returns a new array of the items from the end of the given array until the given function evalutes true.

This function has a curried and non-curried form.

import { takeLastUntil } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = takeLastUntil((item: number): boolean => item === 3)(list);
// [4, 5]

`takeLastWhile`

takeLastWhile returns a new array of the items from the end of the given array while the given function evaluates true.

This function has a curried and non-curried form.

import { takeLastWhile } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = takeLastWhile((item: number): boolean => item > 3)(list);
// [4, 5]