array-fp-utils

Array utilities for functional programming in TypeScript.

Features

• Battle tested performance;
• Meant to be used with a proper FP library, such as fp-ts;
• Extensive tests.

Installation

npm install array-fp-utils

Requirements

• Node.js v.16+

API

• groupBy
• intersect
• intersectWith
• isDistinctArray
• isSameValueSet
• isSameValueSetWith
• isSubsetOf
• isSubsetOfWith
• unique
• uniqueBy

groupBy

import{pipe}from'fp-ts/lib/function';import{groupBy}from'array-fp-utils';constarr=[{key: 2,score: 2,},{key: 1,score: 0.5,},{key: 1,score: 1,},];// group by key, while maintaining array item orderconstgroupedArr=pipe(arr,groupBy((item)=>item.key));// groupedArr now contains the following// [// [// {// "key": 2,// "score": 2,// },// ],// [// {// "key": 1,// "score": 0.5,// },// {// "key": 1,// "score": 1,// },// ],// ]

intersect

import{pipe}from'fp-ts/lib/function';import{intersect}from'array-fp-utils';constarr=['a','b','c','d','e'];constotherArr=['b','c','f'];// calculates the intersection of two arraysconstintersection=pipe(arr,intersect(otherArr));// returns ['b', 'c']

intersectWith

import{pipe}from'fp-ts/lib/function';import{intersectWith}from'array-fp-utils';constarr=[{foo: 'a'},{foo: 'b'},{foo: 'c'},{foo: 'd'},{foo: 'e'},];constotherArr=[{bar: 'b'},{bar: 'c'},{bar: 'f'}];// calculate the intersection of two arrays using comparator functionconstarr=pipe(mockData,intersectWith(otherArr,(item,otherItem)=>item.foo===otherItem.bar));// arr = [{ foo: 'b' }, { foo: 'c' }]

isDistinctArray

import{pipe}from'fp-ts/lib/function';import{isDistinctArray}from'array-fp-utils';pipe([1,2,3],isDistinctArray);// returns truepipe([1,1,2,3],isDistinctArray);// returns false

isSameValueSet

Indicates whether an array contains the same set of items with another array, irrelevant of position (sorting).

Note: only accepts arrays of primitive values.

Example

import{pipe}from'fp-ts/lib/function';import{isSameValueSet}from'array-fp-utils';pipe([1,2,3],isSameValueSet([3,2,1]));// returns truepipe([1,2],isSameValueSet([1,2,3]));// returns falsepipe([1,2,3],isSameValueSet([1,2,4]));// returns false

isSameValueSetWith

Indicates whether an array contains the same set of items with another array, irrelevant of position (sorting), using a comparator function.

Example

import{pipe}from'fp-ts/lib/function';import{isSameValueSetWith}from'array-fp-utils';pipe([{key: 1},{key: 2},{key: 3}],isSameValueSetWith([3,2,1],(value,otherValue)=>value.key===otherValue));// returns true

isSubsetOf

import{pipe}from'fp-ts/lib/function';import{isSubsetOf}from'array-fp-utils';constarr=['a','b','c','d'];constisSubset=pipe(['b','d'],isSubsetOf(arr));// returns trueconstisSubset=pipe(['a','e'],isSubsetOf(arr));// returns false

isSubsetOfWith

import{pipe}from'fp-ts/lib/function';import{isSubsetOfWith}from'array-fp-utils';constarr=[{foo: 'a'},{foo: 'b'},{foo: 'c'},{foo: 'd'},{foo: 'e'},];constotherArr=[{bar: 'b'},{bar: 'c'},{bar: 'f'}];constisSubset=pipe(arr,isSubsetOfWith(otherArr,(item,otherItem)=>item.foo===otherItem.bar));// returns false since "f" does not exist in arr

unique

import{pipe}from'fp-ts/lib/function';import{unique}from'array-fp-utils';constcountries=['Greece','Greece','Greece','United States','United Kingdom''United States',];// returns ['Greece', 'United Kingdom', 'United State']constuniqueArray=pipe(countries,unique);

uniqueBy

import{pipe}from'fp-ts/lib/function';import{uniqueBy}from'array-fp-utils';constusers=[{id: 1,name: 'John'},{id: 2,name: 'Michael'}{id: 3,name: 'Michael'}]// removes duplicate values from array in FiFo// returns [{id:1, name: 'John'}, {id:2, name: 'Michael'}]constuniqueArray=pipe(users,uniqueBy((user)=>user.name))

Motivation

This library is a collection of array utils, written with FP principles. They focus on performance instead of compatibility.

The alternative would be to use a library like lodash. However, lodash in an attempt to be backwards compatible with older browsers, falls behind on performance. In addition, lodash/groupBy changes the initial order of the array items.

Contribute

Source code contributions are most welcome. Please open a PR, ensure the linter is satisfied and all tests pass.

We are hiring

Causaly is building the world's largest biomedical knowledge platform, using technologies such as TypeScript, React and Node.js. Find out more about our openings at https://apply.workable.com/causaly/.

License

MIT