Hyperjump Pact is a utility library for working with promises. Many promise implementations include these kinds of functions, but this is a promise-implementation agnostic library. All functions are curried and designed for pipelining.
Includes support for node.js JavaScript (CommonJS and ES Modules), TypeScript, and browsers.
npm install @hyperjump/pact --save
Run the tests
npm test
Run the tests with a continuous test runner
npm test -- --watch
The following is short demo using the [Hyperjump Browser][browser] whose use of promises is ideal for illustrating how these functions can be used. See the API section below to see all of the things you can do.
This example uses the API at https://swapi.hyperjump.io. It's a variation of the Star Wars API (SWAPI) implemented using the JRef media type.
const Hyperjump = require("@hyperjump/browser");
const Pact = require("@hyperjump/pact");
const characterHomeworlds = Pact.map(async (character) => {
const name = await character.name;
const homeworld = await character.homeworld.name;
return `${name} is from ${homeworld}`;
});
const ladies = Pact.pipeline([
Pact.filter(async (character) => (await character.gender) === "female"),
Pact.map((character) => character.name)
]);
const mass = Pact.reduce(async (acc, character) => {
return acc + (parseInt(await character.mass, 10) || 0);
}, 0);
(async function () {
const film = Hyperjump.fetch("https://swapi.hyperjump.io/api/films/1");
await film.title; // --> A New Hope
await characterHomeworlds(film.characters); // --> [ 'Luke Skywalker is from Tatooine',
// --> 'C-3PO is from Tatooine',
// --> 'R2-D2 is from Naboo',
// --> ... ]
await ladies(film.characters); // --> [ 'Leia Organa', 'Beru Whitesun lars' ]
await mass(film.characters); // --> 1290
}());
The documentation here is pretty light, but these are implementations of common higher-order functions and they work exactly like you would expect them to except that they work with promises.
Similar to Object.entries
.
Similar to Array.map
.
await map(async (n) => await n + 1, [Promise.resolve(1), Promise.resolve(2)])
// => [Promise.resolve(2), Promise.resolve(3)]
Similar to Array.filter
except the return value of the test function can be a
Promise<boolean>
as well as a boolean
.
await filter(async (n) => await n > 1, [Promise.resolve(1), Promise.resolve(2)])
// => [Promise.resolve(2)]
Similar to Array.reduce
except optimized for Promises.
await reduce(async (sum, n) => sum + await n, 0, [Promise.resolve(1), Promise.resolve(2)]) // => 3
Similar to Array.some
.
await some(async (n) => n > 1, [Promise.resolve(1), Promise.resolve(2)])
// => true
Similar to Array.every
.
await every(async (n) => n > 1, [Promise.resolve(1), Promise.resolve(2)])
// => false
Compose an array of functions that call the next function with result of the previous function.
await pipeline([
filter(async (n) => await n > 1),
map(async (n) => await n + 1),
reduce(async (sum, n) => sum + await n, 0)
], [Promise.resolve(1), Promise.resolve(2), Promise.resolve(3)])
// => 7
Same as the standard Promise.all
except more convenient to use with
pipeline
.
allValues
is like all
except it resolves promise for each value in an object
rather than each item in an array.