relign v1.0.0-alpha-1

If you encounter a bug please report it.

Relign is a little utility library for processing data and tasks in concurrent or serial patterns. It's heavily inspired by the wonderful library async which was widly used back in the bad old days of callback patterns popular in node programs at the time. Relign is for modern TypeScript and JavaScript programs that use async functions and promises.

Relign is a collection of functions that take tasks or data and process them in various ways. These functions are all designed to be simple and easy to use without confusion.

Installation

Relign is published on NPM. It can be used in any TypeScript or JavaScript project, and is esm or cjs compatible.

npm i relign

import { parallelMapLimit } from 'relign';

const urlsToFetch: string[] = [
  'https://coolsite.com/path/one',
  'https://coolsite.com/path/two',
  'https://coolsite.com/path/three',
  //...
  'https://coolsite.com/path/oneThousand',
]

const resultJson = await parallelMapLimit(urlsToFetch, async url => {
  const response = await fetch(url);
  return response.json();
}, 10);

A Note on Execution

One of the main things that make relign special is how it handles data or tasks.

Relign will happily accept any value as a task. If the value is a function it will be executed. If the value is a promise it will be awaited. If the value is a function that returns a promise, the promise will be awaited. If the value is anything else it will be returned as is. This means that you can pass a mix of functions, promises, and values to any relign function accepting tasks and it will do the right thing.

Item functions work in a similar way, but instead these functions take a worker function that is called for each item in the collection. This function is executed in the same way as tasks. That means if the worker returns a promise, the promise will be awaited. If the worker returns a value that value will be returned as is.

Function Index

• parallel
• parallelLimit
• series
• auto
• parallelMap
• parallelMapLimit
• seriesMap
• parallelFilter
• parallelFilterLimit
• seriesFilter
• parallelFind
• parallelFindLimit
• seriesFind
• parallelFlatMap
• parallelFlatMapLimit
• seriesFlatMap
• seriesReduce
• nextTick
• setTimeout
• setInterval
• cbToPromise
• exec

Parallel

The parallel function takes a collection of tasks and executes them concurrently. It returns a promise that resolves to an array of the results of each task. It will happily accept an array or object of tasks. Tasks can be functions, promises, functions that return a promise, or any other value.

With an Array

import { parallel } from 'relign';

const results = await parallel([
  1,
  Promise.resolve(2),
  async () => 3,
  async () => Promise.resolve(4),
])

console.log(results); // [1, 2, 3, 4]

With an Object

import { parallel } from 'relign';

const results = await parallel({
  one: 1,
  two: Promise.resolve(2),
  three: async () => 3,
  four: async () => Promise.resolve(4),
})

console.log(results); // { one: 1, two: 2, three: 3, four: 4 }

Parallel Limit

The parallelLimit function takes a collection of tasks and executes them concurrently with a limit on the number of tasks that can be executed at once. It returns a promise that resolves to an array of the results of each task. It will happily accept an array or object of tasks. Tasks can be functions, promises, functions that return a promise, or any other value.

With an Array

import { parallelLimit } from 'relign';

const results = await parallelLimit([
  1,
  Promise.resolve(2),
  async () => 3,
  async () => Promise.resolve(4),
], 2)

console.log(results); // [1, 2, 3, 4]

With an Object

import { parallelLimit } from 'relign';

const results = await parallelLimit({
  one: 1,
  two: Promise.resolve(2),
  three: async () => 3,
  four: async () => Promise.resolve(4),
}, 2)

console.log(results); // { one: 1, two: 2, three: 3, four: 4 }

Series

The series function takes a collection of tasks and executes them in series. It returns a promise that resolves to an array of the results of each task. It will happily accept an array or object of tasks. Tasks can be functions, promises, functions that return a promise, or any other value.

With an Array

import { series } from 'relign';

const results = await series([
  1,
  Promise.resolve(2),
  async () => 3,
  async () => Promise.resolve(4),
])

console.log(results); // [1, 2, 3, 4]

With an Object

import { series } from 'relign';

