rubico 2.10.0 → 2.11.0

package/_internal/FilteringAsyncIterator.js

@@ -1,38 +1,89 @@
+const promiseRace = require('./promiseRace')
+const __ = require('./placeholder')
+const curry2 = require('./curry2')
 const isPromise = require('./isPromise')
+const LinkedList = require('./LinkedList')
 const symbolAsyncIterator = require('./symbolAsyncIterator')
+const arrayPush = require('./arrayPush')
+const sleep = require('./sleep')
 
 /**
  * @name FilteringAsyncIterator
  *
  * @synopsis
  * ```coffeescript [specscript]
- * const filteringAsyncIterator = new FilteringAsyncIterator(
- *   asyncIterator AsyncIterator<T>,
- *   predicate T=>boolean,
- * ) -> FilteringAsyncIterator<T>
+ * filteringAsyncIterator = new FilteringAsyncIterator(
+ *   asyncIter AsyncIterator<T>,
+ *   predicate T=>Promise|boolean,
+ * ) -> filteringAsyncIterator AsyncIterator
  *
- * filteringAsyncIterator.next() -> { value: Promise, done: boolean }
+ * filteringAsyncIterator.next() -> Promise<{ value: any, done: boolean }>
  * ```
  */
-const FilteringAsyncIterator = (asyncIterator, predicate) => ({
-  isAsyncIteratorDone: false,
-  [symbolAsyncIterator]() {
-    return this
-  },
-  async next() {
-    while (!this.isAsyncIteratorDone) {
-      const { value, done } = await asyncIterator.next()
-      if (done) {
-        this.isAsyncIteratorDone = true
-      } else {
-        const predication = predicate(value)
-        if (isPromise(predication) ? await predication : predication) {
-          return { value, done: false }
+const FilteringAsyncIterator = (asyncIterator, predicate) => {
+  const buffer = new LinkedList()
+
+  let index = -1
+  let consumingAsyncIterator = false
+  let isAsyncIteratorDone = false
+
+  return {
+    [symbolAsyncIterator]() {
+      return this
+    },
+
+    // _consumeAsyncIterator() -> Promise<>
+    async _consumeAsyncIterator() {
+      for await (const item of asyncIterator) {
+        index += 1
+        const booleanResult = predicate(item)
+        buffer.append([booleanResult, item])
+      }
+      isAsyncIteratorDone = true
+    },
+
+    /**
+     * @name next
+     *
+     * @synopsis
+     * ```coffeescript [specscript]
+     * next() -> Promise<{ value, done }>
+     * ```
+     */
+    async next() {
+      if (!consumingAsyncIterator) {
+        this._consumeAsyncIterator()
+        consumingAsyncIterator = true
+      }
+
+      while (!isAsyncIteratorDone) {
+        if (buffer.length > 0) {
+          let [booleanResult, item] = buffer.popFirst()
+          if (isPromise(booleanResult)) {
+            booleanResult = await booleanResult
+          }
+          if (booleanResult) {
+            return { value: item, done: false }
+          }
+          continue
         }
+        await sleep(10)
       }
-    }
-    return { value: undefined, done: true }
-  },
-})
+
+      while (buffer.length > 0) {
+        let [booleanResult, item] = buffer.popFirst()
+        if (isPromise(booleanResult)) {
+          booleanResult = await booleanResult
+        }
+        if (booleanResult) {
+          return { value: item, done: false }
+        }
+      }
+
+      return { value: undefined, done: true }
+    },
+
+  }
+}
 
 module.exports = FilteringAsyncIterator

package/filter.js

@@ -96,14 +96,14 @@ const _filter = function (value, predicate) {
  *   value any,
  *   indexOrKey number|string|any,
  *   filterable Filterable,
- * )=>(condition Promise|boolean)
+ * )=>(booleanResult Promise|boolean)
  *
- * filter(filterable Promise|Filterable, predicate SyncOrAsyncPredicate) -> result Promise|Filterable
- * filter(predicate SyncOrAsyncPredicate)(filterable Filterable) -> result Promise|Filterable
+ * filter(filterable Promise|Filterable, predicate SyncOrAsyncPredicate) -> filteredFilterable Promise|Filterable
+ * filter(predicate SyncOrAsyncPredicate)(filterable Filterable) -> filteredFilterable Promise|Filterable
  * ```
  *
  * @description
- * Filters out elements from a filterable. Returns a filterable of the same type. The order of the elements in the filterable is preserved.
+ * Filters out items from a filterable, returning a filterable of the same type. The order of the items of the filterable is preserved.
  *
  * The following data types are considered to be filterables:
  *  * `array`
@@ -114,12 +114,12 @@ const _filter = function (value, predicate) {
  *  * `object with .filter method`
  *  * `object`
  *
- * The filtering operation is defined by a given predicate function. The predicate function dictates whether a given element from the filterable should be included in the returned filterable.
+ * The filtering operation is defined by a given predicate function. The predicate function dictates whether a given item from the filterable should be included in the returned filterable.
  *
  * ```javascript
- * const predicate = function (element) {
- *   // condition is the boolean result of the predicate test on element
- *   return condition
+ * const predicate = function (item) {
+ *   // booleanResult is the boolean result of the predicate test on item
+ *   return booleanResult
  * }
  * ```
  *
@@ -127,48 +127,47 @@ const _filter = function (value, predicate) {
  *
  * If the filterable is an array:
  * ```coffeescript [specscript]
- * predicate(element any, index number, filt Array) -> condition Promise|boolean|any
+ * predicate(item any, index number, filterable Array) -> booleanResult Promise|boolean|any
  * ```
  *
  * If the filterable is a set:
  * ```coffeescript [specscript]
- * predicate(element any, element any, filt Set) -> condition Promise|boolean|any
+ * predicate(item any, item any, filterable Set) -> booleanResult Promise|boolean|any
  * ```
  *
  * If the filterable is a map:
  * ```coffeescript [specscript]
- * predicate(element any, key any, filt Map) -> condition Promise|boolean|any
+ * predicate(item any, key any, filterable Map) -> booleanResult Promise|boolean|any
  * ```
  *
  * If the filterable is a generator:
  * ```coffeescript [specscript]
- * predicate(element any) -> condition Promise|boolean|any
+ * predicate(item any) -> booleanResult Promise|boolean|any
  * ```
  *
  * If the filterable is an async generator:
  * ```coffeescript [specscript]
- * predicate(element any) -> condition Promise|boolean|any
+ * predicate(item any) -> booleanResult Promise|boolean|any
  * ```
  *
  * If the filterable is an object with a `.filter` method, the predicate function signature is defined externally.
  *
  * If the filterable is a plain object:
  * ```coffeescript [specscript]
- * predicate(element any, key string, filt Object) -> condition Promise|boolean|any
+ * predicate(item any, key string, filterable Object) -> booleanResult Promise|boolean|any
  * ```
  *
- * `filter` works for arrays.
- *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
  * const array = [1, 2, 3, 4, 5]
  *
- * const result = filter(array, isOdd)
- * console.log(result) // [1, 3, 5]
+ * const filteredArray = filter(array, isOdd)
+ *
+ * console.log(filteredArray)
  * ```
  *
- * If the predicate is asynchronous, the returned promise is concurrently resolved for its boolean condition before continuing with the filtering operation.
+ * If the predicate is asynchronous, it is executed concurrently.
  *
  * ```javascript [playground]
  * const asyncIsOdd = async number => number % 2 == 1

package/map.js

@@ -107,7 +107,7 @@ const _map = function (value, f) {
  * ```
  *
  * @description
- * Applies a mapper function to each item of a functor, returning a mapped functor of the same type with the mapped items. The order of the elements is maintained.
+ * Applies a mapper function to each item of a functor, returning a mapped functor of the same type with the mapped items. The order of the items of the functor is preserved.
  *
  * The following data types are considered to be functors:
  *  * `array`
@@ -204,7 +204,7 @@ const _map = function (value, f) {
  * console.log(mappedMap)
  * ```
  *
- * `map` maps each value of a generator, creating a new generator with mapped elements.
+ * `map` maps each value of a generator, creating a new generator with mapped items.
  *
  * ```javascript [playground]
  * const capitalize = string => string.toUpperCase()
@@ -373,7 +373,7 @@ map.entries = function mapEntries(arg0, arg1) {
  *   value any,
  *   indexOrKey number|string|any,
  *   f Functor
- * )=>(mappedElement Promise|any)
+ * )=>(mappedItem Promise|any)
  *
  * _mapSeries(f Functor, f SyncOrAsyncMapper) -> result Promise|Functor
  * ```
@@ -421,7 +421,7 @@ const _mapSeries = function (functor, f) {
  *   value any,
  *   indexOrKey number|string|any,
  *   functor Functor,
- * )=>(mappedElement Promise|any)
+ * )=>(mappedItem Promise|any)
  *
  * map.series(
  *   functor Promise|Functor,
@@ -558,13 +558,12 @@ const _mapPool = function (f, concurrency, mapper) {
  * ]))(ids)
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * If the functor is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * const asyncSquare = async n => n ** 2
  *
  * map.pool(Promise.resolve([1, 2, 3, 4, 5]), 5, asyncSquare).then(console.log)
- * // [1, 4, 9, 16, 25]
  * ```
  *
  * See also:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "CFOSS",