diff --git a/src/asyncEvery.mjs b/src/asyncEvery.mjs index b54e15e..867d3a0 100644 --- a/src/asyncEvery.mjs +++ b/src/asyncEvery.mjs @@ -22,13 +22,27 @@ import asyncFindIndex from './asyncFindIndex.mjs' * * `value`: The current value to process * * `index`: The index in the iterable. Will start from 0. * * `iterable`: The iterable on which the operation is being performed. - * @param {Queue | number} queueOrConcurrency If a queue is specified it will be used to schedule the calls to + * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created * implicitly for the same purpose. Defaults to `1`. * @returns {Promise} A promise that will be resolved to `true` if all values pass the truth test and `false` * if a least one of them doesn't pass it. That promise will be rejected if one of the truth test throws * an exception. * @example + * // example using the default concurrency of 1 + * import { asyncEvery, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * + * const result = await asyncEvery(array, async (v) => { + * // these calls will be performed sequentially + * await asyncSleep(10) // waits 10ms + * return v > 0 + * }) + * console.log(result) // prints true + * // total processing time should be ~ 30ms + * @example + * // example using a set concurrency * import { asyncEvery, asyncSleep } from 'modern-async' * * const array = [1, 2, 3] @@ -41,6 +55,19 @@ import asyncFindIndex from './asyncFindIndex.mjs' * }, 2) * console.log(result) // prints true * // total processing time should be ~ 20ms + * @example + * // example using infinite concurrency + * import { asyncEvery, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * + * const result = await asyncEvery(array, async (v) => { + * // these calls will be performed in parallel + * await asyncSleep(10) // waits 10ms + * return v > 0 + * }, Number.POSITIVE_INFINITY) + * console.log(result) // prints true + * // total processing time should be ~ 10ms */ async function asyncEvery (iterable, iteratee, queueOrConcurrency = 1) { assert(typeof iteratee === 'function', 'iteratee must be a function') diff --git a/src/asyncFilter.mjs b/src/asyncFilter.mjs index 0e5143e..33df40a 100644 --- a/src/asyncFilter.mjs +++ b/src/asyncFilter.mjs @@ -18,12 +18,25 @@ import asyncGeneratorFilter from './asyncGeneratorFilter.mjs' * * `value`: The current value to process * * `index`: The index in the iterable. Will start from 0. * * `iterable`: The iterable on which the operation is being performed. - * @param {Queue | number} queueOrConcurrency If a queue is specified it will be used to schedule the calls to + * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created * implicitly for the same purpose. Defaults to `1`. * @returns {Promise} A promise that will be resolved with an array containing all the values that passed * the truth test. This promise will be rejected if any of the `iteratee` calls throws an exception. * @example + * // example using the default concurrency of 1 + * import { asyncFilter, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncFilter(array, async (v) => { + * // these calls will be performed sequentially + * await asyncSleep(10) // waits 10ms + * return v % 2 === 1 + * }) + * console.log(result) // prints [1, 3] + * // total processing time should be ~ 30ms + * @example + * // example using a set concurrency * import { asyncFilter, asyncSleep } from 'modern-async' * * const array = [1, 2, 3] @@ -35,6 +48,18 @@ import asyncGeneratorFilter from './asyncGeneratorFilter.mjs' * }, 2) * console.log(result) // prints [1, 3] * // total processing time should be ~ 20ms + * @example + * // example using infinite concurrency + * import { asyncFilter, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncFilter(array, async (v) => { + * // these calls will be performed in parallel + * await asyncSleep(10) // waits 10ms + * return v % 2 === 1 + * }, Number.POSITIVE_INFINITY) + * console.log(result) // prints [1, 3] + * // total processing time should be ~ 10ms */ async function asyncFilter (iterable, iteratee, queueOrConcurrency = 1) { return await asyncIterableToArray(asyncGeneratorFilter(iterable, iteratee, queueOrConcurrency)) diff --git a/src/asyncFind.mjs b/src/asyncFind.mjs index 28543ff..478325f 100644 --- a/src/asyncFind.mjs +++ b/src/asyncFind.mjs @@ -19,7 +19,7 @@ import Queue from './Queue.mjs' * * `value`: The current value to process * * `index`: The index in the iterable. Will start from 0. * * `iterable`: The iterable on which the operation is being performed. - * @param {Queue | number} queueOrConcurrency If a queue is specified it will be used to schedule the calls to + * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created * implicitly for the same purpose. Defaults to `1`. * @param {boolean} [ordered] If true this function will return on the first element in the iterable @@ -27,6 +27,18 @@ import Queue from './Queue.mjs' * @returns {Promise} A promise that will be resolved with the first found value or rejected if one of the * `iteratee` calls throws an exception before finding a value. If no value is found it will return `undefined`. * @example + * // example using the default concurrency of 1 + * import { asyncFind, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncFind(array, async (v) => { + * // these calls will be performed sequentially + * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms + * return v % 2 === 1 + * }) + * console.log(result) // prints 1 + * @example + * // example using a set concurrency * import { asyncFind, asyncSleep } from 'modern-async' * * const array = [1, 2, 3, 4, 5] @@ -36,7 +48,18 @@ import Queue from './Queue.mjs' * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms * return v % 2 === 1 * }, 3) - * console.log(result) // prints 1 + * console.log(result) // prints 1 or 3, randomly + * @example + * // example using infinite concurrency + * import { asyncFind, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncFind(array, async (v) => { + * // these calls will be performed in parallel + * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms + * return v % 2 === 1 + * }, Number.POSITIVE_INFINITY) + * console.log(result) // prints 1 or 3, randomly */ async function asyncFind (iterable, iteratee, queueOrConcurrency = 1, ordered = false) { const result = (await asyncFindInternal(iterable, iteratee, queueOrConcurrency, ordered))[1] diff --git a/src/asyncFindIndex.mjs b/src/asyncFindIndex.mjs index 6efd6a2..80da901 100644 --- a/src/asyncFindIndex.mjs +++ b/src/asyncFindIndex.mjs @@ -19,7 +19,7 @@ import Queue from './Queue.mjs' * * `value`: The current value to process * * `index`: The index in the iterable. Will start from 0. * * `iterable`: The iterable on which the operation is being performed. - * @param {Queue | number} queueOrConcurrency If a queue is specified it will be used to schedule the calls to + * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created * implicitly for the same purpose. Defaults to `1`. * @param {boolean} [ordered] If true this function will return on the first element in the iterable @@ -27,6 +27,18 @@ import Queue from './Queue.mjs' * @returns {Promise} A promise that will be resolved with the index of the first found value or rejected if one of the * `iteratee` calls throws an exception before finding a value. If no value is found it will return `-1`. * @example + * // example using the default concurrency of 1 + * import { asyncFindIndex, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncFindIndex(array, async (v) => { + * // these calls will be performed sequentially + * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms + * return v % 2 === 1 + * }) + * console.log(result) // prints 0 + * @example + * // example using a set concurrency * import { asyncFindIndex, asyncSleep } from 'modern-async' * * const array = [1, 2, 3, 4, 5] @@ -36,7 +48,18 @@ import Queue from './Queue.mjs' * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms * return v % 2 === 1 * }, 3) - * console.log(result) // prints 0 + * console.log(result) // prints 0 or 2, randomly + * @example + * // example using infinite concurrency + * import { asyncFindIndex, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncFindIndex(array, async (v) => { + * // these calls will be performed in parallel + * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms + * return v % 2 === 1 + * }, Number.POSITIVE_INFINITY) + * console.log(result) // prints 0 or 2, randomly */ async function asyncFindIndex (iterable, iteratee, queueOrConcurrency = 1, ordered = false) { const result = (await asyncFindInternal(iterable, iteratee, queueOrConcurrency, ordered))[0] diff --git a/src/asyncForEach.mjs b/src/asyncForEach.mjs index 6606c3d..67f9c07 100644 --- a/src/asyncForEach.mjs +++ b/src/asyncForEach.mjs @@ -16,12 +16,24 @@ import Queue from './Queue.mjs' * * `value`: The current value to process * * `index`: The index in the iterable. Will start from 0. * * `iterable`: The iterable on which the operation is being performed. - * @param {Queue | number} queueOrConcurrency If a queue is specified it will be used to schedule the calls to + * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created * implicitly for the same purpose. Defaults to `1`. * @returns {Promise} A promise that will be resolved when all the calls to `iteratee` have been done. * This promise will be rejected if any call to `iteratee` throws an exception. * @example + * // example using the default concurrency of 1 + * import { asyncForEach, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * await asyncForEach(array, async (v) => { + * // these calls will be performed sequentially + * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms + * console.log(v) + * }) + * // prints 1, 2 and 3 in that exact order + * @example + * // example using a set concurrency * import { asyncForEach, asyncSleep } from 'modern-async' * * const array = [1, 2, 3] @@ -33,6 +45,17 @@ import Queue from './Queue.mjs' * }, 2) * // prints 1, 2 and 3 in a random order (it will always print 1 or 2 before printing 3 due to * // the concurrency limit and the internal scheduling order) + * @example + * // example using infinite concurrency + * import { asyncForEach, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * await asyncForEach(array, async (v) => { + * // these calls will be performed in parallel + * await asyncSleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms + * console.log(v) + * }, Number.POSITIVE_INFINITY) + * // prints 1, 2 and 3 in a random order */ async function asyncForEach (iterable, iteratee, queueOrConcurrency = 1) { // eslint-disable-next-line no-unused-vars diff --git a/src/asyncMap.mjs b/src/asyncMap.mjs index 96c21e8..57e79ef 100644 --- a/src/asyncMap.mjs +++ b/src/asyncMap.mjs @@ -17,12 +17,25 @@ import asyncIterableToArray from './asyncIterableToArray.mjs' * * `value`: The current value to process * * `index`: The index in the iterable. Will start from 0. * * `iterable`: The iterable on which the operation is being performed. - * @param {Queue | number} queueOrConcurrency If a queue is specified it will be used to schedule the calls to + * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created * implicitly for the same purpose. Defaults to `1`. * @returns {Promise} A promise that will be resolved with an array containing all the mapped value, * or will be rejected if any of the calls to `iteratee` throws an exception. * @example + * // example using the default concurrency of 1 + * import { asyncMap, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncMap(array, async (v) => { + * // these calls will be performed sequentially + * await asyncSleep(10) // waits 10ms + * return v * 2 + * }, 2) + * console.log(result) // prints [2, 4, 6] + * // total processing time should be ~ 30ms + * @example + * // example using a set concurrency * import { asyncMap, asyncSleep } from 'modern-async' * * const array = [1, 2, 3] @@ -34,6 +47,18 @@ import asyncIterableToArray from './asyncIterableToArray.mjs' * }, 2) * console.log(result) // prints [2, 4, 6] * // total processing time should be ~ 20ms + * @example + * // example using infinite concurrency + * import { asyncMap, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * const result = await asyncMap(array, async (v) => { + * // these calls will be performed in parallel + * await asyncSleep(10) // waits 10ms + * return v * 2 + * }, Number.POSITIVE_INFINITY) + * console.log(result) // prints [2, 4, 6] + * // total processing time should be ~ 10ms */ async function asyncMap (iterable, iteratee, queueOrConcurrency = 1) { return await asyncIterableToArray(asyncGeneratorMap(iterable, iteratee, queueOrConcurrency)) diff --git a/src/asyncSome.mjs b/src/asyncSome.mjs index 81968fe..a6475cf 100644 --- a/src/asyncSome.mjs +++ b/src/asyncSome.mjs @@ -20,12 +20,26 @@ import Queue from './Queue.mjs' * * `value`: The current value to process * * `index`: The index in the iterable. Will start from 0. * * `iterable`: The iterable on which the operation is being performed. - * @param {Queue | number} queueOrConcurrency If a queue is specified it will be used to schedule the calls to + * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created * implicitly for the same purpose. Defaults to `1`. * @returns {Promise} A promise that will be resolved to `true` if at least one value pass the truth test and `false` * if none of them do. That promise will be rejected if one of the truth test throws an exception. * @example + * // example using the default concurrency of 1 + * import { asyncSome, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * + * const result = await asyncSome(array, async (v) => { + * // these calls will be performed sequentially + * await asyncSleep(10) // waits 10ms + * return v % 2 === 0 + * }) + * console.log(result) // prints true + * // total processing time should be ~ 30ms + * @example + * // example using a set concurrency * import { asyncSome, asyncSleep } from 'modern-async' * * const array = [1, 2, 3] @@ -37,6 +51,19 @@ import Queue from './Queue.mjs' * return v % 2 === 0 * }, 2) * console.log(result) // prints true + * // total processing time should be ~ 20ms + * @example + * // example using infinite concurrency + * import { asyncSome, asyncSleep } from 'modern-async' + * + * const array = [1, 2, 3] + * + * const result = await asyncSome(array, async (v) => { + * // these calls will be performed in parallel + * await asyncSleep(10) // waits 10ms + * return v % 2 === 0 + * }, Number.POSITIVE_INFINITY) + * console.log(result) // prints true * // total processing time should be ~ 10ms */ async function asyncSome (iterable, iteratee, queueOrConcurrency = 1) {