rubico 2.8.5 → 2.10.0

package/README.md

@@ -2,6 +2,7 @@
 ![rubico](https://raw.githubusercontent.com/a-synchronous/assets/master/rubico-logo.png)
 > a shallow river in northeastern Italy, just south of Ravenna
 
+Source code: [GitHub](https://github.com/a-synchronous/rubico) |
 License: [CFOSS](https://cloutsworld.com/en-us/legal/license/cfoss)
 
 ![Node.js CI](https://github.com/a-synchronous/rubico/workflows/Node.js%20CI/badge.svg)
@@ -136,7 +137,7 @@ pipe(helloPromise, [ // helloPromise is resolved for 'hello'
 ])
 ```
 
-All Rubico operators support both eager and lazy APIs. The eager API takes all required arguments and executes at once, while the lazy API takes only the setup arguments and returns a function that only expects the data arguments. This dual API supports a natural and composable code style.
+All Rubico operators support both eager and lazy interfaces. The eager interface takes all required arguments and executes at once, while the lazy interface takes only the setup arguments and returns a function that only expects the data arguments. This dual interface supports a natural and composable code style.
 
 ```javascript [playground]
 const myObj = { a: 1, b: 2, c: 3 }

package/_internal/FlatMappingAsyncIterator.js

@@ -22,8 +22,11 @@ const sleep = require('./sleep')
  * @muxing
  */
 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,
@@ -34,47 +37,55 @@ const FlatMappingAsyncIterator = function (asyncIterator, flatMapper) {
       return '[object FlatMappingAsyncIterator]'
     },
 
+    // _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
+    },
+
     /**
-     * @name FlatMappingAsyncIterator.prototype.next
+     * @name next
      *
      * @synopsis
      * ```coffeescript [specscript]
-     * new FlatMappingAsyncIterator(
-     *   asyncIterator AsyncIterator, flatMapper function,
-     * ).next() -> Promise<{ value, done }>
+     * next() -> Promise<{ value, done }>
      * ```
      */
     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)
-              }
-            }
-          }
-        }
+      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 }
     },
   }

package/_internal/LinkedList.js

@@ -0,0 +1,54 @@
+/**
+ * @name LinkedList
+ *
+ * @docs
+ * ```coffeescript [specscript]
+ * new LinkedList() -> LinkedList
+ * ```
+ */
+class LinkedList {
+  constructor() {
+    this.first = null
+    this.last = null
+    this.length = 0
+  }
+
+  // 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
+    }
+
+    this.length += 1
+  }
+
+}
+
+module.exports = LinkedList

package/_internal/LinkedList.test.js

@@ -0,0 +1,34 @@
+const LinkedList = require('./LinkedList')
+const assert = require('assert')
+
+describe('LinkedList', () => {
+  it('integration', async () => {
+    const ll = new LinkedList()
+
+    assert.strictEqual(ll.popFirst(), undefined)
+
+    ll.append('value1')
+    assert.strictEqual(ll.length, 1)
+
+    assert.strictEqual(ll.popFirst(), 'value1')
+    assert.strictEqual(ll.length, 0)
+    assert.strictEqual(ll.popFirst(), undefined)
+    assert.strictEqual(ll.length, 0)
+
+    ll.append('value1')
+    assert.strictEqual(ll.length, 1)
+    ll.append('value2')
+    assert.strictEqual(ll.length, 2)
+    ll.append('value3')
+    assert.strictEqual(ll.length, 3)
+
+    assert.strictEqual(ll.popFirst(), 'value1')
+    assert.strictEqual(ll.length, 2)
+    assert.strictEqual(ll.popFirst(), 'value2')
+    assert.strictEqual(ll.length, 1)
+    assert.strictEqual(ll.popFirst(), 'value3')
+    assert.strictEqual(ll.length, 0)
+    assert.strictEqual(ll.popFirst(), undefined)
+    assert.strictEqual(ll.length, 0)
+  })
+})

package/_internal/MappingAsyncIterator.js

