Added back documentation

Author: nicolas-van

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<boolean>} 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')

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<any[]>} 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))

src/asyncFind.mjs

@@ -19,14 +19,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`.
  * @param {boolean} [ordered] If true this function will return on the first element in the iterable
  * order for which `iteratee` returned true. If false it will be the first in time.
  * @returns {Promise<any | undefined>} 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]

src/asyncFindIndex.mjs

@@ -19,14 +19,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`.
  * @param {boolean} [ordered] If true this function will return on the first element in the iterable
  * order for which `iteratee` returned true. If false it will be the first in time.
  * @returns {Promise<number>} 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]

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

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<any[]>} 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))

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<boolean>} 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) {