npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@execonline-inc/collections

v10.7.0

Published

Utilities for working with collections of data

Downloads

19

Readme

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]