rubico 2.5.0 → 2.6.0

package/index.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.5.0
+ * rubico v2.6.0
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.
@@ -164,6 +164,9 @@ const tap = function (...args) {
   if (args.length == 0) {
     return curryArgs2(_tap, __, func)
   }
+  if (areAnyValuesPromises(args)) {
+    return promiseAll(args).then(curry2(_tap, __, func))
+  }
   return _tap(args, func)
 }
 
@@ -707,6 +710,7 @@ const objectMapSeries = function (object, f) {
         thunkify4(_objectMapSeriesAsync, object, f, result, doneKeys),
       ))
     }
+    result[key] = resultItem
   }
   return result
 }
@@ -801,15 +805,14 @@ const tapSync = func => function tapping(...args) {
 const promiseRace = Promise.race.bind(Promise)
 
 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)))
@@ -822,13 +825,12 @@ const arrayMapPoolAsync = async function (
   return promiseAll(result)
 }
 
-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(
@@ -836,13 +838,167 @@ 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
   }
   return result
 }
 
+const stringMapPool = function (s, concurrency, f) {
+  const result = arrayMapPool(s, concurrency, f)
+  return isPromise(result)
+    ? result.then(curry3(callPropUnary, __, 'join', ''))
+    : result.join('')
+}
+
+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
+}
+
+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
+}
+
+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
+}
+
+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
+}
+
+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
+}
+
+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
+}
+
 const _curryArity = (arity, func, args) => function curried(...curriedArgs) {
   const argsLength = args.length,
     curriedArgsLength = curriedArgs.length,
@@ -978,7 +1134,7 @@ const _map = function (value, mapper) {
 }
 
 const map = function (arg0, arg1) {
-  if (typeof arg0 == 'function') {
+  if (arg1 == null) {
     return curry2(_map, __, arg0)
   }
   return isPromise(arg0)
@@ -1001,7 +1157,7 @@ const _mapEntries = (value, mapper) => {
 }
 
 map.entries = function mapEntries(arg0, arg1) {
-  if (typeof arg0 == 'function') {
+  if (arg1 == null) {
     return curry2(_mapEntries, __, arg0)
   }
   return isPromise(arg0)
@@ -1033,7 +1189,7 @@ const _mapSeries = function (collection, f) {
 }
 
 map.series = function mapSeries(arg0, arg1) {
-  if (typeof arg0 == 'function') {
+  if (arg1 == null) {
     return curry2(_mapSeries, __, arg0)
   }
   return isPromise(arg0)
@@ -1041,11 +1197,35 @@ map.series = function mapSeries(arg0, arg1) {
     : _mapSeries(arg0, arg1)
 }
 
-map.pool = (concurrencyLimit, mapper) => function concurrentPoolMapping(value) {
-  if (isArray(value)) {
-    return arrayMapPool(value, mapper, concurrencyLimit)
+const _mapPool = function (collection, concurrency, f) {
+  if (isArray(collection)) {
+    return arrayMapPool(collection, concurrency, f)
+  }
+  if (collection == null) {
+    throw new TypeError(`invalid collection ${collection}`)
   }
-  throw new TypeError(`${value} is not an Array`)
+  if (typeof collection == 'string' || collection.constructor == String) {
+    return stringMapPool(collection, concurrency, f)
+  }
+  if (collection.constructor == Set) {
+    return setMapPool(collection, concurrency, f)
+  }
+  if (collection.constructor == Map) {
+    return mapMapPool(collection, concurrency, f)
+  }
+  if (collection.constructor == Object) {
+    return objectMapPool(collection, concurrency, f)
+  }
+  throw new TypeError(`invalid collection ${collection}`)
+}
+
+map.pool = function mapPool(arg0, arg1, arg2) {
+  if (arg2 == null) {
+    return curry3(_mapPool, __, arg0, arg1)
+  }
+  return isPromise(arg0)
+    ? arg0.then(curry3(_mapPool, __, arg1, arg2))
+    : _mapPool(arg0, arg1, arg2)
 }
 
 const FilteringIterator = (iterator, predicate) => ({
@@ -2152,7 +2332,8 @@ const _forEach = function (collection, callback) {
     return collection
   }
   if (typeof collection.forEach == 'function') {
-    return collection.forEach(callback)
+    collection.forEach(callback)
+    return collection
   }
   if (typeof collection[symbolIterator] == 'function') {
     return iteratorForEach(collection[symbolIterator](), callback)

package/lt.js

@@ -47,6 +47,12 @@ const lessThan = require('./_internal/lessThan')
  *   console.log, // 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]
+ * lt(Promise.resolve({ a: 1, b: 2 }), get('a'), get('b')).then(console.log) // true
+ * ```
  */
 const lt = ComparisonOperator(lessThan)
 

package/lte.js

@@ -47,6 +47,12 @@ const lessThanOrEqual = require('./_internal/lessThanOrEqual')
  *   console.log, // 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]
+ * lte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
+ * ```
  */
 const lte = ComparisonOperator(lessThanOrEqual)
 

package/map.js

@@ -3,6 +3,7 @@ const MappingIterator = require('./_internal/MappingIterator')
 const MappingAsyncIterator = require('./_internal/MappingAsyncIterator')
 const __ = require('./_internal/placeholder')
 const curry2 = require('./_internal/curry2')
+const curry3 = require('./_internal/curry3')
 const isArray = require('./_internal/isArray')
 const isObject = require('./_internal/isObject')
 const arrayMap = require('./_internal/arrayMap')
@@ -16,6 +17,10 @@ const objectMapSeries = require('./_internal/objectMapSeries')
 const setMapSeries = require('./_internal/setMapSeries')
 const mapMapSeries = require('./_internal/mapMapSeries')
 const arrayMapPool = require('./_internal/arrayMapPool')
+const stringMapPool = require('./_internal/stringMapPool')
+const setMapPool = require('./_internal/setMapPool')
+const mapMapPool = require('./_internal/mapMapPool')
+const objectMapPool = require('./_internal/objectMapPool')
 const objectMapEntries = require('./_internal/objectMapEntries')
 const mapMapEntries = require('./_internal/mapMapEntries')
 const symbolIterator = require('./_internal/symbolIterator')
@@ -45,21 +50,6 @@ const symbolAsyncIterator = require('./_internal/symbolAsyncIterator')
  *   originalMap Map,
  *   mapMapper (value any, key any, originalMap Map)=>Promise|any
  * ) -> mappedMap Promise|Map
- *
- * _map(
- *   generatorFunction ...args=>Generator,
- *   syncMapper (value any)=>any,
- * ) -> mappingGeneratorFunction ...args=>Generator
- *
- * _map(
- *   asyncGeneratorFunction ...args=>AsyncGenerator,
- *   mapper (value any)=>Promise|any
- * ) -> mappingAsyncGeneratorFunction ...args=>AsyncGenerator
- *
- * _map(
- *   originalReducer Reducer,
- *   mapper (value any)=>Promise|any,
- * ) -> mappingReducer Reducer
  * ```
  */
 
@@ -107,11 +97,11 @@ const _map = function (value, mapper) {
  *
  * type Mapper = (
  *   value any,
- *   indexOrKey number|string,
+ *   indexOrKey number|string|any,
  *   collection Mappable
  * )=>(resultItem Promise|any)
  *
- * map(collection Mappable, f Mapper) -> result Promise|Mappable
+ * map(collection Promise|Mappable, f Mapper) -> result Promise|Mappable
  * map(f Mapper)(collection Mappable) -> result Promise|Mappable
  * ```
  *
@@ -246,12 +236,21 @@ const _map = function (value, mapper) {
  * })()
  * ```
  *
+ * 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]
+ * const asyncSquare = async n => n ** 2
+ *
+ * map(Promise.resolve([1, 2, 3, 4, 5]), asyncSquare).then(console.log)
+ * // [1, 4, 9, 16, 25]
+ * ```
+ *
  * @execution concurrent
  *
  * @TODO streamMap
  */
 const map = function (arg0, arg1) {
-  if (typeof arg0 == 'function') {
+  if (arg1 == null) {
     return curry2(_map, __, arg0)
   }
   return isPromise(arg0)
@@ -278,14 +277,19 @@ const _mapEntries = (value, mapper) => {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * map.entries(
- *   value Map|Object|Promise<Map|Object>,
- *   mapper ([key any, value any])=>Promise|[any, any],
- * ) -> Promise|Map|Object
+ * type EntriesMappable = Object|Map
  *
- * map.entries(
- *   mapper ([key any, value any])=>Promise|[any, any],
- * )(value Map|Object) -> Promise|Map|Object
+ * type Mapper = (
+ *   value any,
+ *   key string|any,
+ *   collection EntriesMappable
+ * )=>(resultItem Promise|any)
+ *
+ * map.entries(value Promise|EntriesMappable, mapper Mapper)
+ *   -> Promise|EntriesMappable
+ *
+ * map.entries(mapper Mapper)(value EntriesMappable)
+ *   -> Promise|EntriesMappable
  * ```
  *
  * @description
@@ -302,10 +306,22 @@ const _mapEntries = (value, mapper) => {
  * // Map(3) { 'A' => 1, 'B' => 4, 'C' => 9 }
  * ```
  *
+ * 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]
+ * const asyncSquareEntries = async ([k, v]) => [k, v ** 2]
+ *
+ * map.entries(
+ *   Promise.resolve({ a: 1, b: 2, c: 3 }),
+ *   asyncSquareEntries,
+ * ).then(console.log)
+ * // { a: 1, b: 4, c: 9 }
+ * ```
+ *
  * @since v1.7.0
  */
 map.entries = function mapEntries(arg0, arg1) {
-  if (typeof arg0 == 'function') {
+  if (arg1 == null) {
     return curry2(_mapEntries, __, arg0)
   }
   return isPromise(arg0)
@@ -318,11 +334,11 @@ map.entries = function mapEntries(arg0, arg1) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map|Iterator|AsyncIterator
+ * type Mappable = Array|Object|Set|Map
  *
  * type Mapper = (
  *   value any,
- *   indexOrKey number|string,
+ *   indexOrKey number|string|any,
  *   collection Mappable
  * )=>(mappedItem Promise|any)
  *
@@ -357,23 +373,20 @@ const _mapSeries = function (collection, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map|Iterator|AsyncIterator
+ * type Mappable = Array|Object|Set|Map
  *
  * type Mapper = (
  *   value any,
- *   indexOrKey number|string,
+ *   indexOrKey number|string|any,
  *   collection Mappable
  * )=>(mappedItem Promise|any)
  *
- * map.series( Mappable)
- *
- * map.series(
- *   mapperFunc (value any)=>Promise|any,
- * )(array Array) -> Promise|Array
+ * map.series(collection Promise|Mappable, f Mapper) -> result Mappable
+ * map.series(f Mapper)(collection Mappable) -> result Mappable
  * ```
  *
  * @description
- * `map` with serial execution.
+ * [map](/docs/map) with serial execution.
  *
  * ```javascript [playground]
  * const delayedLog = number => new Promise(function (resolve) {
@@ -384,13 +397,22 @@ const _mapSeries = function (collection, f) {
  * })
  *
  * console.log('start')
- * map.series(delayedLog)([1, 2, 3, 4, 5])
+ * map.series([1, 2, 3, 4, 5], delayedLog)
+ * ```
+ *
+ * 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]
+ * const asyncSquare = async n => n ** 2
+ *
+ * map.series(Promise.resolve([1, 2, 3, 4, 5]), asyncSquare).then(console.log)
+ * // [1, 4, 9, 16, 25]
  * ```
  *
  * @execution series
  */
 map.series = function mapSeries(arg0, arg1) {
-  if (typeof arg0 == 'function') {
+  if (arg1 == null) {
     return curry2(_mapSeries, __, arg0)
   }
   return isPromise(arg0)
@@ -398,19 +420,59 @@ map.series = function mapSeries(arg0, arg1) {
     : _mapSeries(arg0, arg1)
 }
 
+/**
+ * @name _mapPool
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Mappable = Array|Object|Set|Map
+ *
+ * _mapPool(collection Mappable, concurrency number, f function) -> result Promise|Mappable
+ * ```
+ */
+const _mapPool = function (collection, concurrency, f) {
+  if (isArray(collection)) {
+    return arrayMapPool(collection, concurrency, f)
+  }
+  if (collection == null) {
+    throw new TypeError(`invalid collection ${collection}`)
+  }
+  if (typeof collection == 'string' || collection.constructor == String) {
+    return stringMapPool(collection, concurrency, f)
+  }
+  if (collection.constructor == Set) {
+    return setMapPool(collection, concurrency, f)
+  }
+  if (collection.constructor == Map) {
+    return mapMapPool(collection, concurrency, f)
+  }
+  if (collection.constructor == Object) {
+    return objectMapPool(collection, concurrency, f)
+  }
+  throw new TypeError(`invalid collection ${collection}`)
+}
+
 /**
  * @name map.pool
  *
  * @synopsis
  * ```coffeescript [specscript]
+ * type Mappable = Array|Object|Set|Map
+ *
+ * map.pool(
+ *   concurrency number,
+ *   mapper (value any)=>Promise|any,
+ * )(collection Mappable) -> result Promise|Array
+ *
  * map.pool(
- *   maxConcurrency number,
+ *   collection Mappable,
+ *   concurrency number,
  *   mapper (value any)=>Promise|any,
- * )(array Array) -> result Promise|Array
+ * ) -> result Promise|Array
  * ```
  *
  * @description
- * `map` that specifies the maximum concurrency (number of ongoing promises at any time) of the execution. Only works for arrays.
+ * [map](/docs/map) with limited [concurrency](https://web.mit.edu/6.005/www/fa14/classes/17-concurrency/).
  *
  * ```javascript [playground]
  * const ids = [1, 2, 3, 4, 5]
@@ -428,15 +490,26 @@ map.series = function mapSeries(arg0, arg1) {
  * ]))(ids)
  * ```
  *
+ * 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]
+ * 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]
+ * ```
+ *
  * @TODO objectMapPool
  *
  * @execution concurrent
  */
-map.pool = (concurrencyLimit, mapper) => function concurrentPoolMapping(value) {
-  if (isArray(value)) {
-    return arrayMapPool(value, mapper, concurrencyLimit)
+map.pool = function mapPool(arg0, arg1, arg2) {
+  if (arg2 == null) {
+    return curry3(_mapPool, __, arg0, arg1)
   }
-  throw new TypeError(`${value} is not an Array`)
+  return isPromise(arg0)
+    ? arg0.then(curry3(_mapPool, __, arg1, arg2))
+    : _mapPool(arg0, arg1, arg2)
 }
 
 module.exports = map

package/not.js

@@ -45,6 +45,14 @@ const _not = function (args, predicate) {
  *   not(isOdd)(3),
  * ) // false
  * ```
+ *
+ * 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]
+ * const isOdd = number => number % 2 == 1
+ *
+ * not(Promise.resolve(3), isOdd).then(console.log) // false
+ * ```
  */
 
 const not = function (...args) {

package/omit.js

@@ -62,6 +62,13 @@ const _omit = function (source, paths) {
  *   console.log, // { c: 9 }
  * ])
  * ```
+ *
+ * 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]
+ * omit(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
+ * // { c: 3 }
+ * ```
  */
 const omit = function (arg0, arg1) {
   if (arg1 == null) {

package/or.js

@@ -129,6 +129,15 @@ const areAnyPredicatesTruthy = 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]
+ * or(Promise.resolve('aaa'), [
+ *   s => s.startsWith('b'),
+ *   s => s.endsWith('a'),
+ * ]).then(console.log) // true
+ * ```
+ *
  * @execution series
  *
  * @note ...args slows down here by an order of magnitude

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "MIT",

package/pick.js

@@ -62,6 +62,13 @@ const _pick = function (source, keys) {
  *   console.log, // { a: 1, c: 9 }
  * ])
  * ```
+ *
+ * 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]
+ * pick(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
+ * // { a: 1, b: 2 }
+ * ```
  */
 const pick = function (arg0, arg1) {
   if (arg1 == null) {