rubico 2.11.0 → 2.12.1

package/dist/x/values.mjs

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.10.0
+ * Rubico v2.12.1
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software

package/dist/x/when.es.js

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.10.0
+ * Rubico v2.12.1
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software

package/dist/x/when.es.min.js

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.10.0
+ * Rubico v2.12.1
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software

package/dist/x/when.js

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.10.0
+ * Rubico v2.12.1
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software

package/dist/x/when.min.js

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.10.0
+ * Rubico v2.12.1
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software

package/dist/x/when.mjs

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.10.0
+ * Rubico v2.12.1
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software

package/eq.js

@@ -6,59 +6,58 @@ const equals = require('./_internal/equals')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
+ * type SyncOrAsyncResolver = (...arguments)=>Promise|any
  *
- * type SyncOrAsyncResolver = (...args)=>Promise|any
- *
- * leftValue Promise|any
- * rightValue Promise|any
- * leftResolver SyncOrAsyncResolver
- * rightResolver SyncOrAsyncResolver
- *
- * eq(leftValue, rightValue) -> Promise|boolean
- * eq(...argsOrPromises, leftResolver, rightValue) -> Promise|boolean
- * eq(...argsOrPromises, leftValue, rightResolver) -> Promise|boolean
- * eq(...argsOrPromises, leftResolver, rightResolver) -> Promise|boolean
- * eq(leftResolver, rightValue)(...args) -> Promise|boolean
- * eq(leftValue, rightResolver)(...args) -> Promise|boolean
- * eq(leftResolver, rightResolver)(...args) -> Promise|boolean
+ * eq(leftValue Promise|any, rightValue Promise|any) -> Promise|boolean
+ * eq(...arguments, leftResolver SyncOrAsyncResolver, rightValue Promise|any) -> Promise|boolean
+ * eq(...arguments, leftValue Promise|any, rightResolver SyncOrAsyncResolver) -> Promise|boolean
+ * eq(...arguments, leftResolver SyncOrAsyncResolver, rightResolver SyncOrAsyncResolver) -> Promise|boolean
  *
+ * eq(leftResolver SyncOrAsyncResolver, rightValue Promise|any)(...arguments) -> Promise|boolean
+ * eq(leftValue Promise|any, rightResolver SyncOrAsyncResolver)(...arguments) -> Promise|boolean
+ * eq(leftResolver SyncOrAsyncResolver, rightResolver SyncOrAsyncResolver)(...arguments) -> Promise|boolean
  * ```
  *
  * @description
- * Function equivalent to the [Equality (==)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality) operator. Tests for equality (`==`) between two values.
+ * Comparison operator. Tests for equality (`==`) between two values.
  *
  * ```javascript [playground]
  * const areNamesEqual = eq('Ted', 'John')
  *
- * console.log(areNamesEqual) // false
+ * console.log(areNamesEqual)
  * ```
  *
- * If either of the two values are resolver functions, `eq` returns a function that resolves the value(s) to compare.
+ * If either of the two values are resolver functions, `eq` returns a function that resolves the values to compare.
  *
  * ```javascript [playground]
  * const personIsJohn = eq(get('name'), 'John')
+ * const personLikesBananas = eq(get('likes'), 'bananas')
  *
  * const person = { name: 'John', likes: 'bananas' }
  *
