cartesian-js v5.0.0
CartesianJS
Async Therefore I Am
A practical functional asynchronous library for JavaScript programmers.
Why Cartesian?
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.
Installation
NPM:
npm install cartesian-js -SYarn:
yarn add cartesian-js --saveThe 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';API
batch
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]map
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]);handle
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
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
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
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
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
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
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
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
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); // 6retry
({ 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);sleep
(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({ 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
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);
}