npm package: @livechat/promise-utils
Description: Collection of promise utility functions
Latest version: 1.0.1

## Functions

<dl>
<dt><a href="#promiseRetry">promiseRetry(promiseFactory, options)</a> ⇒</dt>
<dd><p>Retries promise factory until it resolves or maximum retries count is reached</p>
</dd>
<dt><a href="#promiseTry">promiseTry(anyFunction)</a> ⇒</dt>
<dd><p>promiseTry allows us to move success / error handling to be promise based so we will handle both synchronous and asynchronous execution failures and success properly.</p>
</dd>
<dt><a href="#promiseQueue">promiseQueue()</a> ⇒</dt>
<dd><p>promiseQueue is a function that returns an object with two methods: add and flush.
add takes a function that will be added to the queue and returns a promise that resolves to the function&#39;s return value when it is called and executed in order of addition to the queue.
flush takes an error and rejects all pending promises with that error.</p>
</dd>
<dt><a href="#promiseDeferred">promiseDeferred()</a> ⇒</dt>
<dd><p>Creates a deferred object that can be resolved or rejected later.</p>
</dd>
<dt><a href="#promiseTimeoutController">promiseTimeoutController()</a> ⇒</dt>
<dd><p>promiseTimeoutController is a function that returns an object with two properties: racePromiseWithTimeout and signal.
The main function, racePromiseWithTimeout, takes a promise and a timeout duration as parameters.
It returns a promise that races the original promise with a timeout.
If the original promise resolves or rejects before the timeout, the timeout is aborted.
If the timeout occurs before the original promise completes, the request is aborted.
The function also exposes the signal from the requestAbortController for external use.</p>
</dd>
</dl>

<a name="promiseRetry"></a>

## promiseRetry(promiseFactory, options) ⇒

Retries promise factory until it resolves or maximum retries count is reached

**Kind**: global function  
**Returns**: promise that resolves when promiseFactory resolves or rejects when maximum retries count is reached

| Param                | Description                                  |
| -------------------- | -------------------------------------------- |
| promiseFactory       | function that returns a promise              |
| options              | options object                               |
| options.retriesCount | maximum retries count, default: Infinity     |
| options.minTime      | minimum time between retries, default: 100   |
| options.maxTime      | maximum time between retries, default: 10000 |

**Example**

```js
const promise = promiseRetry(() => fetch('https://example.com'), {
  retriesCount: 3,
})
promise
  .then(response => console.log(response))
  .catch(error => console.log(error))
```

<a name="promiseTry"></a>

## promiseTry(anyFunction) ⇒

promiseTry allows us to move success / error handling to be promise based so we will handle both synchronous and asynchronous execution failures and success properly.

**Kind**: global function  
**Returns**: promise that resolves to the return value of the function

| Param       | Description           |
| ----------- | --------------------- |
| anyFunction | function to be called |

**Example**

```js
const promise = promiseTry(() => 1)
promise.then(value => console.log(value)) // 1
```

<a name="promiseQueue"></a>

## promiseQueue() ⇒

promiseQueue is a function that returns an object with two methods: add and flush.
add takes a function that will be added to the queue and returns a promise that resolves to the function's return value when it is called and executed in order of addition to the queue.
flush takes an error and rejects all pending promises with that error.

**Kind**: global function  
**Returns**: object with add and flush methods  
**Example**

```js
const queue = promiseQueue()
const promise1 = queue.add(() => 1)
const promise2 = queue.add(() => 2)
promise1.then(value => console.log(value)) // 1
promise2.then(value => console.log(value)) // 2
```

<a name="promiseDeferred"></a>

## promiseDeferred() ⇒

Creates a deferred object that can be resolved or rejected later.

**Kind**: global function  
**Returns**: A deferred object with a promise and resolve and reject functions.  
**Example**

```js
const def = promiseDeferred()
const promise = def.promise
def.resolve(1)
return promise.then(res => console.log(res)) // 1
```

<a name="promiseTimeoutController"></a>

## promiseTimeoutController() ⇒

promiseTimeoutController is a function that returns an object with two properties: racePromiseWithTimeout and signal.
The main function, racePromiseWithTimeout, takes a promise and a timeout duration as parameters.
It returns a promise that races the original promise with a timeout.
If the original promise resolves or rejects before the timeout, the timeout is aborted.
If the timeout occurs before the original promise completes, the request is aborted.
The function also exposes the signal from the requestAbortController for external use.

**Kind**: global function  
**Returns**: object with racePromiseWithTimeout and signal properties  
**Example**

```js
const { racePromiseWithTimeout, signal } = promiseTimeoutController()
const promise = fetch('https://example.com', { signal })
const result = await racePromiseWithTimeout(promise, 1000)
```