Pledge is a utility library designed to simplify error handling in JavaScript applications using Promises. It provides functions that wrap promises, try-catch blocks, callback-based functions, and timed operations, returning tuples instead of throwing errors.
- All pledge items return a tuple/array with the first item in the tuple being an Error | undefined and the second
item in the tuple being of type
T | undefined. - Pledge has a type for this tuple called
PledgeResult<T> - All pledge functions take an optional parameter object that allows you to supply an abort controller, giving you the ability to cancel the execution of the promise at any time.
- Pledge has full Typescript support
You can install Pledge via npm or pnpm:
npm
npm install @austinbreslin/pledgepnpm
pnpm add @austinbreslin/pledgeAllows you to reduce your boilerplate code for using pledge, by using the exact same constructor used in new Promise.
Signature
newPledge<T>(cb: (resolve: (value: T) => void, reject: (reason?: unknown) => void) => void): PledgeResult<T>Usage
import { newPledge } from "@austinbreslin/pledge";
const example = newPledge((resolve, reject) => {
// do something as if your in a promise
resolve({ example: 'data' });
});
const result = await example();
console.log(result); // [undefined, { example: 'data' }]Wraps an already constructed promise object and ensures it returns a tuple.
Signature
async pledge<T>(Promise<T>, options?: { abortController: AbortController }): PledgeResult<T>Usage
import { pledge } from '@austinbreslin/pledge';
const result = await pledge(Promise.resolve({ example: 'data' }));
console.log(result); // [undefined, { example: 'data' }]Reduces the boilerplate code when you want to run code that could throw an error.
Signature
<T>(fn: () => T) => voidUsage
import { pledgeTryCatch } from "@austinbreslin/pledge";
const result = pledgeTryCatch<object>(() => {
return JSON.parse('abc{}invalid');
});
console.log(result); // [SyntaxError: Unexpected token 'a', "abc{}invalid" is not valid JSON, undefined]Converts a callback function into pledge wrapped promise. This does not accept options as a second parameter.
Signature
async <T>(fn: (...arguments: unknown[], callback: (err: Error | undefined, data: T | undefined) => void)) => void;Usage
import { pledgify } from "@austinbreslin/pledge";
const example = (toWhom, cb) => {
// You shouldn't create callbacks anymore, but some old libraries will still
// use this format.
try {
const parsed = JSON.parse(`abc{ hello: '${toWhom}'}invalid`);
cb(undefined, parsed);
} catch (error) {
cb(error, undefined);
}
};
const wrapped = pledgify(example);
const result = await wrapped("John Smith");
console.log(result); // [SyntaxError: Unexpected token, undefined]An alternative to Promise.all that returns a tuple
Signature
async <T>(promise: Promise[], options?: { abortController: AbortController }): PledgeResult<T>Usage
import { pledgeAll } from "@austinbreslin/pledge";
const promises = [
fetch('https://example.com'),
fetch('https://example.com')
];
const pledged = await pledgeAll(promises);
console.log(pledged); // [undefined, [fetch1:Response, fetch2:Response]]An alternative to Promise.allSettled, but returns an array of errors and an array of results in the order you specified, unlike Promise.all which forces you to check each result to discover if that promise failed or not.
Signature
async <T>(promise: Promise[], options?: { abortController: AbortController }): [Error[], T[]]Usage
import { pledgeAllSettled } from "@austinbreslin/pledge";
const promises = [
fetch('https://example.com'),
fetch('invalidhttps://example.com'),
];
const pledged = await pledgeAllSettled(promises);
console.log(pledge); // [[undefined, net::ERR_NAME_NOT_RESOLVED], [Response, undefined]]An alternative to Promise.race
Signature
async <T>(promises: Promise[], options?: { abortController: AbortController }): PledgeResult<T>Usage
import { pledgeRace } from "@austinbreslin/pledge"
const promises = [
fetch('https://example.com'),
fetch('https://example.com'),
];
const pledged = await pledgeRace(promises);
console.log(pledged); // [undefined, Response]An alternative to Promise.any
Signature
async <T>(promises: Promise[], options?: { abortController: AbortController }): PledgeResult<T>Usage
import { pledgeAny } from "@austinbreslin/pledge";
const promises = [
fetch('https://example.com'),
fetch('invalidhttps://example.com')
];
const pledged = await pledgeAny(promises);
console.log(pledged); // [undefined, [Response]]
// Doesn't error out, because 1 passedAn alternative to pledge, but with time options. It will cancel the promise if it exceeds the set time. The time unit is milliseconds, and the default is 0ms.
Signature
async <T>(promise: Promise<T>, timeoutMs: number, options?: { abortController: AbortController }): PledgeResult<T>Usage
import { pledgeTimed } from "@austinbreslin/pledge";
const pledged = await pledgeTimed(fetch('https://example.com'), 20);
console.log(pledged); // [Error('Pledge time out occurred at set time:'), undefined] An alternative to pledgeAll, but with time options. It will cancel all the promises if any of them exceed the set time. The time unit is milliseconds, and the default is 0ms.
Signature
async <T>(promises: Promise[], timeoutMs: number, options?: { abortController: AbortController }): PledgeResult<T>Usage
import { pledgeAllTimed } from "@austinbreslin/pledge";
const promises = [
fetch('https://example.com'),
fetch('https://example.com')
];
const pledged = await pledgeAllTimed(promises, 20);
console.log(pledged); // [Error('Pledge time out occurred at set time:'), undefined]
const success = await pledgeAllTimed(promises, 2000);
console.log(success); // [undefined, [Response1, Response1]]An alternative to pledgeAllSettled, but with time options. It will cancel all the promises if any of them exceed the set time. The unit is milliseconds, and the default is 0ms.
Signature
async <T>(promises: Promise[], timeoutMs: Number, options?: { abortController: AbortController }): [(Error | undefined)[], (T | undefined)[]]Usage
import { pledgeAllSettledTimed } from "@austinbreslin/pledge";
const promises = [
fetch('https://example.com'),
fetch('https://example.com')
];
const pledged = await pledgeAllSettledTimed(promises, 20);
console.log(pledged); // [[Error("Pledge time out occurred at set time: ")], undefined]This is a helper function that will execute your promise function after a set period of time. The time unit is milliseconds. The default wait time is 0ms.
Signature
async <T>(promiseFn: () => Promise<T>) => PledgeResult<T>Usage
import { pledgeWait } from "@austinbreslin/pledge";
const promiseFn = fetch.bind(null, 'https://example.com');
const pledged = await pledgeWait(promiseFn);
console.log(pledged); // [undefined, Response]