Skip to content

Higher order functions for iterators/generators and async iterators/generators

License

Notifications You must be signed in to change notification settings

hyperjump-io/pact

Repository files navigation

Hyperjump Pact

Hyperjump Pact is a utility library that provides higher order functions for working with iterators and async iterators.

Installation

Designed for node.js (ES Modules, TypeScript) and browsers.

npm install @hyperjump/pact --save

Usage

import { pipe, range, map, filter, reduce } from "@hyperjump/pact";


const result = pipe(
  range(1, 10),
  filter((n) => n % 2 === 0),
  map((n) => n * 2),
  reduce((sum, n) => sum + n, 0)
);
console.log(result);
import { pipe, asyncMap, asyncFilter, asyncReduce } from "@hyperjump/pact";
// You can alternatively import the async functions without the prefix
// import { pipe, map, filter, reduce } from "@hyperjump/pact/async";


const asyncSequence = async function* () {
  yield 1;
  yield 2;
  yield 3;
  yield 4;
  yield 5;
};

for await (const value of asyncSequence()) {
  console.log(value);
}

const result = await pipe(
  asyncSequence(),
  asyncFilter((n) => n % 2 === 0),
  asyncMap((n) => n * 2),
  asyncReduce((sum, n) => sum + n, 0)
);
console.log(result);

