Async Therefore I Am
A practical functional asynchronous library for JavaScript programmers.
Over the years, I've found myself rewriting utilities for handling Promise-based interactions in every new project I start. I wanted to have a place to pull these functions from and a basic requirement was that they should be modular, composable and purely functional.
This library is meant to give some building blocks form composing your business logic so that you can focus on that rather than needing to getting into the depths of writing a reduce that works asynchronously or figuring out how to batch a certain number of promises at a time.
NPM:
npm install cartesian-js -S
Yarn:
yarn add cartesian-js --save
The library can be used either by requiring the whole thing or even requiring individual functions. The package is modular and most of the functions are one or two liners, so your build size should not be affected much.
// Load the full build.
const cartesian-js = require('cartesian-js');
// Load the full build with ESM
import * as cartesian-js from 'cartesian-js';
// Pull in a single module
import { compose } from 'cartesian-js';
// Directly load a single module
import compose from 'cartesian-js/compose';
batch(Promise, { batchSize?: number; }) => (Array<any>) : Promise<response>
Executes a given number of promises against an array at a time.
Example:
import { batch } from "cartesian-js";
const result = await batch({
batchSize: 2,
})(
(x) => {
return new Promise((resolve) => {
setTimeout(() => {
resolve(x);
}, 10);
});
}
)([1, 2, 3, 4, 5]);
console.log(result); // [1, 2, 3, 4, 5]You may provide an optional retry object to the batch options to perform a set number of retries on each result:
import { batch, pipe } from "cartesian-js";
const result = await batch({
batchSize: 1,
retry: {
attempts: 3,
}
})(
myAsyncFunction,
)([...arr]);You may provide an optional handle function to the batch options to catch any errors on an individual item and deal with them without throwing
import { batch, pipe } from "cartesian-js";
const result = await batch({
batchSize: 2,
handle: (err) => {
// Just log the error and continue
console.warn(err);
// Whatever is returned here will be part of the resulting array
// If you don't return anything, it will have an `undefined` hole in the array
return {
error: true
}
}
})(
myAsyncFunction
)([...arr]);compose(...Promises<any>) => (any) : Promise<any>
Compose multiple promises. Composes from right to left.
Example:
import { compose } from "cartesian-js";
const result = await compose(
(x) => Promise.resolve(`${x}?`), // '8?'
(x) => Promise.resolve(x + 2), // 8
(x) => Promise.resolve(x * 2) // 6
)(3);filter(Promise) => (Array<any>) : Promise<response>
Filters over an array async.
Example:
import { filter } from "cartesian-js";
const result = await filter((x) => {
return Promise.resolve(x.includes("hi"));
})(["hi", "high", "hay"]);
console.log(result); // ["hi", "hey"]handle(Promise<any>) => [Error, Response]
Wraps a promise in a catch and returns an array of any caught errors as the first item in the array and the response as the second item.
Example:
import { handle } from "cartesian-js";
const [error, response] = await handle(api.deleteEverything);
if (error) {
console.log(error);
}
if (response) {
console.log(response);
}handleCompose(...Promises<any>) => (any) : Promise<[error, response]>
The same as compose, but wrapped in a handle. Returns an array of [error, response]
Example:
import { handleCompose } from "cartesian-js";
const [error, response] = await handleCompose(
(x) => Promise.resolve(`${x}?`), // '8?'
(x) => Promise.resolve(x + 2), // 8
(x) => Promise.resolve(x * 2) // 6
)(3);handlePipe(...Promises<any>) => (any) : Promise<[error, response]>
The same as pipe, but wrapped in a handle. Returns an array of [error, response]
Example:
import { handlePipe } from "cartesian-js";
const [error, result] = await handlePipe(
(x) => Promise.resolve(x * 2), // 6
(x) => Promise.resolve(x + 2), // 8
(x) => Promise.resolve(`${x}?`) // '8?'
)(3);map(Promise) => (Array<any>) : Promise<response>
Maps over an array async.
Example:
import { map } from "cartesian-js";
const result = await map((x) => Promise.resolve(x * 3))([1, 2, 3]);
console.log(result); // [3, 6, 9]pipe(...Promises<any>) => (any) : Promise<any>
Compose multiple promises. Each will pass its results to the next.
Example:
import { pipe } from "cartesian-js";
const result = await pipe(
(x) => Promise.resolve(x * 2), // 6
(x) => Promise.resolve(x + 2), // 8
(x) => Promise.resolve(`${x}?`) // '8?'
)(3);reduce(Promise, ?initialValue) => (Array<any>) : Promise<response>
Reduces over an array async.
Example:
import { reduce } from "cartesian-js";
const [six, seven] = await reduce((prev, x) => {
return Promise.resolve([...prev, x + 5]);
}, [])([1, 2]);
console.log(six); // 6({ attempts: number })(fn: () => Promise) => Promise<response>
Waits for a certain number of milliseconds and then proceeds.
Example:
import { retry } from "cartesian-js";
const result = await retry({
attempts: 3, // Number of times to retry before failing
})(myGreatPromise)(null);(milliseconds: number) => (any) : Promise<response>
Waits for a certain number of milliseconds and then proceeds.
Example:
import { sleep } from "cartesian-js";
console.log("Wait a second...");
const result = await sleep({
timeout: 1000,
})("Okay"); // Sleep for a second
console.log(result); // 'Okay'timeout({ timeout: number, errorMessage?: string })(() => Promise<any> => any : Promise<any>
If the timeout happens before a response comes back, we resolve an error.
Example:
import { timeout, handle } from "cartesian-js";
const [error, result] = await handle(
timeout({
timeout: 3000,
errorMessage: "Chronologically challenged",
})(longRunningPromise)
);tryCatch(Promise<any>) => [Error, Response] | tryCatch(Fn) => [Error, Response]
Tries to execute a function or a promise and returns either an error or the response.
Example:
import { tryCatch } from "cartesian-js";
const [error, response] = await tryCatch(api.deleteEverything);
if (error) {
console.log(error);
}
if (response) {
console.log(response);
}