Added ordered param in findXXX functions and improved doc

src/everyLimit.mjs

@@ -22,7 +22,7 @@ import assert from 'nanoassert'
  *   * `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 {number | Queue} concurrencyOrQueue The maximun number of times iteratee can be called concurrently or
+ * @param {number | Queue} concurrencyOrQueue The maximum number of times iteratee can be called concurrently or
  * a queue.
  * @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

src/filterLimit.mjs

@@ -19,10 +19,8 @@ import asyncWrap from './asyncWrap.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 {number | Queue} concurrencyOrQueue The maximun number of times iteratee can be called concurrently or
+ * @param {number | Queue} concurrencyOrQueue The maximum number of times iteratee can be called concurrently or
  * a queue.
- * @param {boolean} ordered If true the results will be in the same order than the source iterable. If false
- * it will be in the order in time, depending which call to iteratee returns first.
  * @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
@@ -40,13 +38,13 @@ import asyncWrap from './asyncWrap.mjs'
  *   // total processing time should be ~ 20ms
  * })
  */
-async function filterLimit (iterable, iteratee, concurrencyOrQueue, ordered = true) {
+async function filterLimit (iterable, iteratee, concurrencyOrQueue) {
   assert(typeof iteratee === 'function', 'iteratee must be a function')
   iteratee = asyncWrap(iteratee)
   const results = []
   for await (const [value, pass] of mapGenerator(iterable, async (v, i, t) => {
     return [v, await iteratee(v, i, t)]
-  }, concurrencyOrQueue, ordered)) {
+  }, concurrencyOrQueue)) {
     if (pass) {
       results.push(value)
     }

src/find.mjs

@@ -4,9 +4,7 @@ import findLimit from './findLimit.mjs'
 /**
  * Returns the first element of an iterable that passes an asynchronous truth test.
  *
- * The calls to `iteratee` will run in parallel. Regardless of which function
- * call returns first, this function will always return the first in iterable order able to pass the truth
- * test. Concurrency has no impact on the value that will be returned by this function.
+ * The calls to `iteratee` will run in parallel.
  *
  * In case of exception in one of the `iteratee` calls the promise returned by this function will be
  * rejected with the exception. In the very specific case where a result is found and an
@@ -18,6 +16,8 @@ import findLimit from './findLimit.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 {boolean} ordered Defaults to true. 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} 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
@@ -30,11 +30,11 @@ import findLimit from './findLimit.mjs'
  *     await sleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms
  *     return v % 2 === 1
  *   })
- *   console.log(result) // will always print 1
+ *   console.log(result) // prints 1
  * })
  */
-async function find (iterable, iteratee) {
-  return findLimit(iterable, iteratee, Number.POSITIVE_INFINITY)
+async function find (iterable, iteratee, ordered = true) {
+  return findLimit(iterable, iteratee, Number.POSITIVE_INFINITY, ordered)
 }
 
 export default find

src/findIndex.mjs

@@ -4,9 +4,7 @@ import findIndexLimit from './findIndexLimit.mjs'
 /**
  * Returns the index of the first element of an iterable that passes an asynchronous truth test.
  *
- * The calls to `iteratee` will run in parallel. Regardless of which function
- * call returns first, this function will always return the first in iterable order able to pass the truth
- * test. Concurrency has no impact on the value that will be returned by this function.
+ * The calls to `iteratee` will run in parallel.
  *
  * In case of exception in one of the `iteratee` calls the promise returned by this function will be
  * rejected with the exception. In the very specific case where a result is found and an
@@ -18,6 +16,8 @@ import findIndexLimit from './findIndexLimit.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 {boolean} ordered Defaults to true. 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} 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
@@ -30,11 +30,11 @@ import findIndexLimit from './findIndexLimit.mjs'
  *     await sleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms
  *     return v % 2 === 1
  *   })
- *   console.log(result) // will always print 0
+ *   console.log(result) // prints 0
  * })
  */
-async function findIndex (iterable, iteratee) {
-  return findIndexLimit(iterable, iteratee, Number.POSITIVE_INFINITY)
+async function findIndex (iterable, iteratee, ordered = true) {
+  return findIndexLimit(iterable, iteratee, Number.POSITIVE_INFINITY, ordered)
 }
 
 export default findIndex

src/findIndexLimit.mjs

@@ -5,9 +5,7 @@ import Queue from './Queue.mjs'
 /**
  * Returns the index of the first element of an iterable that passes an asynchronous truth test.
  *
- * The calls to `iteratee` will run in parallel, up to a concurrency limit. Regardless of which function
- * call returns first, this function will always return the first in iterable order able to pass the truth
- * test. Concurrency has no impact on the value that will be returned by this function.
+ * The calls to `iteratee` will run in parallel, up to a concurrency limit.
  *
  * Whenever a result is found, all the remaining tasks will be cancelled as long
  * as they didn't started already. In case of exception in one of the iteratee calls the promise
@@ -21,8 +19,10 @@ 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 {number | Queue} concurrencyOrQueue The maximun number of times iteratee can be called concurrently or
+ * @param {number | Queue} concurrencyOrQueue The maximum number of times iteratee can be called concurrently or
  * a queue.
+ * @param {boolean} ordered Defaults to true. 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} 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
@@ -36,11 +36,11 @@ import Queue from './Queue.mjs'
  *     await sleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms
  *     return v % 2 === 1
  *   }, 3)
- *   console.log(result) // will always print 0
+ *   console.log(result) // prints 0
  * })
  */
-async function findIndexLimit (iterable, iteratee, concurrencyOrQueue) {
-  const result = (await findInternal(iterable, iteratee, concurrencyOrQueue))[0]
+async function findIndexLimit (iterable, iteratee, concurrencyOrQueue, ordered = true) {
+  const result = (await findInternal(iterable, iteratee, concurrencyOrQueue, ordered))[0]
   return result
 }
 

src/findLimit.mjs

@@ -5,10 +5,7 @@ import Queue from './Queue.mjs'
 /**
  * Returns the first element of an iterable that passes an asynchronous truth test.
  *
- * The calls to `iteratee` will run in parallel, up to a concurrency limit. This implies that
- * the element found by this function may not be the first element of the iterable able to pass the
- * truth test. It will be the first one for which one of the parallel calls to `iteratee` was able to
- * return a positive result. If you need a sequential alternative use `findSeries()`.
+ * The calls to `iteratee` will run in parallel, up to a concurrency limit.
  *
  * Whenever a result is found, all the remaining tasks will be cancelled as long
  * as they didn't started already. In case of exception in one of the `iteratee` calls the promise
@@ -22,8 +19,10 @@ 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 {number | Queue} concurrencyOrQueue The maximun number of times iteratee can be called concurrently or
+ * @param {number | Queue} concurrencyOrQueue The maximum number of times iteratee can be called concurrently or
  * a queue.
+ * @param {boolean} ordered Defaults to true. 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} 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
@@ -37,14 +36,11 @@ import Queue from './Queue.mjs'
  *     await sleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms
  *     return v % 2 === 1
  *   }, 3)
- *   console.log(result) // prints 1, 3 or 5 randomly
- *   // 5 is a potential result in this case even with a concurrency of 3 due to how
- *   // randomness works, and all asynchronous operations are inherently random. The only way to ensure an
- *   // order is to use a concurreny of 1 or to use findSeries() which does the same thing.
+ *   console.log(result) // prints 1
  * })
  */
-async function findLimit (iterable, iteratee, concurrencyOrQueue) {
-  const result = (await findInternal(iterable, iteratee, concurrencyOrQueue))[1]
+async function findLimit (iterable, iteratee, concurrencyOrQueue, ordered = true) {
+  const result = (await findInternal(iterable, iteratee, concurrencyOrQueue, ordered))[1]
   return result
 }
 

src/findSeries.mjs

@@ -7,7 +7,7 @@ import findLimit from './findLimit.mjs'
  * The calls to `iteratee` will run sequentially.
  *
  * In case of exception in one of the `iteratee` calls the promise returned by this function will be
- * rejected with the exception.
+ * rejected with the exception and the remaining pending tasks will be cancelled.
  *
  * @param {Iterable | AsyncIterable} iterable An iterable or async iterable object.
  * @param {Function} iteratee A function that will be called with each member of the iterable. It will receive

src/forEachLimit.mjs

@@ -16,7 +16,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 {number | Queue} concurrencyOrQueue The maximun number of times iteratee can be called concurrently or
+ * @param {number | Queue} concurrencyOrQueue The maximum number of times iteratee can be called concurrently or
  * a queue.
  * @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.

src/mapLimit.mjs

@@ -16,7 +16,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 {number | Queue} concurrencyOrQueue The maximun number of times iteratee can be called concurrently or
+ * @param {number | Queue} concurrencyOrQueue The maximum number of times iteratee can be called concurrently or
  * a queue.
  * @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.

src/someLimit.mjs

@@ -20,7 +20,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 {number | Queue} concurrencyOrQueue The maximun number of times iteratee can be called concurrently or
+ * @param {number | Queue} concurrencyOrQueue The maximum number of times iteratee can be called concurrently or
  * a queue.
  * @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.