Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/rickypc/timeable-promise

Various asynchronous operations with timeout support
https://github.com/rickypc/timeable-promise
asynchronous helper promise support time timeable timeout utility wait
Last synced: about 20 hours ago
JSON representation
Various asynchronous operations with timeout support
Host: GitHub
URL: https://github.com/rickypc/timeable-promise
Owner: rickypc
License: agpl-3.0
Created: 2019-07-31T06:03:22.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2023-05-10T21:59:05.000Z (over 1 year ago)
Last Synced: 2025-01-14T11:05:40.493Z (13 days ago)
Topics: asynchronous, helper, promise, support, time, timeable, timeout, utility, wait
Language: JavaScript
Homepage: https://www.npmjs.com/package/timeable-promise
Size: 102 KB
Stars: 3
Watchers: 1
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

README

        [![Version](https://img.shields.io/npm/v/timeable-promise)](https://bit.ly/2YFweqU)

[![Downloads](https://img.shields.io/npm/dt/timeable-promise)](https://bit.ly/2YFweqU)

[![Dependency Status](https://img.shields.io/librariesio/github/rickypc/timeable-promise)](https://bit.ly/3MUJErG)

[![Code Style](https://img.shields.io/badge/code%20style-Airbnb-red)](https://bit.ly/2JYN1gk)

[![Build](https://img.shields.io/github/actions/workflow/status/rickypc/timeable-promise/validations.yml)](https://bit.ly/43aA0qF)

[![Coverage](https://img.shields.io/codecov/c/github/rickypc/timeable-promise)](https://bit.ly/2LPRiVj)

[![Vulnerability](https://img.shields.io/snyk/vulnerabilities/github/rickypc/timeable-promise)](https://bit.ly/2yP3kGa)

[![License](https://img.shields.io/npm/l/timeable-promise)](https://bit.ly/2yi7gyO)

Timeable Promise

================

Various asynchronous operations with timeout support.

Installation

-

```bash

$ yarn add timeable-promise

# or

$ npm install --save timeable-promise

```

API Reference

-

Various asynchronous operations with timeout support.

**See**: [Promise](https://mzl.la/2MQJhPC)  

**Example**  

```js

const {

  chunk,

  concurrent,

  concurrents,

  consecutive,

  consecutives,

  parallel,

  poll,

  sequential,

  sleep,

  toNumber,

  untilSettledOrTimedOut,

  waitFor,

} = require('timeable-promise');

// ---------- chunk ----------

const chunked = chunk([1, 2, 3, 4], 2);

console.log('chunked: ', chunked);

// ---------- concurrent ----------

const concurrentSettled = await concurrent([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('concurrent settled: ', concurrentSettled);

// ---------- concurrents ----------

const concurrentsSettled = await concurrents([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('concurrents settled: ', concurrentsSettled);

// ---------- consecutive ----------

const consecutiveSettled = await consecutive([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('consecutive settled: ', consecutiveSettled);

// ---------- consecutives ----------

const consecutivesSettled = await consecutives([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('consecutives settled: ', consecutivesSettled);

// ---------- parallel ----------

const parallelSettled = await parallel([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('parallel settled: ', parallelSettled);

// ---------- poll ----------

const timer = poll((stopped) => {

  // Do something promising here...

  if (!stopped()) {

    // Do something when polling is not stopped...

  }

}, 100);

setTimeout(() => {

  // Simulate the end of polling.

  timer.stop();

}, 1000);

// ---------- sequential ----------

const sequentialSettled = await sequential([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('sequential settled: ', sequentialSettled);

// ---------- sleep ----------

console.time('sleep');

// Sleep for 1s.

await sleep(1000);

console.timeEnd('sleep');

// ---------- toNumber ----------

const converted = toNumber('1');

console.log('converted: ', 1);

// ---------- untilSettledOrTimedOut ----------

const response = await untilSettledOrTimedOut((resolve, reject, pending) => {

  // Promise executor with extra `pending` param to check if promise is not

  // timed-out yet.

  if (pending()) {

    resolve(true);

  }

}, (resolve, reject) => {

  // Timeout executor with option to either resolve or reject the promise.

  reject(Error('error'));

}, 5000)

  .catch(ex => console.log('nay :(', ex));

console.log(`resolved with ${response}, yay!`);

// ---------- waitFor ----------

// Long process running...

let inflight = true

const predicate = () => !inflight;

const timeout = 5000;

setTimeout(() => {

  // Long process done.

  inflight = false;

}, 1000);

console.time('waitFor');

await waitFor(predicate, timeout);

console.timeEnd('waitFor');

```

* [timeable-promise](#module_timeable-promise)

    * [.chunk(array, [size])](#module_timeable-promise.chunk) ⇒ Array

    * [.concurrent(array, executor, [concurrency])](#module_timeable-promise.concurrent) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>

        * [~executor](#module_timeable-promise.concurrent..executor) : function

        * [~settled](#module_timeable-promise.concurrent..settled) : object

    * [.concurrents(array, executor, [concurrency])](#module_timeable-promise.concurrents) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>

    * [.consecutive(array, executor, [concurrency])](#module_timeable-promise.consecutive) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>

        * [~executor](#module_timeable-promise.consecutive..executor) : function

        * [~settled](#module_timeable-promise.consecutive..settled) : object

    * [.consecutives(array, executor, [concurrency])](#module_timeable-promise.consecutives) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>

    * [.parallel(array, executor, [concurrency])](#module_timeable-promise.parallel) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>

    * [.poll(executor, [interval], [immediately])](#module_timeable-promise.poll) ⇒ [timer](#module_timeable-promise.poll..timer)

        * [~executor](#module_timeable-promise.poll..executor) : function

        * [~timer](#module_timeable-promise.poll..timer) : object

    * [.sequential(array, executor, [concurrency])](#module_timeable-promise.sequential) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>

    * [.sleep(timeout)](#module_timeable-promise.sleep) ⇒ Promise.<void>

    * [.toNumber(value, [defaultValue])](#module_timeable-promise.toNumber) ⇒ number

    * [.untilSettledOrTimedOut(executor, timeoutExecutor, timeout)](#module_timeable-promise.untilSettledOrTimedOut) ⇒ Promise.<\*>

        * [~executor](#module_timeable-promise.untilSettledOrTimedOut..executor) : function

        * [~timeoutExecutor](#module_timeable-promise.untilSettledOrTimedOut..timeoutExecutor) : function

    * [.waitFor(predicate, timeout, [interval])](#module_timeable-promise.waitFor) ⇒ Promise.<void>



### timeable-promise.chunk(array, [size]) ⇒ Array

Splits the `array` into groups of `size`.

             The final chunk would be the remaining elements.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Array - The chunked array.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| array | Array |  | The original array. |

| [size] | number | 0 | The group size. |

**Example**  

```js

const { chunk } = require('timeable-promise');

const chunked = chunk([1, 2, 3, 4], 2);

console.log('chunked: ', chunked);

```



### timeable-promise.concurrent(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>

Run `executor` on all `array` items concurrently.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Promise.<Array.<module:timeable-promise.concurrent~settled>> - The concurrent outcome objects.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| array | Array |  | The array items to be processed by executor. |

| executor | [executor](#module_timeable-promise.concurrent..executor) |  | Executor function. |

| [concurrency] | number | 0 | The max concurrent execution. |

**Example**  

```js

const { concurrent } = require('timeable-promise');

const concurrentSettled = await concurrent([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('concurrent settled: ', concurrentSettled);

```

* [.concurrent(array, executor, [concurrency])](#module_timeable-promise.concurrent) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>

    * [~executor](#module_timeable-promise.concurrent..executor) : function

    * [~settled](#module_timeable-promise.concurrent..settled) : object



#### concurrent~executor : function

Executor function that will be executed concurrently.

**Kind**: inner typedef of [concurrent](#module_timeable-promise.concurrent)  

| Param | Type | Description |

| --- | --- | --- |

| value | \* | The current value being processed in the array. |

| index | number | The index of the current value being processed in the array. |

| array | Array | The array that is being processed concurrently. |

**Example**  

```js

const executor = (value, index, array) => {

  // Do something promising here...

};

```



#### concurrent~settled : object

Concurrent outcome object.

**Kind**: inner typedef of [concurrent](#module_timeable-promise.concurrent)  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| reason | Error | The exception object. |

| status | string | The outcome status. |

| value | \* | The outcome value. |



### timeable-promise.concurrents(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>

Run `executor` on all `array` groups concurrently.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Promise.<Array.<module:timeable-promise.concurrent~settled>> - The concurrent outcome objects.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| array | Array |  | The array groups to be processed by executor. |

| executor | [executor](#module_timeable-promise.concurrent..executor) |  | Executor function. |

| [concurrency] | number | 0 | The max concurrent execution. |

**Example**  

```js

const { concurrents } = require('timeable-promise');

const concurrentsSettled = await concurrents([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('concurrents settled: ', concurrentsSettled);

```



### timeable-promise.consecutive(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>

Run `executor` on all `array` items consecutively.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Promise.<Array.<module:timeable-promise.consecutive~settled>> - The consecutive outcome objects.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| array | Array |  | The array items to be processed by executor. |

| executor | [executor](#module_timeable-promise.consecutive..executor) |  | Executor function. |

| [concurrency] | number | 0 | The max consecutive execution. |

**Example**  

```js

const { consecutive } = require('timeable-promise');

const consecutiveSettled = await consecutive([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('consecutive settled: ', consecutiveSettled);

```

* [.consecutive(array, executor, [concurrency])](#module_timeable-promise.consecutive) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>

    * [~executor](#module_timeable-promise.consecutive..executor) : function

    * [~settled](#module_timeable-promise.consecutive..settled) : object



#### consecutive~executor : function

Executor function that will be executed consecutively.

**Kind**: inner typedef of [consecutive](#module_timeable-promise.consecutive)  

| Param | Type | Description |

| --- | --- | --- |

| value | \* | The current value being processed in the array. |

| index | number | The index of the current value being processed in the array. |

| array | Array | The array that is being processed consecutively. |

| accumulator | Array | The outcome array from previous call to this executor. |

**Example**  

```js

const executor = (value, index, array, accumulator) => {

  // Do something promising here...

};

```



#### consecutive~settled : object

Consecutive outcome object.

**Kind**: inner typedef of [consecutive](#module_timeable-promise.consecutive)  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| reason | Error | The exception object. |

| status | string | The outcome status. |

| value | \* | The outcome value. |



### timeable-promise.consecutives(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>

Run `executor` on all `array` groups consecutively.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Promise.<Array.<module:timeable-promise.consecutive~settled>> - The consecutive outcome objects.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| array | Array |  | The array groups to be processed by executor. |

| executor | [executor](#module_timeable-promise.consecutive..executor) |  | Executor function. |

| [concurrency] | number | 0 | The max consecutive execution. |

**Example**  

```js

const { consecutives } = require('timeable-promise');

const consecutivesSettled = await consecutives([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('consecutives settled: ', consecutivesSettled);

```



### timeable-promise.parallel(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>

Provide parallel execution with `concurrency` support.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Promise.<Array.<module:timeable-promise.concurrent~settled>> - The parallel outcome objects.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| array | Array |  | The array that is being processed in parallel. |

| executor | [executor](#module_timeable-promise.concurrent..executor) |  | Executor function. |

| [concurrency] | number | 0 | The max concurrent execution. |

**Example**  

```js

const { parallel } = require('timeable-promise');

const parallelSettled = await parallel([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('parallel settled: ', parallelSettled);

```



### timeable-promise.poll(executor, [interval], [immediately]) ⇒ [timer](#module_timeable-promise.poll..timer)

Provide polling support without congestion when `executor`

             takes longer than `interval`.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: [timer](#module_timeable-promise.poll..timer) - The return object with stop function.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| executor | [executor](#module_timeable-promise.poll..executor) |  | Executor function. |

| [interval] | number | 1000 | Delay interval. |

| [immediately] | boolean | false | Run executor immediately in the beginning. |

**Example**  

```js

const { poll } = require('timeable-promise');

const timer = poll((stopped) => {

  // Do something promising here...

  if (!stopped()) {

    // Do something when polling is not stopped...

  }

}, 100);

setTimeout(() => {

  // Simulate the end of polling.

  timer.stop();

}, 1000);

```

* [.poll(executor, [interval], [immediately])](#module_timeable-promise.poll) ⇒ [timer](#module_timeable-promise.poll..timer)

    * [~executor](#module_timeable-promise.poll..executor) : function

    * [~timer](#module_timeable-promise.poll..timer) : object



#### poll~executor : function

Executor function that is executed immediately by the Promise implementation.

**Kind**: inner typedef of [poll](#module_timeable-promise.poll)  

| Param | Type | Description |

| --- | --- | --- |

| stopped | function | True if polling is stopped, otherwise false. |

**Example**  

```js

const executor = (stopped) => {

  // Do something promising here...

  if (!stopped()) {

    // Do something when polling is not stopped...

  }

};

```



#### poll~timer : object

Timer object containing the polling stop function.

**Kind**: inner typedef of [poll](#module_timeable-promise.poll)  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| stop | function | The polling stop function. |



### timeable-promise.sequential(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>

Provide sequential execution with `concurrency` support.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Promise.<Array.<module:timeable-promise.consecutive~settled>> - The sequential outcome objects.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| array | Array |  | The array that is being processed in sequential. |

| executor | [executor](#module_timeable-promise.consecutive..executor) |  | Executor function. |

| [concurrency] | number | 0 | The max consecutive execution. |

**Example**  

```js

const { sequential } = require('timeable-promise');

const sequentialSettled = await sequential([...], (value, index, array) => {

  // Do something promising here...

  return value;

});

console.log('sequential settled: ', sequentialSettled);

```



### timeable-promise.sleep(timeout) ⇒ Promise.<void>

Provide sleep support.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

| Param | Type | Description |

| --- | --- | --- |

| timeout | number | Timeout. |

**Example**  

```js

const { sleep } = require('timeable-promise');

console.time('sleep');

// Sleep for 1s.

await sleep(1000);

console.timeEnd('sleep');

```



### timeable-promise.toNumber(value, [defaultValue]) ⇒ number

Converts `value` to number.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: number - The converted number.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| value | \* |  | The value to be converted to number. |

| [defaultValue] | number | 0 | The default number. |

**Example**  

```js

const { toNumber } = require('timeable-promise');

const converted = toNumber('1');

console.log('converted: ', 1);

```



### timeable-promise.untilSettledOrTimedOut(executor, timeoutExecutor, timeout) ⇒ Promise.<\*>

Provide `timeout` support on Promise object.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

**Returns**: Promise.<\*> - Resolve or reject response value.  

| Param | Type | Description |

| --- | --- | --- |

| executor | [executor](#module_timeable-promise.untilSettledOrTimedOut..executor) | Executor function. |

| timeoutExecutor | [timeoutExecutor](#module_timeable-promise.untilSettledOrTimedOut..timeoutExecutor) | Timeout executor function. |

| timeout | number | Timeout. |

**Example**  

```js

const { untilSettledOrTimedOut } = require('timeable-promise');

const executor = (resolve, reject, pending) => {

  // Do something promising here...

  if (pending()) {

    try {

      // Do something more promising here...

      resolve(true);

    } catch (ex) {

      reject(false);

    }

  }

};

const timeoutExecutor = (resolve, reject) => {

  try {

    resolve(true);

  } catch (ex) {

    reject(false);

  }

};

const timeout = 5000;

const response = await untilSettledOrTimedOut(executor, timeoutExecutor, timeout)

  .catch(ex => console.log('nay :(', ex));

console.log(`resolved with ${response}, yay!`);

```

* [.untilSettledOrTimedOut(executor, timeoutExecutor, timeout)](#module_timeable-promise.untilSettledOrTimedOut) ⇒ Promise.<\*>

    * [~executor](#module_timeable-promise.untilSettledOrTimedOut..executor) : function

    * [~timeoutExecutor](#module_timeable-promise.untilSettledOrTimedOut..timeoutExecutor) : function



#### untilSettledOrTimedOut~executor : function

Executor function that is executed immediately by the Promise implementation.

**Kind**: inner typedef of [untilSettledOrTimedOut](#module_timeable-promise.untilSettledOrTimedOut)  

| Param | Type | Description |

| --- | --- | --- |

| resolve | function | Resolve the promise. |

| reject | function | Reject the promise. |

| pending | function | True if Promise is not timed out, otherwise false. |

**Example**  

```js

const executor = (resolve, reject, pending) => {

  // Do something promising here...

  if (pending()) {

    try {

      // Do something more promising here...

      resolve(true);

    } catch (ex) {

      reject(false);

    }

  }

};

```



#### untilSettledOrTimedOut~timeoutExecutor : function

Timeout executor function that is executed when timeout is reached.

**Kind**: inner typedef of [untilSettledOrTimedOut](#module_timeable-promise.untilSettledOrTimedOut)  

| Param | Type | Description |

| --- | --- | --- |

| resolve | function | Resolve the promise. |

| reject | function | Reject the promise. |

**Example**  

```js

const timeoutExecutor = (resolve, reject) => {

  try {

    resolve(true);

  } catch (ex) {

    reject(false);

  }

};

```



### timeable-promise.waitFor(predicate, timeout, [interval]) ⇒ Promise.<void>

Provide waiting support on given `predicate`.

**Kind**: static method of [timeable-promise](#module_timeable-promise)  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| predicate | function |  | Predicate function. |

| timeout | number |  | Timeout. |

| [interval] | number | 1000 | Check interval. |

**Example**  

```js

const { waitFor } = require('timeable-promise');

// Long process running...

let inflight = true

const predicate = () => !inflight;

const timeout = 5000;

setTimeout(() => {

  // Long process done.

  inflight = false;

}, 1000);

console.time('waitFor');

await waitFor(predicate, timeout);

console.timeEnd('waitFor');

```

Development Dependencies

-

You will need to install [Node.js](https://bit.ly/2SMCGXK) as a local

development dependency. The `npm` package manager comes bundled with all

recent releases of `Node.js`. You can also use [yarn](https://bit.ly/3nmWS1K)

as a package manager.

`yarn` or `npm install` will attempt to resolve any `npm` module dependencies

that have been declared in the project’s `package.json` file, installing them

into the `node_modules` folder.

```bash

$ yarn

# or

$ npm install

```

Run Benchmark, Leak, Lint, and Unit Tests

-

To make sure we did not break anything, let's run all the tests:

```bash

$ yarn test

# or

$ npm run test:lint; npm run test:unit; npm run test:bench; npm run test:leak

```

Run benchmark tests only:

```bash

$ yarn test:bench

# or

$ npm run test:bench

```

Run leak tests only:

```bash

$ yarn test:leak

# or

$ npm run test:leak

```

Run lint tests only:

```bash

$ yarn test:lint

# or

$ npm run test:lint

```

Run unit tests only:

```bash

$ yarn test:unit

# or

$ npm run test:unit

```

Contributing

-

If you would like to contribute code to Timeable Promise repository you can do so

through GitHub by forking the repository and sending a pull request.

If you do not agree to [Contribution Agreement](CONTRIBUTING.md), do not

contribute any code to Timeable Promise repository.

When submitting code, please make every effort to follow existing conventions

and style in order to keep the code as readable as possible. Please also include

appropriate test cases.

That's it! Thank you for your contribution!

License

-

Copyright (c) 2018 - 2023 Richard Huang.

This module is free software, licensed under: [GNU Affero General Public License (AGPL-3.0)](https://bit.ly/2yi7gyO).

Documentation and other similar content are provided under [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://bit.ly/2SMCRlS).