API

  • map: (fn: Function, iterator: Iterable) => Generator

    Apply a function to every value in the iterator

  • asyncMap: (fn: Function, iterator: AsyncIterable) => AsyncGenerator

    Same as map, but works with AsyncGenerators and async mapping functions.

  • tap: (fn: Function, iterator: Iterable) => Generator

    Apply a function to every value in the iterator, but yield the original value, not the result of the function.

  • asyncTap: (fn: Function, iterator: AsyncIterable) => AsyncGenerator

    Same as tap, but works with AsyncGenerators.

  • filter: (fn: Function, iterator: Iterable) => Generator

    Yields only the values in the iterator that pass the predicate function.

  • asyncFilter: (fn: Function, iterator: AsyncIterable) => AsyncGenerator

    Same as filter, but works with AsyncGenerators and async predicate functions.

  • scan: (fn: Function, acc: any, iter: Iterable) => any

    Same as reduce except it emits the accumulated value after each update

  • asyncScan: (fn: Function, acc: any, iter: AsyncIterable) => Promise

    Same as scan, but works with AsyncGenerators and async predicate functions.

  • flatten: (iterator: NestedIterable, depth: number = 1) => Generator

    Yields values from the iterator with all sub-iterator elements concatenated into it recursively up to the specified depth.

  • asyncFlatten: (iterator: NestedAsyncIterable, depth: number = 1) => AsyncGenerator

    Same as flatten, but works with AsyncGenerators.

  • drop: (n: number, iterator: Iterable) => Generator

    Yields all the values in the iterator except for the first n values.

  • asyncDrop: (n: number, iterator: AsyncIterable) => AsyncGenerator

    Same as drop, but works with AsyncGenerators.

  • dropWhile: (fn: Function, iterator: Iterable) => Generator

    Same as drop but instead of dropping a specific number of values, it drops values until the fn(value) is false and then yields the remaining values.

  • asyncDropWhile: (fn: Function, iterator: AsyncIterable) => AsyncGenerator

    Same as dropWhile, but works with AsyncGenerators.

  • take: (n: number, iterator: Iterable) => Generator

    Yields the first n values in the iterator.

  • asyncTake: (n: number, iterator: AsyncIterable) => AsyncGenerator

    Same as take, but works with AsyncGenerators.

  • takeWhile: (fn: Function, iterator: Iterable) => Generator

    Same as take but instead of yielding a specific number of values, it yields values as long as the fn(value) returns true and drops the rest.

  • asyncTakeWhile: (fn: Function, iterator: AsyncIterable) => AsyncGenerator

    Same as takeWhile, but works with AsyncGenerators.

  • head: (iterator: Iterable) => A

    Returns the first value in the iterator.

  • asyncHead: (iterator: AsyncIterable) => A

    Same as head, but works with AsyncGenerators.

  • range: (from: number, to?: number) => Generator

    Yields numbers starting from from until to. If to is not passed, the iterator will be infinite.

  • empty: () => Generator

    Yields nothing.

  • asyncEmpty: () => AsyncGenerator

    Yields nothing asynchronously.

  • zip: (iter1: Iterable, iter2: Iterable) => Generator

    Yields tuples containing a value from each iterator. The iterator will have the same length as iter1. If iter1 is longer than iter2, the second value of the tuple will be undefined. If iter2 is longer than iter1, the remaining values in iter2 will be ignored.

  • asyncZip: (iter1: AsyncIterable, iter2: AsyncIterable) => AsyncGenerator

    Same as zip but works with AsyncGenerators.

  • concat: (...iters: Iterable[]) => Generator

    Yields values from each iterator in order.

  • asyncConcat: (...iters: AsyncIterable[]) => AsyncGenerator

    Same as concat but works with AsyncGenerators.

  • reduce: (fn: Function, acc: any, iter: Iterable) => any

    Reduce an iterator to a single value.

  • asyncReduce: (fn: Function, acc: A, iter: AsyncIterable) => Promise

    Same as reduce, but works with AsyncGenerators and async reducer functions.

  • every: (fn: Function, iterator: Iterable) => boolean

    Returns a boolean indicating whether or not all values in the iterator passes the predicate function.

  • asyncEvery: (fn: Function, iterator: AsyncIterable) => Promise

    Same as every, but works with AsyncGenerators and async predicate functions.

  • some: (fn: Function, iterator: Iterable) => boolean

    Returns a boolean indicating whether or not there exists a value in the iterator that passes the predicate function.

  • asyncSome: (fn: Function, iterator: AsyncIterable) => Promise

    Same as some, but works with AsyncGenerators and async predicate functions.

  • find: (fn: Function, iterator: Iterable) => any

    Returns the first value that passes the predicate function.

  • asyncFind: (fn: Function, iterator: AsyncIterable) => Promise

    Same as find, but works with AsyncGenerators and async predicate functions.

  • count: (iterator: Iterable) => number

    Returns the number of items in the iterator.

  • asyncCount: (iterator: AsyncIterable) => Promise

    Same as count, but works with AsyncGenerators.

  • collectArray: (iterator: Iterable) => Array;

    Collect all the items in the iterator into an array.

  • asyncCollectArray: (iterator: AsyncIterable) => Promise;

    Same as collectArray, but works with AsyncGenerators.

  • collectSet: (iterator: Iterable) => Set;

    Collect all the items in the iterator into a Set.

  • asyncCollectSet: (iterator: AsyncIterable) => Promise;

    Same as collectSet, but works with AsyncGenerators.

  • collectMap: (iterator: Iterable) => Map;

    Collect all the key/value tuples in the iterator into a Map.

  • asyncCollectMap: (iterator: AsyncIterable) => Promise;

    Same as collectMap, but works with AsyncGenerators.

  • collectObject: (iterator: Iterable) => Object;

    Collect all the key/value tuples in the iterator into an Object.

  • asyncCollectObject: (iterator: AsyncIterable) => Promise;

    Same as collectObject, but works with AsyncGenerators.

  • join: (separator: string, iterator: Iterable) => string;

    Collect all the items in the iterator into a string separated by the separator token.

  • asyncJoin: (separator: string, iterator: AsyncIterable) => Promise;

    Same as join, but works with AsyncGenerators.

  • pipe: (iterator: Iterable | AsyncIterable, ...fns: Function) => any;

    Starting with an iterator, apply any number of functions to transform the values and return the result.

  • Contributing

    Tests

    Run the tests

    npm test

    Run the tests with a continuous test runner

    npm test -- --watch

About

Higher order functions for iterators/generators and async iterators/generators

Resources

License

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published