@@ -1,6 +1,11 @@
-const NextIteration = require('./NextIteration')
+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 MappingAsyncIterator
@@ -15,20 +20,65 @@ const symbolAsyncIterator = require('./symbolAsyncIterator')
  * mappingAsyncIterator.next() -> Promise<{ value: any, done: boolean }>
  * ```
  */
-const MappingAsyncIterator = (asyncIterator, mapper) => ({
-  [symbolAsyncIterator]() {
-    return this
-  },
-  async next() {
-    const iteration = await asyncIterator.next()
-    if (iteration.done) {
-      return iteration
-    }
-    const mapped = mapper(iteration.value)
-    return isPromise(mapped)
-      ? mapped.then(NextIteration)
-      : { value: mapped, done: false }
+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
+    },
+
+    /**
+     * @name next
+     *
+     * @synopsis
+     * ```coffeescript [specscript]
+     * next() -> Promise<{ value, done }>
+     * ```
+     */
+    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 }
+    },
+
   }
-})
+}
 
 module.exports = MappingAsyncIterator

package/_internal/SerialMappingAsyncIterator.js

@@ -0,0 +1,79 @@
+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 SerialMappingAsyncIterator
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * serialMappingAsyncIterator = new SerialMappingAsyncIterator(
+ *   asyncIter AsyncIterator<T>,
+ *   mapper T=>Promise|any,
+ * ) -> serialMappingAsyncIterator AsyncIterator
+ *
+ * serialMappingAsyncIterator.next() -> Promise<{ value: any, done: boolean }>
+ * ```
+ */
+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
+    },
+
+    /**
+     * @name next
+     *
+     * @synopsis
+     * ```coffeescript [specscript]
+     * next() -> Promise<{ value, done }>
+     * ```
+     */
+    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 }
+    },
+
+  }
+}
+
+module.exports = SerialMappingAsyncIterator

package/_internal/curryArity.js

@@ -29,7 +29,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]
@@ -53,7 +53,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
@@ -103,7 +103,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)

package/_internal/iteratorFind.js

@@ -28,7 +28,6 @@ const iteratorFindAsync = async function (iterator, predicate) {
     }
     iteration = iterator.next()
   }
