async/iterators.js

  1. /**
  2.  * Asynchronous tools.
  3.  *
  4.  * @module async
  5.  * @license Apache-2.0
  6.  * @copyright Mat. 2018-present
  7.  */
  9. import { head } from "../array/list";
  10. import { curry } from "../func/curry";
  11. import { inc } from "../math/arithmetic";
  12. import { isArray, isFunction } from "../type/check";
  13. import { btquote } from "../utils/misc";
  18. /**
  19.  * Asynchronous version of standard `Array.prototype.map` function.
  20.  *
  21.  * - `arr` - array to operate on
  22.  * - `f` - async or sync function with signature:
  23.  *     - `this` - bound to `arr`
  24.  *     - `element` - currently processed element
  25.  *     - `index` - current index
  26.  *
  27.  * `f` can return `Promise.<unknown>` or `<unknown>`
  28.  *
  29.  * Example:
  30.  *
  31.  * ```
  32.  * (async () => {
  33.  *     let x = await async.map(
  34.  *         array.range(10),
  35.  *         x => async.timeout(() => 4*x, 100*x)
  36.  *     )
  37.  *     console.log(x)
  38.  * })()
  39.  * ```
  40.  *
  41.  * @async
  42.  * @function map
  43.  * @param {Array} arr
  44.  * @param {Function} f
  45.  * @returns {Promise.<Array>}
  46.  */
  47. export const map = curry((arr, f) => {
  48.     const results = [];
  49.     let i = 0;
  51.     return new Promise((resolve, reject) => {
  52.         const progress = (r) => {
  53.             results.push(r);
  54.             i = inc(i);
  55.             if (i < arr.length) {
  56.                 Promise
  57.                     .resolve(f.call(arr, arr[i], i))
  58.                     .then(progress).catch(reject);
  59.             } else resolve(results);
  60.         };
  62.         if (isArray(arr)  &&  isFunction(f)) {
  63.             if (arr.length > 0) {
  64.                 Promise
  65.                     .resolve(f.call(arr, head(arr), 0))
  66.                     .then(progress).catch(reject);
  67.             } else resolve(results);
  68.         } else throw new TypeError(
  69.             "async.map() expected array and function, " +
  70.             `got ${btquote(arr)} and ${btquote(f)}`,
  71.         );
  72.     });
  73. });
  78. /**
  79.  * Asynchronous version of standard `Array.prototype.map` function.
  80.  *
  81.  * *Implementation that does paralell execution*.
  82.  *
  83.  * - `arr` - array to operate on
  84.  * - `f` - async or sync function with signature:
  85.  *     - `this` - bound to `arr`
  86.  *     - `element` - currently processed element
  87.  *     - `index` - current index
  88.  *
  89.  * `f` can return `Promise.<unknown>` or `<unknown>`
  90.  *
  91.  * Example:
  92.  *
  93.  * ```
  94.  * (async () => {
  95.  *     let x = await async.parMap(
  96.  *         array.range(10),
  97.  *         x => async.timeout(() => 4*x, 100*x)
  98.  *     )
  99.  *     console.log(x)
  100.  * })()
  101.  * ```
  102.  *
  103.  * @async
  104.  * @function parMap
  105.  * @param {Array} arr
  106.  * @param {Function} f
  107.  * @returns {Promise.<Array>}
  108.  */
  109. export const parMap = curry((arr, f) =>
  110.     Promise.all(arr.map((el, i) => Promise.resolve(f.call(arr, el, i)))),
  111. );
  116. /**
  117.  * Asynchronous version of standard `Array.prototype.reduce` function.
  118.  *
  119.  * - `arr` - array to operate on
  120.  * - `f` - async or sync function with signature:
  121.  *     - `this` - bound to `arr`
  122.  *     - `acc` - accumulates the `f`'s return values; it is
  123.  *         the accumulated value previously returned
  124.  *         in the last invocation of `f`, or `initAcc`, if supplied.
  125.  *     - `element` - currently processed element
  126.  *     - `index` - current index
  127.  * - `initAcc` - value to use as the first argument to the first call
  128.  *     of the `f`. If no initial value is supplied, the first element
  129.  *     in the array will be used.
  130.  *
  131.  * `f` can return `Promise.<unknown>` or `<unknown>`
  132.  *
  133.  * Example:
  134.  *
  135.  * ```
  136.  * (async () => {
  137.  *     let x = await async.reduce(
  138.  *         array.range(10),
  139.  *         (acc, x) => async.timeout(() => acc+x, 100*x),
  140.  *         0
  141.  *     )
  142.  *     console.log(x)
  143.  * })()
  144.  * ```
  145.  *
  146.  * @async
  147.  * @function reduce
  148.  * @param {Array} arr
  149.  * @param {Function} f
  150.  * @param {unknown} [initAcc]
  151.  * @returns {Promise.<unknown>}
  152.  */
  153. export const reduce = curry((arr, f, initAcc) => {
  154.     let i = 0;
  156.     return new Promise((resolve, reject) => {
  157.         const progress = r => {
  158.             i = inc(i);
  159.             if (i < arr.length) {
  160.                 Promise
  161.                     .resolve(f.call(arr, r, arr[i], i))
  162.                     .then(progress).catch(reject);
  163.             } else resolve(r);
  164.         };
  166.         if (isArray(arr)  &&  isFunction(f)) {
  167.             if (arr.length > 0) {
  168.                 Promise
  169.                     .resolve(f.call(arr, initAcc ?? head(arr), head(arr), 0))
  170.                     .then(progress).catch(reject);
  171.             } else resolve(initAcc);
  172.         } else throw new TypeError(
  173.             "async.reduce() expected array and function, " +
  174.             `got ${btquote(arr)} and ${btquote(f)}`,
  175.         );
  176.     });
  177. });