- * if (personIsJohn(person)) {
- *   console.log('The person is John')
+ * if (personIsJohn(person) && personLikesBananas(person)) {
+ *   console.log('John likes bananas.')
  * }
  * ```
  *
  * If either of the two resolver functions is asynchronous, `eq` returns an asynchronous function.
  *
  * ```javascript [playground]
- * const asyncPersonIsJohn = eq(async person => person.name, 'John')
+ * const userbase = new Map()
  *
- * const person = { name: 'John', likes: 'bananas' }
+ * userbase.set('example-id', { name: 'John', likes: 'bananas' })
  *
- * asyncPersonIsJohn(person).then(condition => {
- *   if (condition) {
- *     console.log('The person is John')
+ * async function getUserNameById(id) {
+ *   const user = userbase.get(id)
+ *   if (user) {
+ *     return user.name
  *   }
- * })
+ *   return undefined
+ * }
+ *
+ * const booleanResult = await eq('example-id', getUserNameById, 'John')
+ *
+ * console.log(booleanResult)
  * ```
  *
  * `eq` supports a lazy interface for composability.
@@ -66,14 +65,14 @@ const equals = require('./_internal/equals')
  * ```javascript [playground]
  * pipe({ name: 'John' }, [
  *   eq('John', get('name')),
- *   console.log, // true
+ *   console.log,
  * ])
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * eq(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
+ * eq(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log)
  * ```
  *
  * See also:

package/es.js

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.10.0
+ * Rubico v2.12.1
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software
@@ -1474,26 +1474,64 @@ const FilteringIterator = (iterator, predicate) => ({
   },
 })
 
-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
+    },
+
+    
+    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 }
+    },
+
+  }
+}
 
 const arrayExtendMap = function (
   array, values, valuesMapper, valuesIndex,

package/every.js

@@ -51,18 +51,22 @@ const _every = function (collection, predicate) {
  * ```
  *
  * @description
- * Test a predicate concurrently across all elements of a foldable, returning true if all executions return true.
+ * Tests a predicate concurrently across all items of a foldable. Returns true if every item tests true by the predicate.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
- * console.log(
- *   every([1, 2, 3, 4, 5], isOdd),
- * ) // false
+ * {
+ *   const array = [1, 2, 3, 4, 5]
+ *   const isEveryNumberOdd = every(array, isOdd)
+ *   console.log(isEveryNumberOdd)
+ * }
  *
- * console.log(
- *   every([1, 3, 5], isOdd),
- * ) // true
+ * {
+ *   const array = [1, 3, 5]
+ *   const isEveryNumberOdd = every(array, isOdd)
+ *   console.log(isEveryNumberOdd)
+ * }
  * ```
  *
  * The following data types are considered to be foldables:
@@ -74,29 +78,19 @@ const _every = function (collection, predicate) {
  *  * `object with .reduce method`
  *  * `object`
  *
- * `every` works for async generators.
- *
- * ```javascript [playground]
- * const asyncNumbers = async function* () {
- *   yield 1; yield 2; yield 3; yield 4; yield 5
- * }
- *
- * every(asyncNumbers(), async number => number < 6).then(console.log) // true
- * ```
- *
  * `every` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe([1, 2, 3], [
  *   every(number => number < 5),
- *   console.log, // true
+ *   console.log,
  * ])
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * If the foldable is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * every(Promise.resolve([1, 2, 3, 4, 5]), n => n < 6).then(console.log) // true
+ * every(Promise.resolve([1, 2, 3, 4, 5]), n => n < 6).then(console.log)
  * ```
  *
  * See also:

package/filter.js

@@ -96,14 +96,24 @@ const _filter = function (value, predicate) {
  *   value any,
  *   indexOrKey number|string|any,
  *   filterable Filterable,
- * )=>(booleanResult Promise|boolean)
+ * )=>(booleanResult Promise|boolean|any)
  *
  * filter(filterable Promise|Filterable, predicate SyncOrAsyncPredicate) -> filteredFilterable Promise|Filterable
  * filter(predicate SyncOrAsyncPredicate)(filterable Filterable) -> filteredFilterable Promise|Filterable
  * ```
  *
  * @description
- * Filters out items from a filterable, returning a filterable of the same type. The order of the items of the filterable is preserved.
+ * Filters out items from a filterable, returning a filtered filterable of the same type. The order of the items of the filterable is preserved.
+ *
+ * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * const array = [1, 2, 3, 4, 5]
+ *
+ * const filteredArray = filter(array, isOdd)
+ *
+ * console.log(filteredArray)
+ * ```
  *
  * The following data types are considered to be filterables:
  *  * `array`
@@ -114,11 +124,11 @@ 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 item from the filterable should be included in the returned filterable.
+ * The filtering operation is defined by the predicate function, which determines whether a given item from the filterable should be included in the filtered filterable.
  *
  * ```javascript
  * const predicate = function (item) {
- *   // booleanResult is the boolean result of the predicate test on item
+ *   // booleanResult is the boolean result of the predicate
  *   return booleanResult
  * }
  * ```
@@ -150,118 +160,71 @@ const _filter = function (value, predicate) {
  * 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(item any, key string, filterable Object) -> booleanResult Promise|boolean|any
  * ```
  *
- * ```javascript [playground]
- * const isOdd = number => number % 2 == 1
- *
- * const array = [1, 2, 3, 4, 5]
- *
- * const filteredArray = filter(array, isOdd)
+ * If the filterable is an object with a `.filter` method, the predicate function signature is defined externally.
  *
- * console.log(filteredArray)
- * ```
+ * If the filterable is a generator, the predicate function must be synchronous.
  *
- * If the predicate is asynchronous, it is executed concurrently.
+ * If the predicate function is asynchronous, it is executed concurrently.
  *
  * ```javascript [playground]
  * const asyncIsOdd = async number => number % 2 == 1
  *
  * const array = [1, 2, 3, 4, 5]
  *
- * const promise = filter(array, asyncIsOdd)
- * promise.then(console.log) // [1, 3, 5]
- * ```
- *
- * `filter` applies the predicate function to just the values of an object.
- *
- * ```javascript [playground]
- * const isOdd = number => number % 2 == 1
- *
- * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+ * const result = await filter(array, asyncIsOdd)
  *
- * const result = filter(obj, isOdd)
- * console.log(result) // { a: 1, c: 3, e: 5 }
+ * console.log(result)
  * ```
  *
- * `filter` applies the predicate to the values of the entries of a map.
+ * `filter` applies the predicate function to just the values of objects and maps.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
- * const myMap = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
+ * const object = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+ * const map = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
  *
- * const result = filter(myMap, isOdd)
- * console.log(result) // Map(3) { 'a' => 1, 'c' => 3, 'e' => 5 }
- * ```
- *
- * For generators, `filter` returns a lazily filtered generator. All values that are normally yielded by the generator that test false by the predicate are excluded from the returned generator.
- *
- * ```javascript [playground]
- * const isOdd = number => number % 2 == 1
+ * const filteredObject = filter(object, isOdd)
+ * const filteredMap = filter(map, isOdd)
  *
- * const numbersGeneratorFunction = function* () {
- *   yield 1; yield 2; yield 3; yield 4; yield 5
- * }
- *
- * const numbersGenerator = numbersGeneratorFunction()
- * const oddNumbersGenerator = filter(numbersGeneratorFunction(), isOdd)
- *
- * for (const number of numbersGenerator) {
- *   console.log(number) // 1
- *                       // 2
- *                       // 3
- *                       // 4
- *                       // 5
- * }
- *
- * for (const number of oddNumbersGenerator) {
- *   console.log(number) // 1
- *                       // 3
- *                       // 5
- * }
+ * console.log(filteredObject)
+ * console.log(filteredMap)
  * ```
  *
- * For async generators, `filter` returns a lazily filtered async generator. All values that are normally yielded by the async generator that test falsy by the predicate are excluded from the returned async generator.
+ * For generators, `filter` returns a filtered generator.
  *
  * ```javascript [playground]
- * const asyncIsOdd = async number => number % 2 == 1
+ * const isOdd = number => number % 2 == 1
  *
- * const asyncNumbersGeneratorFunction = async function* () {
+ * const generateNumbers = function* () {
  *   yield 1; yield 2; yield 3; yield 4; yield 5
  * }
  *
- * const asyncNumbersGenerator = asyncNumbersGeneratorFunction()
- *
- * const asyncOddNumbersGenerator = filter(asyncNumbersGeneratorFunction(), asyncIsOdd)
+ * const numbers = generateNumbers()
+ * const oddNumbers = filter(generateNumbers(), isOdd)
  *
- * for await (const number of asyncNumbersGenerator) {
- *   console.log(number) // 1
- *                       // 2
- *                       // 3
- *                       // 4
- *                       // 5
+ * console.log('numbers')
+ * for (const number of numbers) {
+ *   console.log(number)
  * }
  *
- * for await (const number of asyncOddNumbersGenerator) {
- *   console.log(number) // 1
- *                       // 3
- *                       // 5
+ * console.log('odd numbers')
+ * for (const number of oddNumbers) {
+ *   console.log(number)
  * }
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * If the filterable is a promise, it is resolved for its value before further execution for the eager interface only. 
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
  * filter(Promise.resolve([1, 2, 3, 4, 5]), isOdd).then(console.log)
- * // [1, 3, 5]
  * ```
  *
  * See also:

package/flatMap.js

@@ -79,9 +79,17 @@ const _flatMap = function (value, flatMapper) {
  * @description
  * Applies a flat-mapper function to each item of a monad, returning a flat-mapped monad of the same type.
  *
- * A flat-mapping operation iterates through each item of a monad and applies the flat-mapper function to each item, flattening the result of the execution into the returned monad.
+ * ```javascript [playground]
+ * const duplicate = value => [value, value]
+ *
+ * const duplicated = flatMap([1, 2, 3, 4, 5], duplicate)
+ *
+ * console.log(duplicated)
+ * ```
+ *
+ * `flatMap` iterates through each item of a monad and applies the flat-mapper function to each item, concatenating the execution result (flat-mapped item) into the flat-mapped monad. If the execution result is a promise, it is resolved for its value before being concatenated into the flat-mapped monad. If the execution result is asynchronously iterable, it is muxed into the flat-mapped monad.
  *
- * If the flat-mapper is asynchronous, it is executed concurrently. The execution result may be asynchronously iterable, in which case it is muxed into the returned monad.
+ * If the flat-mapper function is asynchronous, it is executed concurrently.
  *
  * The following data types are considered to be monads:
  *  * `array`
@@ -125,15 +133,7 @@ const _flatMap = function (value, flatMapper) {
  * flatMapper(item any, key string, monad Object) -> flatMappedItem Promise|Monad|any
  * ```
  *
- * ```javascript [playground]
- * const duplicate = value => [value, value]
- *
- * const duplicated = flatMap([1, 2, 3, 4, 5], duplicate)
- *
- * console.log(duplicated)
- * ```
- *
- * If the iterable is an object with a `.flatMap` or `.chain` method, the flat-mapper function signature is defined externally.
+ * If the iterable is an object with a `flatMap` or `chain` method, the flat-mapper function signature is defined externally.
  *
  * Values from async generators are muxed. Muxing, or asynchronously "mixing", is the process of combining multiple asynchronous sources into one source, with order determined by the asynchronous resolution of the individual promise elements.
  *
@@ -153,7 +153,7 @@ const _flatMap = function (value, flatMapper) {
  * // values from async generators are muxed
  * const muxed = await flatMap(['foo', 'bar', 'baz'], asyncRepeat3)
  *
- * console.log(muxed)
+ * console.log('muxed:', muxed)
  *
  * const repeat3 = function* (message) {
  *   yield message; yield message; yield message
@@ -162,7 +162,7 @@ const _flatMap = function (value, flatMapper) {
  * // values from generators and other monads are concatenated
  * const repeated = flatMap(['foo', 'bar', 'baz'], repeat3)
  *
- * console.log(repeated)
+ * console.log('repeated:', repeated)
  * ```
  *
  * If the monad is a promise, it is resolved for its value before further execution for the eager interface only.

package/forEach.js

@@ -60,6 +60,14 @@ const _forEach = function (collection, callback) {
  * @description
  * Executes a callback function for each item of an iterable, returning the original iterable unmodified.
  *
+ * ```javascript [playground]
+ * console.log('array')
+ * forEach([1, 2, 3, 4, 5], num => console.log(num))
+ *
+ * console.log('object')
+ * forEach({ a: 1, b: 2, c: 3 }, num => console.log(num))
+ * ```
+ *
  * The following data types are considered to be iterable:
  *  * `array`
  *  * `set`
@@ -101,14 +109,6 @@ const _forEach = function (collection, callback) {
  * callback(item any, key string, iterable Object) -> Promise|undefined
  * ```
  *
- * ```javascript [playground]
- * console.log('array')
- * forEach([1, 2, 3, 4, 5], num => console.log(num))
- *
- * console.log('object')
- * forEach({ a: 1, b: 2, c: 3 }, num => console.log(num))
- * ```
- *
  * If the iterable is an object with a `.forEach` method, the callback function signature is defined externally.
  *
  * If the callback function is asynchronous, it is executed concurrently.

package/get.js

@@ -74,9 +74,9 @@ const _get = function (object, path, defaultValue) {
  * ```javascript [playground]
  * const asyncDefaultResolver = async object => object.a
  *
- * const promise = get({ a: 1 }, 'notfound', asyncDefaultResolver)
+ * const result = await get({ a: 1 }, 'notfound', asyncDefaultResolver)
  *
- * promise.then(console.log)
+ * console.log(result)
  * ```
  *
  * `get` supports three types of path patterns for nested property access.
@@ -96,7 +96,7 @@ const _get = function (object, path, defaultValue) {
  * const get00000BracketNotation = get('[0][0][0][0][0]')
  * const get00000ArrayNotation = get([0, 0, 0, 0, 0])
  *
- * const nested = [[[[['foo']]]]]
+ * const nested = [[[[[1]]]]]
  *
  * console.log(get00000DotNotation(nested))
  * console.log(get00000BracketNotation(nested))