const results = await series({
  one: 1,
  two: Promise.resolve(2),
  three: async () => 3,
  four: async () => Promise.resolve(4),
})

console.log(results); // { one: 1, two: 2, three: 3, four: 4 }

Auto

The auto function is great when you want tasks to be executed in a specific order based on dependencies on one another, but still want to run non interdependent tasks concurrently. It takes an object with a key for each task and a array value of dependencies and a task. It returns a promise that resolves to an object with the results of each task. Tasks can be functions, promises, functions that return promises, or any other value.

import { auto } from 'relign';

const results = await auto({
  one: [1],
  two: [Promise.resolve(2)],
  three: ['one', 'two', async ({ one, two }) => one + two],
  four: ['two', async ({ two }) => two * 2],
})

console.log(results); // { one: 1, two: 2, three: 3, four: 4 }

Parallel Map

The parallelMap function takes a collection of items and a map function. It will then concurrently process each item in the collection with the map function. Note that the map function can return a promise or any other value. If a promise is returned, the result of the promise will be used as the value for the item in the results array. If any other value is returned, that value will be used as is.

With an Array

import { parallelMap } from 'relign';

const results = await parallelMap([1, 2, 3, 4], async (item) => {
  return item * 2;
})

console.log(results); // [2, 4, 6, 8]

With an Object

import { parallelMap } from 'relign';

const results = await parallelMap({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item * 2;
})

console.log(results); // { one: 2, two: 4, three: 6, four: 8 }

Parallel Map Limit

The parallelMapLimit function takes a collection of items, a map function, and a limit. It will then concurrently process each item in the collection with the map function with a limit on the number of items that can be processed at once. Note that the map function can return a promise or any other value. If a promise is returned, the result of the promise will be used as the value for the item in the results array. If any other value is returned, that value will be used as is.

With an Array

import { parallelMapLimit } from 'relign';

const results = await parallelMapLimit([1, 2, 3, 4], async (item) => {
  return item * 2;
}, 2)

console.log(results); // [2, 4, 6, 8]

With an Object

import { parallelMapLimit } from 'relign';

const results = await parallelMapLimit({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item * 2;
}, 2)

console.log(results); // { one: 2, two: 4, three: 6, four: 8 }

Series Map

The seriesMap function takes a collection of items and a map function. It will then process each item in the collection with the map function in series. Note that the map function can return a promise or any other value. If a promise is returned, the result of the promise will be used as the value for the item in the results array. If any other value is returned, that value will be used as is.

With an Array

import { seriesMap } from 'relign';

const results = await seriesMap([1, 2, 3, 4], async (item) => {
  return item * 2;
})

console.log(results); // [2, 4, 6, 8]

With an Object

import { seriesMap } from 'relign';

const results = await seriesMap({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item * 2;
})

console.log(results); // { one: 2, two: 4, three: 6, four: 8 }

Parallel Filter

The parallelFilter function takes a collection of items and a filter function. It will then concurrently process each item in the collection with the filter function. Note that the filter function can return a promise that resolves to a boolean or a boolean. The boolean will be used to determine if the item should be included in the results.

With an Array

import { parallelFilter } from 'relign';

const results = await parallelFilter([1, 2, 3, 4], async (item) => {
  return item % 2 === 0;
})

console.log(results); // [2, 4]

With an Object

import { parallelFilter } from 'relign';

const results = await parallelFilter({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item % 2 === 0;
})

console.log(results); // { two: 2, four: 4 }

Parallel Filter Limit

The parallelFilterLimit function takes a collection of items, a filter function, and a limit. It will then concurrently process each item in the collection with the filter function with a limit on the number of items that can be processed at once. Note that the filter function can return a promise that resolves to a boolean or a boolean. The boolean will be used to determine if the item should be included in the results.

With an Array

import { parallelFilterLimit } from 'relign';

const results = await parallelFilterLimit([1, 2, 3, 4], async (item) => {
  return item % 2 === 0;
}, 2)

console.log(results); // [2, 4]

With an Object

import { parallelFilterLimit } from 'relign';

