rubico 2.8.5 → 2.10.0

package/es.js

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.8.5
+ * Rubico v2.10.0
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software
@@ -601,26 +601,167 @@ const MappingIterator = (iterator, mapper) => ({
   },
 })
 
-const NextIteration = value => ({ value, done: false })
+const promiseRace = Promise.race.bind(Promise)
 
-const symbolAsyncIterator = Symbol.asyncIterator
+class LinkedList {
+  constructor() {
+    this.first = null
+    this.last = null
+    this.length = 0
+  }
 
-const MappingAsyncIterator = (asyncIterator, mapper) => ({
-  [symbolAsyncIterator]() {
-    return this
-  },
-  async next() {
-    const iteration = await asyncIterator.next()
-    if (iteration.done) {
-      return iteration
+  // popFirst() -> firstValue any
+  popFirst() {
+    const first = this.first
+
+    if (first == null) {
+      return undefined
+    }
+
+    if (first.next) {
+      this.first = first.next
+    } else {
+      this.first = null
+    }
+
+    this.length -= 1
+
+    return first.value
+  }
+
+  // append(value any) -> undefined
+  append(value) {
+    const node = { value }
+    if (this.first == null) {
+      this.first = node
+    }
+
+    if (this.last == null) {
+      this.last = node
+    } else {
+      this.last.next = node
+      this.last = node
     }
-    const mapped = mapper(iteration.value)
-    return isPromise(mapped)
-      ? mapped.then(NextIteration)
-      : { value: mapped, done: false }
+
+    this.length += 1
   }
+
+}
+
+const symbolAsyncIterator = Symbol.asyncIterator
+
+const arrayPush = function (array, value) {
+  array.push(value)
+  return array
+}
+
+const sleep = time => new Promise(resolve => {
+  setTimeout(resolve, time)
 })
 
+const MappingAsyncIterator = (asyncIterator, mapper) => {
+  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 mappedItem = mapper(item)
+        buffer.append(mappedItem)
+      }
+      isAsyncIteratorDone = true
+    },
+
+    
+    async next() {
+      if (!consumingAsyncIterator) {
+        this._consumeAsyncIterator()
+        consumingAsyncIterator = true
+      }
+
+      while (!isAsyncIteratorDone) {
+        if (buffer.length > 0) {
+          let value = buffer.popFirst()
+          if (isPromise(value)) {
+            value = await value
+          }
+          return { value, done: false }
+        }
+        await sleep(10)
+      }
+
+      if (buffer.length > 0) {
+        let value = buffer.popFirst()
+        if (isPromise(value)) {
+          value = await value
+        }
+        return { value, done: false }
+      }
+
+      return { value: undefined, done: true }
+    },
+
+  }
+}
+
+const SerialMappingAsyncIterator = (asyncIterator, mapper) => {
+  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
+        let mappedItem = mapper(item)
+        if (isPromise(mappedItem)) {
+          mappedItem = await mappedItem
+        }
+        buffer.append(mappedItem)
+      }
+      isAsyncIteratorDone = true
+    },
+
+    
+    async next() {
+      if (!consumingAsyncIterator) {
+        this._consumeAsyncIterator()
+        consumingAsyncIterator = true
+      }
+
+      while (!isAsyncIteratorDone) {
+        if (buffer.length > 0) {
+          return { value: buffer.popFirst(), done: false }
+        }
+        await sleep(10)
+      }
+
+      if (buffer.length > 0) {
+        return { value: buffer.popFirst(), done: false }
+      }
+
+      return { value: undefined, done: true }
+    },
+
+  }
+}
+
 const isObject = value => {
   if (value == null) {
     return false
@@ -866,8 +1007,6 @@ const tapSync = func => function tapping(...args) {
   return args[0]
 }
 
-const promiseRace = Promise.race.bind(Promise)
-
 const arrayMapPoolAsync = async function (
   array, f, concurrencyLimit, result, index, promises,
 ) {
@@ -1073,7 +1212,7 @@ const _curryArity = (arity, func, context, args) => function curried(...curriedA
     curriedArgsIndex = -1,
     numCurriedPlaceholders = 0
 
-  while (++argsIndex < argsLength) {
+  while ((argsIndex += 1) < argsLength) {
     const arg = args[argsIndex]
     if (arg == __ && (curriedArgsIndex += 1) < curriedArgsLength) {
       const curriedArg = curriedArgs[curriedArgsIndex]
@@ -1097,7 +1236,7 @@ const _curryArity = (arity, func, context, args) => function curried(...curriedA
     }
   }
 
-  while (++curriedArgsIndex < curriedArgsLength) {
+  while ((curriedArgsIndex += 1) < curriedArgsLength) {
     const curriedArg = curriedArgs[curriedArgsIndex]
     if (curriedArg == __) {
       numCurriedPlaceholders += 1
@@ -1127,7 +1266,7 @@ const curryArity = function (arity, func, context, args) {
     return _curryArity(arity, func, context, args)
   }
   let argsIndex = -1
-  while (++argsIndex < argsLength) {
+  while ((argsIndex += 1) < argsLength) {
     const arg = args[argsIndex]
     if (arg == __) {
       return _curryArity(arity, func, context, args)
@@ -1190,9 +1329,6 @@ const _map = function (value, f) {
   if (typeof value.then == 'function') {
     return value.then(f)
   }
-  if (typeof value.map == 'function') {
-    return value.map(f)
-  }
   if (typeof value == 'string' || value.constructor == String) {
     return stringMap(value, f)
   }
@@ -1208,6 +1344,9 @@ const _map = function (value, f) {
   if (typeof value[symbolAsyncIterator] == 'function') {
     return MappingAsyncIterator(value[symbolAsyncIterator](), f)
   }
+  if (typeof value.map == 'function') {
+    return value.map(f)
+  }
   if (value.constructor == Object) {
     return objectMap(value, f)
   }
@@ -1246,27 +1385,36 @@ map.entries = function mapEntries(arg0, arg1) {
     : _mapEntries(arg0, arg1)
 }
 
-const _mapSeries = function (collection, f) {
-  if (isArray(collection)) {
-    return arrayMapSeries(collection, f)
+const _mapSeries = function (functor, f) {
+  if (isArray(functor)) {
+    return arrayMapSeries(functor, f)
   }
-  if (collection == null) {
-    throw new TypeError(`invalid collection ${collection}`)
+  if (functor == null) {
+    throw new TypeError(`invalid functor ${functor}`)
   }
 
-  if (typeof collection == 'string' || collection.constructor == String) {
-    return stringMapSeries(collection, f)
+  if (typeof functor == 'string' || functor.constructor == String) {
+    return stringMapSeries(functor, f)
   }
-  if (collection.constructor == Set) {
-    return setMapSeries(collection, f)
+  if (functor.constructor == Set) {
+    return setMapSeries(functor, f)
   }
-  if (collection.constructor == Map) {
-    return mapMapSeries(collection, f)
+  if (functor.constructor == Map) {
+    return mapMapSeries(functor, f)
   }
-  if (collection.constructor == Object) {
-    return objectMapSeries(collection, f)
+  if (typeof functor[symbolIterator] == 'function') {
+    return MappingIterator(functor[symbolIterator](), f)
   }
-  throw new TypeError(`invalid collection ${collection}`)
+  if (typeof functor[symbolAsyncIterator] == 'function') {
+    return SerialMappingAsyncIterator(functor[symbolAsyncIterator](), f)
+  }
+  if (typeof functor.map == 'function') {
+    return functor.map(f)
+  }
+  if (functor.constructor == Object) {
+    return objectMapSeries(functor, f)
+  }
+  throw new TypeError(`invalid functor ${functor}`)
 }
 
 map.series = function mapSeries(arg0, arg1) {
@@ -1483,15 +1631,15 @@ const _filter = function (value, predicate) {
   if (value.constructor == Map) {
     return mapFilter(value, predicate)
   }
-  if (typeof value.filter == 'function') {
-    return value.filter(predicate)
-  }
   if (typeof value[symbolIterator] == 'function') {
     return FilteringIterator(value[symbolIterator](), predicate)
   }
   if (typeof value[symbolAsyncIterator] == 'function') {
     return FilteringAsyncIterator(value[symbolAsyncIterator](), predicate)
   }
+  if (typeof value.filter == 'function') {
+    return value.filter(predicate)
+  }
   if (value.constructor == Object) {
     return objectFilter(value, predicate)
   }
@@ -1938,11 +2086,6 @@ const transform = function (...args) {
   return _transform(args[0], args[1], args[2])
 }
 
-const arrayPush = function (array, value) {
-  array.push(value)
-  return array
-}
-
 const FlatMappingIterator = function (iterator, flatMapper) {
   let buffer = [],
     bufferIndex = 0
@@ -1977,13 +2120,12 @@ const FlatMappingIterator = function (iterator, flatMapper) {
   }
 }
 
-const sleep = time => new Promise(resolve => {
-  setTimeout(resolve, time)
-})
-
 const FlatMappingAsyncIterator = function (asyncIterator, flatMapper) {
-  const buffer = [],
-    promises = new Set()
+  const buffer = []
+  const promises = new Set()
+
+  let consumingAsyncIterator = false
+  let isAsyncIteratorDone = false
 
   return {
     isAsyncIteratorDone: false,
@@ -1994,38 +2136,48 @@ const FlatMappingAsyncIterator = function (asyncIterator, flatMapper) {
       return '[object FlatMappingAsyncIterator]'
     },
 
-    
-    async next() {
-      while (
-        !this.isAsyncIteratorDone || buffer.length > 0 || promises.size > 0
-      ) {
-        if (!this.isAsyncIteratorDone) {
-          const { value, done } = await asyncIterator.next()
-          if (done) {
-            this.isAsyncIteratorDone = done
-          } else {
-            const monad = flatMapper(value)
-            if (isPromise(monad)) {
-              const bufferLoading =
-                monad.then(curry3(genericReduce, __, arrayPush, buffer))
-              const promise = bufferLoading.then(() => promises.delete(promise))
-              promises.add(promise)
-            } else {
-              const bufferLoading = genericReduce(monad, arrayPush, buffer)
-              if (isPromise(bufferLoading)) {
-                const promise = bufferLoading.then(() => promises.delete(promise))
-                promises.add(promise)
-              }
-            }
+    // _consumeAsyncIterator() -> Promise<>
+    async _consumeAsyncIterator() {
+      for await (const item of asyncIterator) {
+        const monad = flatMapper(item)
+        if (isPromise(monad)) {
+          const bufferLoading =
+            monad.then(curry3(genericReduce, __, arrayPush, buffer))
+          const promise = bufferLoading.then(() => promises.delete(promise))
+          promises.add(promise)
+        } else {
+          const bufferLoading = genericReduce(monad, arrayPush, buffer)
+          if (isPromise(bufferLoading)) {
+            const promise = bufferLoading.then(() => promises.delete(promise))
+            promises.add(promise)
           }
         }
+      }
+      isAsyncIteratorDone = true
+    },
+
+    
+    async next() {
+      if (!consumingAsyncIterator) {
+        this._consumeAsyncIterator()
+        consumingAsyncIterator = true
+      }
+
+      while (!isAsyncIteratorDone || promises.size > 0) {
         if (buffer.length > 0) {
           return { value: buffer.shift(), done: false }
         }
         if (promises.size > 0) {
-          await promiseRace([sleep(1000), ...promises])
+          await promiseRace(promises)
+        } else {
+          await sleep(10)
         }
       }
+
+      if (buffer.length > 0) {
+        return { value: buffer.shift(), done: false }
+      }
+
       return { value: undefined, done: true }
     },
   }
@@ -2121,9 +2273,12 @@ const objectFlatten = function (object) {
 
   for (const key in object) {
     const element = object[key]
+
     if (element == null) {
       continue
-    } else if (typeof element[symbolIterator] == 'function') {
+    }
+
+    if (typeof element[symbolIterator] == 'function') {
       for (const monadElement of element) {
         objectAssign(result, monadElement)
       }
@@ -2384,7 +2539,7 @@ const _iteratorForEachSeriesAsync = async function (iterator, callback) {
 
 const iteratorForEachSeries = function (iterator, callback) {
   let iteration = iterator.next()
-  while (!iterator.done) {
+  while (!iteration.done) {
     const operation = callback(iteration.value)
     if (isPromise(operation)) {
       return operation
@@ -2414,16 +2569,16 @@ const _forEach = function (collection, callback) {
   if (collection == null) {
     return collection
   }
-  if (typeof collection.forEach == 'function') {
-    collection.forEach(callback)
-    return collection
-  }
   if (typeof collection[symbolIterator] == 'function') {
     return iteratorForEach(collection[symbolIterator](), callback)
   }
   if (typeof collection[symbolAsyncIterator] == 'function') {
     return asyncIteratorForEach(collection[symbolAsyncIterator](), callback)
   }
+  if (typeof collection.forEach == 'function') {
+    collection.forEach(callback)
+    return collection
+  }
   if (collection.constructor == Object) {
     return objectForEach(collection, callback)
   }
@@ -3120,8 +3275,8 @@ const get = function (arg0, arg1, arg2) {
   if (typeof arg0 == 'string' || typeof arg0 == 'number' || isArray(arg0)) {
     return curry3(_get, __, arg0, arg1)
   }
-  if (isPromise(arg0)) {
-    return arg0.then(curry3(_get, __, arg1, arg2))
+  if (isPromise(arg0) || isPromise(arg2)) {
+    return promiseAll([arg0, arg1, arg2]).then(curry2(funcApply, _get, __))
   }
   return _get(arg0, arg1, arg2)
 }

package/every.js

@@ -84,7 +84,7 @@ const _every = function (collection, predicate) {
  * every(asyncNumbers(), async number => number < 6).then(console.log) // true
  * ```
  *
- * `every` supports a lazy API for composability.
+ * `every` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe([1, 2, 3], [
@@ -93,7 +93,7 @@ const _every = function (collection, predicate) {
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * every(Promise.resolve([1, 2, 3, 4, 5]), n => n < 6).then(console.log) // true

package/filter.js

@@ -70,15 +70,15 @@ const _filter = function (value, predicate) {
   if (value.constructor == Map) {
     return mapFilter(value, predicate)
   }
-  if (typeof value.filter == 'function') {
-    return value.filter(predicate)
-  }
   if (typeof value[symbolIterator] == 'function') {
     return FilteringIterator(value[symbolIterator](), predicate)
   }
   if (typeof value[symbolAsyncIterator] == 'function') {
     return FilteringAsyncIterator(value[symbolAsyncIterator](), predicate)
   }
+  if (typeof value.filter == 'function') {
+    return value.filter(predicate)
+  }
   if (value.constructor == Object) {
     return objectFilter(value, predicate)
   }
@@ -256,7 +256,7 @@ const _filter = function (value, predicate) {
  * }
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1

package/flatMap.js

@@ -20,7 +20,7 @@ const __ = require('./_internal/placeholder')
  *
  * _flatMap(
  *   m Monad,
- *   flatMapper (element any)=>Promise|Iterable,
+ *   flatMapper (item any)=>Promise|Iterable,
  * ) -> result Promise|Monad
  * ```
  */
@@ -64,66 +64,84 @@ const _flatMap = function (value, flatMapper) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Monad = Array|String|Set|Generator|AsyncGenerator|{ flatMap: string }|{ chain: string }|Object
+ * type Monad = Array|string|Set|Generator|AsyncGenerator|{ flatMap: string }|{ chain: string }|Object
  *
  * type SyncOrAsyncFlatMapper = (
- *   element any,
+ *   item any,
  *   indexOrKey number|string|any,
  *   monad Monad
- * )=>Promise|Monad|any
+ * )=>(flatMappedItem Promise|Monad|any)
  *
- * flatMapper SyncOrAsyncFlatMapper
- *
- * flatMap(monad Promise|Monad, flatMapper) -> result Promise|Monad
- * flatMap(flatMapper)(monad Monad) -> result Promise|Monad
+ * flatMap(monad Promise|Monad, flatMapper SyncOrAsyncFlatMapper) -> flatMappedMonad Promise|Monad
+ * flatMap(flatMapper SyncOrAsyncFlatMapper)(monad Monad) -> flatMappedMonad Promise|Monad
  * ```
  *
  * @description
- * Applies a flatMapper function to each element of a monad, returning a monad of the same type.
+ * Applies a flat-mapper function to each item of a monad, returning a flat-mapped monad of the same type.
  *
- * A flatMapping operation iterates through each element of a monad and applies the flatMapper function to each element, flattening the result of the execution into the returned monad.
+ * 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.
  *
- * If the flatMapper 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 is asynchronous, it is executed concurrently. The execution result may be asynchronously iterable, in which case it is muxed into the returned monad.
  *
- * The following data types are considered to be monads, all are flattenable into other monads:
+ * The following data types are considered to be monads:
  *  * `array`
  *  * `string`
  *  * `set`
- *  * `genreator`
+ *  * `generator`
  *  * `async generator`
  *  * `object with .flatMap method`
  *  * `object with .chain method`
  *  * `object`
  *
- * `flatMap` flattens various data types.
+ * The flat-mapper function signature changes depending on the provided monad.
+ *
+ * If the monad is an array:
+ * ```coffeescript [specscript]
+ * flatMapper(item any, index number, monad Array) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a string:
+ * ```coffeescript [specscript]
+ * flatMapper(character string, index number, monad string) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a set:
+ * ```coffeescript [specscript]
+ * flatMapper(item any, item any, monad set) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a generator:
+ * ```coffeescript [specscript]
+ * flatMapper(item any) -> flatMappedItem Monad|any
+ * ```
+ *
+ * If the monad is an async generator:
+ * ```coffeescript [specscript]
+ * flatMapper(item any) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a plain object:
+ * ```coffeescript [specscript]
+ * flatMapper(item any, key string, monad Object) -> flatMappedItem Promise|Monad|any
+ * ```
  *
  * ```javascript [playground]
- * const identity = value => value
- *
- * flatMap(identity)([
- *   [1, 1], // array
- *   new Set([2, 2]), // set
- *   (function* () { yield 3; yield 3 })(),
- *   (async function* () { yield 7; yield 7 })(),
- *   { a: 5, b: 5 }, // object
- *   new Uint8Array([8]), // typedArray
- * ]).then(console.log)
- * // [1, 1, 2, 3, 3, 5, 5, 8, 7, 7]
+ * 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.
+ *
  * 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.
  *
+ * For other types of monads, order is preserved from the original monad and applied to the flat-mapped items, which are then concatenated into the flat-mapped monad. The order of the items of a given flat-mapped item is determined by the structure of the flat-mapped item.
+ *
  * ```javascript [playground]
  * const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
  *
- * const repeat3 = function* (message) {
- *   yield message; yield message; yield message
- * }
- *
- * console.log( // sync is concatenated
- *   flatMap(['foo', 'bar', 'baz'], repeat3),
- * ) // ['foo', 'foo', 'foo', 'bar', 'bar', 'bar', 'baz', 'baz', 'baz']
- *
  * const asyncRepeat3 = async function* (message) {
  *   yield message
  *   await sleep(100)
@@ -133,35 +151,24 @@ const _flatMap = function (value, flatMapper) {
  * }
  *
  * // values from async generators are muxed
- * flatMap(['foo', 'bar', 'baz'], asyncRepeat3).then(console.log)
- * // ['foo', 'bar', 'baz', 'foo', 'bar', 'baz', 'foo', 'bar', 'baz']
- * ```
+ * const muxed = await flatMap(['foo', 'bar', 'baz'], asyncRepeat3)
  *
- * `flatMap` applies the flatMapper function to each element of an array, flattening the results into a new array.
+ * console.log(muxed)
  *
- * ```javascript [playground]
- * const duplicate = value => [value, value]
- *
- * console.log(
- *   flatMap([1, 2, 3, 4, 5], duplicate)
- * ) // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
- * ```
- *
- * `flatMap` acts on each character of a string.
+ * const repeat3 = function* (message) {
+ *   yield message; yield message; yield message
+ * }
  *
- * ```javascript [playground]
- * const duplicate = value => [value, value]
+ * // values from generators and other monads are concatenated
+ * const repeated = flatMap(['foo', 'bar', 'baz'], repeat3)
  *
- * console.log(
- *   flatMap('12345', duplicate)
- * ) // 1122334455
+ * console.log(repeated)
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * If the monad is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * flatMap(Promise.resolve([1, 2, 3, 4, 5]), n => [n, n]).then(console.log)
- * // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
  * ```
  *
  * See also:
@@ -179,7 +186,7 @@ const _flatMap = function (value, flatMapper) {
  * @archive
  *  * For typed arrays (type [`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#typedarray_objects)) and Node.js buffers (type [`Buffer`](https://nodejs.org/api/buffer.html)), `flatMap` applies a flatMapper function to each value of the typed array/buffer, joining the result of each execution with `.set` into the resulting typed array
  *
- *  * For Node.js duplex streams (type [Stream](https://nodejs.org/api/stream.html#class-streamduplex)), `flatMap` applies a flatMapper function to each element of the stream, writing (`.write`) each element of each execution into the duplex stream
+ *  * For Node.js duplex streams (type [Stream](https://nodejs.org/api/stream.html#class-streamduplex)), `flatMap` applies a flatMapper function to each item of the stream, writing (`.write`) each item of each execution into the duplex stream
  */
 const flatMap = (arg0, arg1) => {
   if (typeof arg0 == 'function') {