@z22092/promise-helpers/README.md

Promise Helpers

#   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:

```shell
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
```typescript
import { promiseProxy, promiseRetry, promiseTimeout } from 'promise-helpers';
```

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

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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