const results = await parallelFilterLimit({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item % 2 === 0;
}, 2)

console.log(results); // { two: 2, four: 4 }

Series Filter

The seriesFilter function takes a collection of items and a filter function. It will then process each item in the collection with the filter function in series. Note that the filter function can return a promise that resolves to a boolean or a boolean. The boolean will be used to determine if the item should be included in the results.

With an Array

import { seriesFilter } from 'relign';

const results = await seriesFilter([1, 2, 3, 4], async (item) => {
  return item % 2 === 0;
})

console.log(results); // [2, 4]

With an Object

import { seriesFilter } from 'relign';

const results = await seriesFilter({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item % 2 === 0;
})

console.log(results); // { two: 2, four: 4 }

Parallel Find

The parallelFind function takes a collection of items and a find function. It will then concurrently execute the find function on each item in the collection until the find function returns a promise that resolves to true, or true. The first item to result in true being returned or resolved will be returned as the result. If no item results in true, undefined will be returned.

With an Array

import { parallelFind } from 'relign';

const result = await parallelFind([1, 2, 3, 4], async (item) => {
  return item === 3;
})

console.log(result); // 3

With an Object

import { parallelFind } from 'relign';

const result = await parallelFind({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item === 3;
})

console.log(result); // 3

Parallel Find Limit

The parallelFindLimit function takes a collection of items, a find function, and a limit. It will then concurrently execute the find function on each item in the collection with a limit on the number of items that can be processed at once. The find function will be executed on each item in the collection until the find function returns a promise that resolves to true, or true. The first item to result in true being returned or resolved will be returned as the result. If no item results in true, undefined will be returned.

With an Array

import { parallelFindLimit } from 'relign';

const result = await parallelFindLimit([1, 2, 3, 4], async (item) => {
  return item === 3;
}, 2)

console.log(result); // 3

With an Object

import { parallelFindLimit } from 'relign';

const result = await parallelFindLimit({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item === 3;
}, 2)

console.log(result); // 3

Series Find

The seriesFind function takes a collection of items and a find function. It will then execute the find function on each item in the collection in series until the find function returns a promise that resolves to true, or true. The first item to result in true being returned or resolved will be returned as the result. If no item results in true, undefined will be returned.

With an Array

import { seriesFind } from 'relign';

const result = await seriesFind([1, 2, 3, 4], async (item) => {
  return item === 3;
})

console.log(result); // 3

With an Object

import { seriesFind } from 'relign';

const result = await seriesFind({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return item === 3;
})

console.log(result); // 3

Parallel Flat Map

The parallelFlatMap function takes a collection of items and a flat map function. It will then concurrently execute the flat map function on each item in the collection. Note that the flat map function can return a promise that resolves to an array or an array. The array will be flattened into the result.

With an Array

import { parallelFlatMap } from 'relign';

const results = await parallelFlatMap([1, 2, 3, 4], async (item) => {
  return [item, item];
})

console.log(results); // [1, 1, 2, 2, 3, 3, 4, 4]

With an Object

import { parallelFlatMap } from 'relign';

const results = await parallelFlatMap({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return [item, item];
})

console.log(results); // [1, 1, 2, 2, 3, 3, 4, 4]

Parallel Flat Map Limit

The parallelFlatMapLimit function takes a collection of items, a flat map function, and a limit. It will then concurrently execute the flat map function on each item in the collection with a limit on the number of items that can be processed at once. Note that the flat map function can return a promise that resolves to an array or an array. The array will be flattened into the result.

With an Array

import { parallelFlatMapLimit } from 'relign';

const results = await parallelFlatMapLimit([1, 2, 3, 4], async (item) => {
  return [item, item];
}, 2)

console.log(results); // [1, 1, 2, 2, 3, 3, 4, 4]

With an Object

import { parallelFlatMapLimit } from 'relign';

const results = await parallelFlatMapLimit({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return [item, item];
}, 2)

console.log(results); // [1, 1, 2, 2, 3, 3, 4, 4]

Series Flat Map

