Timeable Promise

Various asynchronous operations with timeout support.

Installation

$ yarn add timeable-promise
# or
$ npm install --save timeable-promise

API Reference

Various asynchronous operations with timeout support.

See: Promise
Example

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
  • .chunk(array, [size]) ⇒ Array
  • .concurrent(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>
    • ~executor : function
    • ~settled : object
  • .concurrents(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>
  • .consecutive(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>
    • ~executor : function
    • ~settled : object
  • .consecutives(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>
  • .parallel(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>
  • .poll(executor, [interval], [immediately]) ⇒ timer
    • ~executor : function
    • ~timer : object
  • .sequential(array, executor, [concurrency]) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>
  • .sleep(timeout) ⇒ Promise.<void>
  • .toNumber(value, [defaultValue]) ⇒ number
  • .untilSettledOrTimedOut(executor, timeoutExecutor, timeout) ⇒ Promise.<*>
    • ~executor : function
    • ~timeoutExecutor : function
  • .waitFor(predicate, timeout, [interval]) ⇒ 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
Returns: Array - The chunked array.

| Param | Type | Default | Description | | --- | --- | --- | --- | | array | Array | | The original array. | | [size] | number | 0 | The group size. |

Example

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
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 | | Executor function. | | [concurrency] | number | 0 | The max concurrent execution. |

Example

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]) ⇒ Promise.<Array.<module:timeable-promise.concurrent~settled>>
  • ~executor : function
  • ~settled : object

concurrent~executor : function

Executor function that will be executed concurrently.

Kind: inner typedef of 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

const executor = (value, index, array) => {
  // Do something promising here...
};

concurrent~settled : object

Concurrent outcome object.

Kind: inner typedef of 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
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 | | Executor function. | | [concurrency] | number | 0 | The max concurrent execution. |

Example

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
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 | | Executor function. | | [concurrency] | number | 0 | The max consecutive execution. |

Example

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]) ⇒ Promise.<Array.<module:timeable-promise.consecutive~settled>>
  • ~executor : function
  • ~settled : object

consecutive~executor : function

Executor function that will be executed consecutively.

Kind: inner typedef of 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

const executor = (value, index, array, accumulator) => {
  // Do something promising here...
};

consecutive~settled : object

Consecutive outcome object.

Kind: inner typedef of 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
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 | | Executor function. | | [concurrency] | number | 0 | The max consecutive execution. |

Example

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
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 | | Executor function. | | [concurrency] | number | 0 | The max concurrent execution. |

Example

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

Provide polling support without congestion when executor takes longer than interval.

Kind: static method of timeable-promise
Returns: timer - The return object with stop function.

| Param | Type | Default | Description | | --- | --- | --- | --- | | executor | executor | | Executor function. | | [interval] | number | 1000 | Delay interval. | | [immediately] | boolean | false | Run executor immediately in the beginning. |

Example

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]) ⇒ timer
  • ~executor : function
  • ~timer : object

poll~executor : function

Executor function that is executed immediately by the Promise implementation.

Kind: inner typedef of poll

| Param | Type | Description | | --- | --- | --- | | stopped | function | True if polling is stopped, otherwise false. |

Example

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
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
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 | | Executor function. | | [concurrency] | number | 0 | The max consecutive execution. |

Example

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

| Param | Type | Description | | --- | --- | --- | | timeout | number | Timeout. |

Example

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
Returns: number - The converted number.

| Param | Type | Default | Description | | --- | --- | --- | --- | | value | * | | The value to be converted to number. | | [defaultValue] | number | 0 | The default number. |

Example

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
Returns: Promise.<*> - Resolve or reject response value.

| Param | Type | Description | | --- | --- | --- | | executor | executor | Executor function. | | timeoutExecutor | timeoutExecutor | Timeout executor function. | | timeout | number | Timeout. |

Example

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) ⇒ Promise.<*>
  • ~executor : function
  • ~timeoutExecutor : function

untilSettledOrTimedOut~executor : function

Executor function that is executed immediately by the Promise implementation.

Kind: inner typedef of 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

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

| Param | Type | Description | | --- | --- | --- | | resolve | function | Resolve the promise. | | reject | function | Reject the promise. |

Example

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | predicate | function | | Predicate function. | | timeout | number | | Timeout. | | [interval] | number | 1000 | Check interval. |

Example

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 as a local development dependency. The npm package manager comes bundled with all recent releases of Node.js. You can also use yarn 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.

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

$ yarn test
# or
$ npm run test:lint; npm run test:unit; npm run test:bench; npm run test:leak

Run benchmark tests only:

$ yarn test:bench
# or
$ npm run test:bench

Run leak tests only:

$ yarn test:leak
# or
$ npm run test:leak

Run lint tests only:

$ yarn test:lint
# or
$ npm run test:lint

Run unit tests only:

$ 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, 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).

Documentation and other similar content are provided under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.