-  return undefined
 }
 
 /**
@@ -57,7 +56,6 @@ const iteratorFind = function (iterator, predicate) {
     }
     iteration = iterator.next()
   }
-  return undefined
 }
 
 module.exports = iteratorFind

package/_internal/iteratorForEachSeries.js

@@ -32,7 +32,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

package/_internal/objectFlatten.js

@@ -38,9 +38,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)
       }

package/all.js

@@ -36,42 +36,34 @@ const _allValues = function (values) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
+ * type SyncOrAsyncResolver = (...arguments)=>Promise|any
+ * type ResolverOrValue = SyncOrAsyncResolver|Promise|any
  *
- * type SyncOrAsyncResolver = (...args)=>Promise|any
+ * all(Promise|Array<Promise|any>) -> Promise|Array
+ * all(...arguments, Array<ResolverOrValue>) -> Promise|Array
+ * all(Array<ResolverOrValue>)(...arguments) -> Promise|Array
  *
- * arrayResolversOrPromisesOrValues Array<SyncOrAsyncResolver|Promise|any>
- * objectResolversOrPromisesOrValues Object<SyncOrAsyncResolver|Promise|any>
- *
- * all(arrayValues Promise|Array<Promise|any>) -> arrayResult Promise|Array
- * all(...argsOrPromises, arrayResolversOrPromisesOrValues) -> arrayResult Promise|Array
- * all(arrayResolversOrPromisesOrValues)(...args) -> arrayResult Promise|Array
- *
- * all(objectValues Promise|Object<Promise|any>) -> objectResult Promise|Object
- * all(...argsOrPromises, objectResolversOrPromisesOrValues) -> objectResult Promise|Object
- * all(objectResolversOrPromisesOrValues)(...args) -> objectResult Promise|Object
+ * all(Promise|Object<Promise|any>) -> Promise|Object
+ * all(...arguments, Object<ResolverOrValue>) -> Promise|Object
+ * all(Object<ResolverOrValue>)(...arguments) -> Promise|Object
  * ```
  *
  * @description
- * Constructs an array if provided an array of resolvers, promises, values, or a mix thereof. Constructs an object if provided an object of resolvers, promises, values, or a mix thereof. If provided any resolvers, `all` returns a function that constructs the array or object. Otherwise, if none of the provided values in the array or object are functions, `all` returns the constructed array or object directly.
- *
- * `all` constructs an array from resolvers.
+ * Function composer and data constructor. Constructs an array if provided an array of resolvers, promises, or values. Constructs an object if provided an object of resolvers, promises, or values. `all` returns a constructor function if provided resolvers. Otherwise, `all` returns the constructed array or object directly.
  *
  * ```javascript [playground]
- * const createArrayOfGreetingsFor = all([
+ * const createArrayOfGreetings = all([
  *   name => `Hi ${name}`,
- *   name => `Hey ${name}`,
  *   name => `Hello ${name}`,
+ *   name => `Greetings ${name}`,
  * ])
  *
- * const arrayOfGreetingsFor1 = createArrayOfGreetingsFor('1')
+ * const arrayOfGreetings = createArrayOfGreetings('example')
  *
- * console.log(arrayOfGreetingsFor1)
- * // ['Hi 1', 'Hey 1', 'Hello 1']
+ * console.log(arrayOfGreetings)
  * ```
  *
- * If any provided values are promises, `all` returns a promise.
+ * If provided promises, `all` resolves those promises and returns a promise of the resolved values.
  *
  * ```javascript [playground]
  * const promise1 = all([
@@ -79,23 +71,25 @@ const _allValues = function (values) {
  *   Promise.resolve(2),
  *   3,
  * ])
- * promise1.then(console.log) // [1, 2, 3]
+ *
+ * promise1.then(console.log)
  *
  * const promise2 = all({
  *   a: 1,
  *   b: Promise.resolve(2),
  *   c: Promise.resolve(3),
  * })
- * promise2.then(console.log) // { a: 1, b: 2, c: 3 }
+ *
+ * promise2.then(console.log)
  * ```
  *
- * If any provided resolvers are asynchronous, `all` returns a promise. `all` can be used in a pipeline to compose and manpulate data.
+ * If any resolvers provided to `all` are asynchronous, `all` returns a promise.
  *
  * ```javascript [playground]
  * const identity = value => value
  *
  * const userbase = new Map()
- * userbase.set('1', { _id: 1, name: 'John' })
+ * userbase.set('1', { id: 1, name: 'John' })
  *
  * const getUserByID = async id => userbase.get(id)
  *
@@ -109,35 +103,17 @@ const _allValues = function (values) {
  *   }),
  * ])
  *
- * getAndLogUserById('1') // Got user {"_id":1,"name":"John"} by id 1
+ * getAndLogUserById('1')
  * ```
  *
- * Provided no resolvers, `all` returns the constructed array or object.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * all({}, {
- *   a: Promise.resolve(1),
- *   b: 2,
- *   c: () => 3,
- *   d: async () => 4,
- * }).then(console.log) // { a: 1, b: 2, c: 3, d: 4 }
- *
- * all([], [
- *   Promise.resolve(1),
- *   2,
- *   () => 3,
- *   async () => 4,
- * ]).then(console.log) // [1, 2, 3, 4]
- * ```
- *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
- *
- * ```javascript [playground]
- * all(Promise.resolve({ a: 1 }), [
- *   obj => obj.a + 1,
- *   obj => obj.a + 2,
- *   obj => obj.a + 3,
- * ]).then(console.log) // [2, 3, 4]
+ * all(Promise.resolve({ a: 1 }), Promise.resolve(2), [
+ *   (obj, n) => obj.a + n + 1,
+ *   (obj, n) => obj.a + n + 2,
+ *   (obj, n) => obj.a + n + 3,
+ * ]).then(console.log)
  * ```
  *
  * See also:
@@ -186,26 +162,24 @@ const all = function (...args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * all.series(...args, funcsArray Array<function>) -> result Promise|Array
+ * all.series(...arguments, Array<function>) -> Promise|Array
  *
- * all.series(funcsArray Array<function>)(...args) -> result Promise|Array
+ * all.series(Array<function>)(...arguments) -> Promise|Array
  * ```
  *
  * @description
- * `all` with serial execution.
+ * [all](/docs/all) with serial execution.
  *
  * ```javascript [playground]
  * const sleep = ms => () => new Promise(resolve => setTimeout(resolve, ms))
  *
- * all.series([
+ * all.series('hello', [
  *   greeting => console.log(greeting + ' world'),
  *   sleep(1000),
- *   greeting => console.log(greeting + ' mom'),
+ *   greeting => console.log(greeting + ' all'),
  *   sleep(1000),
  *   greeting => console.log(greeting + ' goodbye'),
- * ])('hello') // hello world
- *             // hello mom
- *             // hello goodbye
+ * ])
  * ```
  *
  * @execution series

package/and.js

@@ -145,7 +145,7 @@ const areAllPredicatesTruthy = function (args, predicates) {
  * console.log(condition) // true
  * ```
  *
- * 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]
  * and(Promise.resolve(5), [

package/assign.js

@@ -18,36 +18,33 @@ const _assign = function (object, funcs) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- *
  * type UnarySyncOrAsyncResolver = any=>Promise|any
  *
- * objectResolversOrPromisesOrValues Object<UnarySyncOrAsyncResolver|Promise|any>
- *
- * assign(argumentObject Promise|Object, objectResolversOrPromisesOrValues) -> resultObject
- * assign(objectResolversOrPromisesOrValues)(argumentObject Object) -> resultObject
+ * assign(Promise|Object, Object<UnarySyncOrAsyncResolver|Promise|any>) -> Promise|Object
+ * assign(Object<UnarySyncOrAsyncResolver|Promise|any>)(Object) -> Promise|Object
  * ```
  *
  * @description
- * Function equivalent to [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign). Constructs an object `result` from an object `objectResolversOrPromisesOrValues` of resolvers, promises, values, or a mix thereof and an argument object `argumentObject`.
+ * Function composer and data constructor. Constructs a new object from an argument object and an object of resolvers, promises, or values.
  *
- * If any values of `objectResolversOrPromisesOrValues` are resolvers, `assign` provides the `argumentObject` to those resolvers to resolve the values for assignment in `resultObject`.
+ * If provided resolver functions, `assign` resolves the values to be assigned at the keys of the resolver functions in the new object by calling those resolvers with the argument object.
  *
  * ```javascript [playground]
  * const assignSquaredAndCubed = assign({
  *   squared: ({ number }) => number ** 2,
  *   cubed: ({ number }) => number ** 3,
- *   n: 1,
  * })
  *
  * console.log(assignSquaredAndCubed({ number: 2 }))
- * // { number: 2, squared: 4, cubed: 8, n: 1 }
- *
  * console.log(assignSquaredAndCubed({ number: 3 }))
- * // { number: 3, squared: 9, cubed: 27, n: 1 }
+ *
+ * const n = 1
+ * const assignN = assign({ n })
+ *
+ * console.log(assignN({}))
  * ```
  *
- * If any of the resolvers in `objectResolversOrPromisesOrValues` are asynchronous, `assign` returns a promise of `resultObject`.
+ * If any of the resolvers provided to `assign` are asynchronous, the execution of `assign` with the argument object returns a promise.
  *
  * ```javascript [playground]
  * const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
@@ -59,11 +56,12 @@ const _assign = function (object, funcs) {
  *   },
  * })
  *
- * asyncAssignTotal({ numbers: [1, 2, 3, 4, 5] }).then(console.log)
- * // { numbers: [1, 2, 3, 4, 5], total: 15 }
+ * const promise = asyncAssignTotal({ numbers: [1, 2, 3, 4, 5] })
+ *
+ * promise.then(console.log)
  * ```
  *
- * 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 argument object is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * assign(Promise.resolve({}), {