The seriesFlatMap function takes a collection of items and a flat map function. It will then execute the flat map function on each item in the collection in series. Note that the flat map function can return a promise that resolves to an array or an array. The array will be flattened into the result.

With an Array

import { seriesFlatMap } from 'relign';

const results = await seriesFlatMap([1, 2, 3, 4], async (item) => {
  return [item, item];
})

console.log(results); // [1, 1, 2, 2, 3, 3, 4, 4]

With an Object

import { seriesFlatMap } from 'relign';

const results = await seriesFlatMap({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (item) => {
  return [item, item];
})

console.log(results); // [1, 1, 2, 2, 3, 3, 4, 4]

Series Reduce

The seriesReduce function takes a collection of items, a reducer function, and an initial value. It will then execute the reducer function on each item in the collection in series. The result of the reducer function can be a promise or any value. If the reducer function returns a promise, the result of the promise will be used as the memo for the next iteration, otherwise the return value will be used as the memo. After all items have been processed, the memo will be returned as the result.

With an Array

import { seriesReduce } from 'relign';

const result = await seriesReduce([1, 2, 3, 4], async (memo, item) => {
  return memo + item;
}, 0)

console.log(result); // 10

With an Object

import { seriesReduce } from 'relign';

const result = await seriesReduce({
  one: 1,
  two: 2,
  three: 3,
  four: 4,
}, async (memo, item) => {
  return memo + item;
}, 0)

console.log(result); // 10

Next Tick

The nextTick function returns a promise that resolves on the next tick of the event loop. If used in a browser, requestAnimationFrame under the hood instead of node's process.nextTick.

import { nextTick } from 'relign';

await nextTick();

Next tick can also take a task or value as an argument. If a task is passed, the task will be executed on the next tick of the event loop and the promise will resolve to the result of the task. If a value is passed, the promise will resolve to the value on the next tick of the event loop.

import { nextTick } from 'relign';

const result = await nextTick(() => {
  return 'hello world';
});

console.log(result); // 'hello world'

Set Timeout

The setTimeout takes a delay and returns a promise that resolves after the delay has elapsed.

import { setTimeout } from 'relign';

await setTimeout(1000);

Set timeout can also take a task or value as an argument. If a task is passed, the task will be executed after the delay has elapsed and the promise will resolve to the result of the task. If a value is passed, the promise will resolve to the value after the delay has elapsed.

import { setTimeout } from 'relign';

const result = await setTimeout(1000, () => {
  return 'hello world';
});

console.log(result); // 'hello world'

Set Interval

The setInterval takes a task and a interval duration. It will call the task every interval period until the task throws, or executes the resolve function passed to it. The promise returned by setInterval will not resolve until the task throws or executes the resolve function passed to it. If the task calls the resolve function and passes a value, the promise will resolve to that value.

import { setInterval } from 'relign';

let count = 0;

const result = await setInterval(1000, (resolve) => {
  count += 1;

  if (count === 5) {
    resolve(count);
  }
});

console.log(result); // 5

Callback to Promise

The cbToPromise function takes a function that uses the error first callback pattern and returns a function that returns a promise. The returned function will call the original function and resolve or reject the promise based on the error first callback.

import { cbToPromise } from 'relign';

const readFile = cbToPromise(fs.readFile);

const result = await readFile('./package.json', 'utf8');

console.log(result); // package.json contents

Execute

The exec function is the heart of relign and is used by a majority of the functions above. The execute function takes a task or value and executes it. If the task is a function, it will be called and the result will be returned. If the task is a promise, the promise will be awaited and the result will be returned. If the task is any other value, the value will be returned.

import { exec } from 'relign';

const result = exec(() => {
  return 'hello world';
});

console.log(result); // 'hello world'

Help Welcome

If you want to support this project by throwing be some coffee money It's greatly appreciated.

If your interested in providing feedback or would like to contribute please feel free to do so. I recommend first opening an issue expressing your feedback or intent to contribute a change, from there we can consider your feedback or guide your contribution efforts. Any and all help is greatly appreciated since this is an open source effort after all.

Thank you!