promise-helpers

promise-helpers is a TypeScript library that provides several utility functions to make working with JavaScript Promises easier. It has three main methods: promiseProxy, promiseRetry, and promiseTimeout.

Installation

You can install promise-helpers using npm, yarn or bun.js:

foo@bar:~$ npm install promise-helpers
foo@bar:~$ yarn add promise-helpers
foo@bar:~$ bun add promise-helpers

You can also use the pakage with the module bundler like webpack

import { promiseProxy, promiseRetry, promiseTimeout } from 'promise-helpers';

If you're using deno, you can use it as a library

import { promiseProxy, promiseRetry, promiseTimeout } from 'https://deno.land/x/promise_helpers/mod.ts';

Usage

• promiseProxy

promiseProxy is a function that creates a "proxy" for an async function, which can be used to modify the arguments passed to the function and/or the value returned by the function.

import { promiseProxy } from 'promise-helpers';

async function exampleFunction(a: number, b: number) {
  return a + b;
}

const proxiedFunction = promiseProxy(exampleFunction);

proxiedFunction.handlerParams.addHandler(
  async (a: number, b: number) => {
    console.log('Modifying arguments:', a, b);
    return [a + 1, b + 1];
  },
  (err: Error) => { // call if error occurs
    // parser error
    throw err
  }, { // options object
    runWhen: (a: number, b: number) => {
      return a === 1
    },
    id: 10
  });

console.log(await proxiedFunction(1, 2)); // logs: 3
// console will also log: "Modifying arguments: 1 2"

• promiseRetry

promiseRetry is a function that wraps an async function and makes it automatically retry if it fails. The number of retries and the delay between retries can be configured.

import { promiseRetry } from 'promise-helpers';

async function exampleFunction() {
  if (Math.random() < 0.5)
{
throw new Error('Random failure');
}
return 'success';
}

const retriedFunction = promiseRetry(exampleFunction, { attempts: 5, delayTime: 1000 });

console.log(await retriedFunction()); // may log "success" or throw an Error, depending on the outcome of the random failures

• promiseTimeout

promiseTimeout is a function that wraps an async function and makes it automatically throw an error if it takes longer than a specified amount of time to complete.

import { promiseTimeout } from 'promise-helpers';
async function exampleFunction() {
    // This function takes longer than 200ms
    await new Promise((res) => setTimeout(res, 300))
    return 'success';
}
const timedOutFunction = promiseTimeout(exampleFunction, { ms: 200 });

try {
    console.log(await timedOutFunction());
} catch (e) {
    console.log(e); // logs "PromiseTimeoutError"
}

All these methods are useful for adding functionality and error handling to async functions, and can be used together or separately, depending on the needs of your application.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT