rubico 2.4.2 → 2.6.0

package/README.md

@@ -265,3 +265,6 @@ rubico is [MIT Licensed](https://github.com/a-synchronous/rubico/blob/master/LIC
 [Practical Functional Programming in JavaScript - Techniques for Composing Data](https://dev.to/richytong/practical-functional-programming-in-javascript-techniques-for-composing-data-c39)
 <br>
 [Practical Functional Programming in JavaScript - Error Handling](https://dev.to/richytong/practical-functional-programming-in-javascript-error-handling-8g5)
+
+# Blog
+Check out the rubico blog at [https://rubico.land/blog](https://rubico.land/blog)

package/_internal/arrayMapPool.js

@@ -11,27 +11,26 @@ const promiseRace = require('./promiseRace')
  * arrayMapPoolAsync<
  *   T any,
  *   array Array<T>,
- *   mapper T=>Promise|any,
+ *   f T=>Promise|any,
  *   concurrencyLimit number,
  *   result Array,
  *   index number,
  *   promises Set<Promise>,
- * >(array, mapper, concurrencyLimit, result, index, promises) -> result
+ * >(array, f, concurrencyLimit, result, index, promises) -> result
  * ```
  *
  * @description
- * Apply a mapper with limited concurrency to each item of an array, returning a Promise of an array of results.
+ * Apply a function `f` with limited concurrency to each item of an array, returning a Promise of an array of results.
  */
 const arrayMapPoolAsync = async function (
-  array, mapper, concurrencyLimit, result, index, promises,
+  array, f, concurrencyLimit, result, index, promises,
 ) {
   const arrayLength = array.length
   while (++index < arrayLength) {
     if (promises.size >= concurrencyLimit) {
       await promiseRace(promises)
     }
-
-    const resultItem = mapper(array[index])
+    const resultItem = f(array[index])
     if (isPromise(resultItem)) {
       const selfDeletingPromise = resultItem.then(
         tapSync(() => promises.delete(selfDeletingPromise)))
@@ -45,29 +44,22 @@ const arrayMapPoolAsync = async function (
 }
 
 /**
- * @name
- * arrayMapPool
+ * @name arrayMapPool
  *
  * @synopsis
  * ```coffeescript [specscript]
- * arrayMapPool<
- *   T any,
- *   array Array<T>
- *   mapper T=>Promise|any,
- *   concurrentLimit number,
- * >(array, mapper, concurrentLimit) -> Promise|Array
+ * arrayMapPool(array Array, concurrency number, f function) -> Promise|string
  * ```
  *
  * @description
- * Apply a mapper with limited concurrency to each item of an array, returning an array of results.
+ * Apply a function `f` with limited concurrency to each item of an array, returning an array of results.
  */
-const arrayMapPool = function (array, mapper, concurrentLimit) {
+const arrayMapPool = function (array, concurrency, f) {
   const arrayLength = array.length,
     result = Array(arrayLength)
   let index = -1
   while (++index < arrayLength) {
-
-    const resultItem = mapper(array[index])
+    const resultItem = f(array[index])
     if (isPromise(resultItem)) {
       const promises = new Set(),
         selfDeletingPromise = resultItem.then(
@@ -75,7 +67,7 @@ const arrayMapPool = function (array, mapper, concurrentLimit) {
       promises.add(selfDeletingPromise)
       result[index] = selfDeletingPromise
       return arrayMapPoolAsync(
-        array, mapper, concurrentLimit, result, index, promises)
+        array, f, concurrency, result, index, promises)
     }
     result[index] = resultItem
   }

package/_internal/mapMapPool.js

@@ -0,0 +1,80 @@
+const isPromise = require('./isPromise')
+const promiseRace = require('./promiseRace')
+const promiseAll = require('./promiseAll')
+const symbolIterator = require('./symbolIterator')
+
+/**
+ * @name _mapMapPoolAsync
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * _mapMapPoolAsync(
+ *   m Map,
+ *   iterator Iterator,
+ *   concurrency number,
+ *   f function,
+ *   result Map,
+ *   promises Set,
+ * ) -> Promise<Map>
+ * ```
+ */
+const _mapMapPoolAsync = async function (
+  m, iterator, concurrency, f, result, promises,
+) {
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    if (promises.size >= concurrency) {
+      await promiseRace(promises)
+    }
+    const key = iteration.value[0]
+    const resultItem = f(iteration.value[1], key, m)
+    if (isPromise(resultItem)) {
+      result.set(key, resultItem)
+      const selfDeletingPromise = resultItem.then(resolvedValue => {
+        promises.delete(selfDeletingPromise)
+        result.set(key, resolvedValue)
+      })
+      promises.add(selfDeletingPromise)
+    } else {
+      result.set(key, resultItem)
+    }
+    iteration = iterator.next()
+  }
+  if (promises.size > 0) {
+    await promiseAll(promises)
+  }
+  return result
+}
+
+/**
+ * @name mapMapPool
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * mapMapPool(m Map, concurrency number, f function) -> Promise|Map
+ * ```
+ */
+const mapMapPool = function (m, concurrency, f) {
+  const result = new Map()
+  const iterator = m[symbolIterator]()
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    const key = iteration.value[0]
+    const resultItem = f(iteration.value[1], key, m)
+    if (isPromise(resultItem)) {
+      const promises = new Set()
+      result.set(key, resultItem)
+      const selfDeletingPromise = resultItem.then(resolvedValue => {
+        promises.delete(selfDeletingPromise)
+        result.set(key, resolvedValue)
+      })
+      promises.add(selfDeletingPromise)
+      return _mapMapPoolAsync(m, iterator, concurrency, f, result, promises)
+    }
+    result.set(key, resultItem)
+    iteration = iterator.next()
+  }
+  return result
+}
+
+module.exports = mapMapPool

package/_internal/mapMapSeries.js

@@ -0,0 +1,62 @@
+const isPromise = require('./isPromise')
+const curry3 = require('./curry3')
+const thunkify3 = require('./thunkify3')
+const mapSet = require('./mapSet')
+const funcConcat = require('./funcConcat')
+const symbolIterator = require('./symbolIterator')
+
+// _mapMapSeriesAsync(
+//   iterator Iterator,
+//   f function,
+//   result Map,
+// ) -> Promise<Map>
+const _mapMapSeriesAsync = async function (iterator, f, result) {
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    let resultItem = f(iteration.value[1])
+    if (isPromise(resultItem)) {
+      resultItem = await resultItem
+    }
+    result.set(iteration.value[0], resultItem)
+    iteration = iterator.next()
+  }
+  return result
+}
+
+/**
+ * @name mapMapSeries
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type MapMapper = (
+ *   value any,
+ *   key any,
+ *   map Map
+ * )=>(resultItem Promise|any)
+ *
+ * mapMapSeries(map Map, f MapMapper) -> Promise|Map
+ * ```
+ *
+ * @description
+ * Apply a mapper in series to each value of a Map, returning a new Map of mapped items. Mapper may be asynchronous.
+ */
+const mapMapSeries = function (map, f) {
+  const result = new Map()
+  const iterator = map[symbolIterator]()
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    const key = iteration.value[0]
+    const resultItem = f(iteration.value[1])
+    if (isPromise(resultItem)) {
+      return resultItem.then(funcConcat(
+        curry3(mapSet, result, key, __),
+        thunkify3(_mapMapSeriesAsync, iterator, f, result),
+      ))
+    }
+    result.set(key, resultItem)
+    iteration = iterator.next()
+  }
+  return result
+}
+
+module.exports = mapMapSeries

package/_internal/objectForEachSeries.js

@@ -4,11 +4,11 @@ const thunkify3 = require('./thunkify3')
 // _objectForEachSeriesAsync(
 //   object Object,
 //   callback function,
-//   firstKey string
+//   doneKeys Object,
 // ) -> Promise<object>
-const _objectForEachSeriesAsync = async function (object, callback, firstKey) {
+const _objectForEachSeriesAsync = async function (object, callback, doneKeys) {
   for (const key in object) {
-    if (key == firstKey) {
+    if (key in doneKeys) {
       continue
     }
     const operation = callback(object[key])
@@ -31,11 +31,13 @@ const _objectForEachSeriesAsync = async function (object, callback, firstKey) {
  * Execute a callback for each value of an object. Return a promise if any executions are asynchronous.
  */
 const objectForEachSeries = function (object, callback) {
+  const doneKeys = {}
   for (const key in object) {
+    doneKeys[key] = true
     const operation = callback(object[key])
     if (isPromise(operation)) {
       return operation
-        .then(thunkify3(_objectForEachSeriesAsync, object, callback, key))
+        .then(thunkify3(_objectForEachSeriesAsync, object, callback, doneKeys))
     }
   }
   return object

package/_internal/objectMapPool.js

@@ -0,0 +1,77 @@
+const isPromise = require('./isPromise')
+const promiseRace = require('./promiseRace')
+const promiseAll = require('./promiseAll')
+
+/**
+ * @name _objectMapPoolAsync
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * _objectMapPoolAsync(
+ *   o Object,
+ *   concurrency number,
+ *   f function,
+ *   result Object,
+ *   doneKeys Object,
+ *   promises Set,
+ * ) -> result Promise|Object
+ * ```
+ */
+const _objectMapPoolAsync = async function (
+  o, concurrency, f, result, doneKeys, promises,
+) {
+  for (const key in o) {
+    if (key in doneKeys) {
+      continue
+    }
+    if (promises.size >= concurrency) {
+      await promiseRace(promises)
+    }
+    const resultItem = f(o[key], key, o)
+    if (isPromise(resultItem)) {
+      result[key] = resultItem
+      const selfDeletingPromise = resultItem.then(resolvedValue => {
+        promises.delete(selfDeletingPromise)
+        result[key] = resolvedValue
+      })
+      promises.add(selfDeletingPromise)
+    } else {
+      result[key] = resultItem
+    }
+  }
+  if (promises.size > 0) {
+    await promiseAll(promises)
+  }
+  return result
+}
+
+/**
+ * @name objectMapPool
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * objectMapPool(o Object, concurrency number, f function) -> Promise|Object
+ * ```
+ */
+const objectMapPool = function (o, concurrency, f) {
+  const result = {}
+  const doneKeys = {}
+  for (const key in o) {
+    doneKeys[key] = true
+    const resultItem = f(o[key], key, o)
+    if (isPromise(resultItem)) {
+      const promises = new Set()
+      result[key] = resultItem
+      const selfDeletingPromise = resultItem.then(resolvedValue => {
+        promises.delete(selfDeletingPromise)
+        result[key] = resolvedValue
+      })
+      promises.add(selfDeletingPromise)
+      return _objectMapPoolAsync(o, concurrency, f, result, doneKeys, promises)
+    }
+    result[key] = resultItem
+  }
+  return result
+}
+
+module.exports = objectMapPool

package/_internal/objectMapSeries.js

@@ -0,0 +1,62 @@
+const isPromise = require('./isPromise')
+const curry3 = require('./curry3')
+const thunkify4 = require('./thunkify4')
+const objectSet = require('./objectSet')
+const funcConcat = require('./funcConcat')
+const symbolIterator = require('./symbolIterator')
+
+// _objectMapSeriesAsync(
+//   object Object,
+//   f function,
+//   result Object,
+//   doneKeys Object
+// ) -> Promise<object>
+const _objectMapSeriesAsync = async function (object, f, result, doneKeys) {
+  for (const key in object) {
+    if (key in doneKeys) {
+      continue
+    }
+    let resultItem = f(object[key])
+    if (isPromise(resultItem)) {
+      resultItem = await resultItem
+    }
+    result[key] = resultItem
+  }
+  return result
+}
+
+/**
+ * @name objectMapSeries
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type ObjectMapper = (
+ *   value any,
+ *   key string,
+ *   collection Object
+ * )=>(resultItem Promise|any)
+ *
+ * objectMapSeries(object Object, f ObjectMapper) -> Promise|Object
+ * ```
+ *
+ * @description
+ * Apply a function `f` in series to each value of an object, returning an object of results. `f` may be asynchronous.
+ */
+const objectMapSeries = function (object, f) {
+  const result = {}
+  const doneKeys = {}
+  for (const key in object) {
+    doneKeys[key] = true
+    const resultItem = f(object[key], key, object)
+    if (isPromise(resultItem)) {
+      return resultItem.then(funcConcat(
+        curry3(objectSet, result, key, __),
+        thunkify4(_objectMapSeriesAsync, object, f, result, doneKeys),
+      ))
+    }
+    result[key] = resultItem
+  }
+  return result
+}
+
+module.exports = objectMapSeries

package/_internal/setAdd.js

@@ -0,0 +1,14 @@
+/**
+ * @name setAdd
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * setAdd(set Set, value any) -> set
+ * ```
+ */
+const setAdd = function (set, value) {
+  set.add(value)
+  return set
+}
+
+module.exports = setAdd

package/_internal/setMapPool.js

@@ -0,0 +1,79 @@
+const isPromise = require('./isPromise')
+const promiseRace = require('./promiseRace')
+const promiseAll = require('./promiseAll')
+const symbolIterator = require('./symbolIterator')
+
+/**
+ * @name _setMapPoolAsync
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * _setMapPoolAsync(
+ *   s Set,
+ *   iterator Iterator,
+ *   concurrency number,
+ *   f function,
+ *   result Set,
+ *   promises Set,
+ * ) -> result Promise<Set>
+ * ```
+ */
+const _setMapPoolAsync = async function (
+  s, iterator, concurrency, f, result, promises,
+) {
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    if (promises.size >= concurrency) {
+      await promiseRace(promises)
+    }
+    const resultItem = f(iteration.value, iteration.value, s)
+    if (isPromise(resultItem)) {
+      const selfDeletingPromise = resultItem.then(resolvedValue => {
+        promises.delete(selfDeletingPromise)
+        result.add(resolvedValue)
+      })
+      promises.add(selfDeletingPromise)
+    } else {
+      result.add(resultItem)
+    }
+    iteration = iterator.next()
+  }
+  if (promises.size > 0) {
+    await promiseAll(promises)
+  }
+  return result
+}
+
+/**
+ * @name setMapPool
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * setMapPool(s Set, concurrency number, f function) -> Promise|Set
+ * ```
+ *
+ * @description
+ * Apply a function `f` with limited concurrency to each item of a set `s`, returning an array of results.
+ */
+const setMapPool = function (s, concurrency, f) {
+  const result = new Set()
+  const iterator = s[symbolIterator]()
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    const resultItem = f(iteration.value, iteration.value, s)
+    if (isPromise(resultItem)) {
+      const promises = new Set()
+      const selfDeletingPromise = resultItem.then(resolvedValue => {
+        promises.delete(selfDeletingPromise)
+        result.add(resolvedValue)
+      })
+      promises.add(selfDeletingPromise)
+      return _setMapPoolAsync(s, iterator, concurrency, f, result, promises)
+    }
+    result.add(resultItem)
+    iteration = iterator.next()
+  }
+  return result
+}
+
+module.exports = setMapPool

package/_internal/setMapSeries.js

@@ -0,0 +1,61 @@
+const isPromise = require('./isPromise')
+const curry2 = require('./curry2')
+const thunkify3 = require('./thunkify3')
+const setAdd = require('./setAdd')
+const funcConcat = require('./funcConcat')
+const symbolIterator = require('./symbolIterator')
+
+// _setMapSeriesAsync(
+//   iterator Iterator,
+//   f function,
+//   result Set,
+// ) -> Promise<Set>
+const _setMapSeriesAsync = async function (iterator, f, result) {
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    let resultItem = f(iteration.value)
+    if (isPromise(resultItem)) {
+      resultItem = await resultItem
+    }
+    result.add(resultItem)
+    iteration = iterator.next()
+  }
+  return result
+}
+
+/**
+ * @name setMapSeries
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type SetMapper = (
+ *   value any,
+ *   key any,
+ *   collection Set
+ * )=>(resultItem Promise|any)
+ *
+ * setMapSeries(set Set, f SetMapper) -> Promise|Set
+ * ```
+ *
+ * @description
+ * Apply a mapper in series to each value of a set, returning a new set of mapped items. Mapper may be asynchronous.
+ */
+const setMapSeries = function (set, f) {
+  const result = new Set()
+  const iterator = set[symbolIterator]()
+  let iteration = iterator.next()
+  while (!iteration.done) {
+    const resultItem = f(iteration.value)
+    if (isPromise(resultItem)) {
+      return resultItem.then(funcConcat(
+        curry2(setAdd, result, __),
+        thunkify3(_setMapSeriesAsync, iterator, f, result),
+      ))
+    }
+    result.add(resultItem)
+    iteration = iterator.next()
+  }
+  return result
+}
+
+module.exports = setMapSeries

package/_internal/stringMap.js

@@ -17,7 +17,7 @@ const callPropUnary = require('./callPropUnary')
  * ```
  *
  * @description
- * Apply a mapper concurrently to each character of a string, returning a string result. `mapper` may be asynchronous.
+ * Apply a mapper concurrently to each character of a string, returning a string result. mapper function may be asynchronous.
  *
  * @related stringFlatMap
  */

package/_internal/stringMapPool.js

@@ -0,0 +1,22 @@
+const isPromise = require('./isPromise')
+const curry3 = require('./curry3')
+const __ = require('./placeholder')
+const callPropUnary = require('./callPropUnary')
+const arrayMapPool = require('./arrayMapPool')
+
+/**
+ * @name stringMapPool
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * stringMapPool(s string, concurrency number, f function) -> Promise|string
+ * ```
+ */
+const stringMapPool = function (s, concurrency, f) {
+  const result = arrayMapPool(s, concurrency, f)
+  return isPromise(result)
+    ? result.then(curry3(callPropUnary, __, 'join', ''))
+    : result.join('')
+}
+
+module.exports = stringMapPool

package/_internal/stringMapSeries.js

@@ -0,0 +1,31 @@
+const isPromise = require('./isPromise')
+const curry3 = require('./curry3')
+const __ = require('./placeholder')
+const arrayMapSeries = require('./arrayMapSeries')
+const callPropUnary = require('./callPropUnary')
+
+/**
+ * @name stringMapSeries
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * stringMapSeries<
+ *   character string,
+ *   str String<character>,
+ *   mapper character=>Promise|string|any,
+ * >(str, mapper) -> stringWithCharactersMapped string
+ * ```
+ *
+ * @description
+ * Apply a mapper function in series to each character of a string, returning a string result. mapper function may be asynchronous.
+ *
+ * @related stringFlatMap
+ */
+const stringMapSeries = function (string, mapper) {
+  const result = arrayMapSeries(string, mapper)
+  return isPromise(result)
+    ? result.then(curry3(callPropUnary, __, 'join', ''))
+    : result.join('')
+}
+
+module.exports = stringMapSeries

package/all.js

@@ -23,7 +23,7 @@ const functionObjectAll = require('./_internal/functionObjectAll')
  * ```
  *
  * @description
- * Function executor and composer. Accepts either an array of functions or an object of functions as the values. Calls each function of the provided array or object in parallel with the provided arguments. Returns either an array or object of the results of the function executions.
+ * Function executor and composer. Accepts either an array of functions or an object of functions. Calls each function of the provided array or object in parallel with the provided arguments. Returns either an array or object of the execution results.
  *
  * ```javascript [playground]
  * const createArrayOfGreetingsFor = all([
@@ -72,6 +72,16 @@ const functionObjectAll = require('./_internal/functionObjectAll')
  * getAndLogUserById('1') // Got user {"_id":1,"name":"George"} by id 1
  * ```
  *
+ * 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]
+ * ```
+ *
  * @execution concurrent
  */
 

package/and.js

@@ -131,6 +131,15 @@ const areAllPredicatesTruthy = function (args, predicates) {
  * ) // 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.
+ *
+ * ```javascript [playground]
+ * and(Promise.resolve(5), [
+ *   n => n > 0,
+ *   n => n < 10,
+ * ]).then(console.log) // true
+ * ```
+ *
  * @execution series
  *
  * @note ...args slows down here by an order of magnitude

package/assign.js

@@ -18,7 +18,7 @@ const _assign = function (object, funcs) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * assign(object Object, resolvers Object<function>) -> result Promise|Object
+ * assign(object Promise|Object, resolvers Object<function>) -> result Promise|Object
  *
  * assign(resolvers Object<function>)(object Object) -> result Promise|Object
  * ```
@@ -55,6 +55,19 @@ const _assign = function (object, funcs) {
  * // { numbers: [1, 2, 3, 4, 5], total: 15 }
  * ```
  *
+ * 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]
+ * assign(Promise.resolve({}), {
+ *   a() {
+ *     return 1
+ *   },
+ *   b() {
+ *     return 2
+ *   },
+ * }).then(console.log)
+ * ```
+ *
  * @execution concurrent
  */
 const assign = function (arg0, arg1) {