rubico 2.5.0 → 2.6.1

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.1",
   "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) {

package/pipe.js

@@ -46,6 +46,14 @@ const __ = require('./_internal/placeholder')
  * ])
  * ```
  *
+ * 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]
+ * pipe(Promise.resolve(1), 2, Promise.resolve(3), [
+ *   console.log, // [1, 2, 3]
+ * ])
+ * ```
+ *
  * @execution series
  *
  * @transducing

package/reduce.js

@@ -172,6 +172,14 @@ const _reduce = function (collection, reducer, initialValue) {
  * reduce(asyncAdd)(asyncGenerate12345()).then(console.log) // 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]
+ * const add = (a, b) => a + b
+ *
+ * reduce(Promise.resolve([1, 2, 3, 4, 5]), add, 0).then(console.log) // 15
+ * ```
+ *
  * @execution series
  *
  * @transducing

package/set.js

@@ -90,6 +90,12 @@ const _set = function (obj, path, value) {
  * ])
  * ```
  *
+ * 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]
+ * set(Promise.resolve({}), 'a', 1).then(console.log) // { a: 1 }
+ * ```
+ *
  * @since 1.7.0
  */
 

package/some.js

@@ -92,6 +92,12 @@ const _some = 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.
+ *
+ * ```javascript [playground]
+ * some(Promise.resolve([1, 2, 3, 4, 5]), n => n > 6).then(console.log) // false
+ * ```
+ *
  * @execution concurrent
  *
  * @muxing

package/switchCase.js

@@ -79,6 +79,18 @@ const curryArgs3 = require('./_internal/curryArgs3')
  * console.log(myDrink) // Beer
  * ```
  *
+ * 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]
+ * switchCase(Promise.resolve(1), 2, Promise.resolve(3), [
+ *   function doValuesAddUpTo6(a, b, c) {
+ *     return a + b + c == 6
+ *   },
+ *   (a, b, c) => console.log(`${a} + ${b} + ${c} == 6`),
+ *   (a, b, c) => console.log(`${a} + ${b} + ${c} != 6`),
+ * ]) // 1 + 2 + 3 == 6
+ * ```
+ *
  * @execution series
  */
 const switchCase = (...args) => {

package/tap.js

@@ -2,14 +2,18 @@ const isPromise = require('./_internal/isPromise')
 const always = require('./_internal/always')
 const thunkifyArgs = require('./_internal/thunkifyArgs')
 const thunkConditional = require('./_internal/thunkConditional')
+const curry2 = require('./_internal/curry2')
 const curry3 = require('./_internal/curry3')
 const curryArgs2 = require('./_internal/curryArgs2')
+const curryArgs3 = require('./_internal/curryArgs3')
 const __ = require('./_internal/placeholder')
+const areAnyValuesPromises = require('./_internal/areAnyValuesPromises')
+const promiseAll = require('./_internal/promiseAll')
 
-// _tap(args Array, func function) -> Promise|any
-const _tap = function (args, func) {
+// _tap(args Array, f function) -> Promise|any
+const _tap = function (args, f) {
   const result = args[0],
-    call = func(...args)
+    call = f(...args)
   return isPromise(call) ? call.then(always(result)) : result
 }
 
@@ -18,8 +22,8 @@ const _tap = function (args, func) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * tap(...args, func function) -> Promise|args[0]
- * tap(func function)(...args) -> Promise|args[0]
+ * tap(...args, f function) -> Promise|args[0]
+ * tap(f function)(...args) -> Promise|args[0]
  * ```
  *
  * @description
@@ -36,13 +40,53 @@ const _tap = function (args, func) {
  *                 // 'foobar'
  *                 // 'foobarbaz'
  * ```
+ *
+ * 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]
+ * tap(Promise.resolve(1), Promise.resolve(2), 3, console.log) // 1 2 3
+ * ```
  */
 const tap = function (...args) {
-  const func = args.pop()
+  const f = args.pop()
   if (args.length == 0) {
-    return curryArgs2(_tap, __, func)
+    return curryArgs2(_tap, __, f)
+  }
+  if (areAnyValuesPromises(args)) {
+    return promiseAll(args).then(curry2(_tap, __, f))
+  }
+  return _tap(args, f)
+}
+
+/**
+ * @name _tapIf
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * _tapIf(
+ *   predicate function,
+ *   f function,
+ *   args Array,
+ * ) -> Promise|args[0]
+ * ```
+ */
+const _tapIf = function (predicate, f, args) {
+  const b = predicate(...args)
+  if (isPromise(b)) {
+    return b.then(curry3(
+      thunkConditional,
+      __,
+      thunkifyArgs(tap(f), args),
+      always(args[0]),
+    ))
   }
-  return _tap(args, func)
+  if (b) {
+    const execution = f(...args)
+    if (isPromise(execution)) {
+      return execution.then(always(args[0]))
+    }
+  }
+  return args[0]
 }
 
 /**
@@ -50,37 +94,42 @@ const tap = function (...args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * tap.if(predicate function, func function)(...args) -> Promise|args[0]
+ * tap.if(...args, predicate function, f function) -> Promise|args[0]
+ * tap.if(predicate function, f function)(...args) -> Promise|args[0]
  * ```
  *
  * @description
- * A version of `tap` that accepts a predicate function (a function that returns a boolean value) before the function to execute. Only executes the function if the predicate function tests true for the same arguments provided to the execution function.
+ * A version of `tap` that accepts a predicate function (a function that returns a boolean value) before the function `f` to execute. Only executes `f` if the predicate function tests true. The arguments are the same to both the predicate function and the function to execute `f`.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
- * const logIfOdd = tap.if(
- *   isOdd,
- *   number => console.log(number, 'is an odd number')
- * )
+ * const logIfOdd = tap.if(isOdd, console.log)
  *
  * logIfOdd(2)
- * logIfOdd(3) // 3 is an odd number
+ * logIfOdd(3) // 3
+ * ```
+ *
+ * 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]
+ * tap.if(Promise.resolve(1), n => n < 5, console.log) // 1
+ * tap.if(Promise.resolve(6), n => n < 5, console.log)
  * ```
  */
-tap.if = (predicate, func) => function tappingIf(...args) {
-  const predication = predicate(...args)
-  if (isPromise(predication)) {
-    return predication.then(curry3(
-      thunkConditional, __, thunkifyArgs(tap(func), args), always(args[0])))
+
+tap.if = function (...args) {
+  if (args.length == 2) {
+    return curryArgs3(_tapIf, args[0], args[1], __)
   }
-  if (predication) {
-    const execution = func(...args)
-    if (isPromise(execution)) {
-      return execution.then(always(args[0]))
-    }
+  const argsLength = args.length
+  const f = args[argsLength - 1]
+  const predicate = args[argsLength - 2]
+  const argValues = args.slice(0, -2)
+  if (areAnyValuesPromises(argValues)) {
+    return promiseAll(argValues).then(curry3(_tapIf, predicate, f, __))
   }
-  return args[0]
+  return _tapIf(predicate, f, args)
 }
 
 module.exports = tap

package/transform.js

@@ -115,10 +115,9 @@ const _transform = function (collection, transducer, initialValue) {
  *
  * `transform` an async generator into `process.stdout`, a Node.js writable stream that implements `.write`.
  *
- * ```javascript [node]
- * // this example is duplicated in rubico/examples/transformStreamRandomInts.js
- *
- * const { pipe, map, transform } = require('rubico')
+ * ```javascript [playground]
+ * const { pipe, compose, transform } = rubico
+ * // global Transducer
  *
  * const square = number => number ** 2
  *
@@ -126,17 +125,46 @@ const _transform = function (collection, transducer, initialValue) {
  *
  * const randomInt = () => Math.ceil(Math.random() * 100)
  *
- * const streamRandomInts = async function* () {
- *   while (true) {
+ * const streamRandomInts = async function* (n) {
+ *   let ct = 0
+ *   while (ct < n) {
+ *     ct += 1
  *     yield randomInt()
  *   }
  * }
  *
+ * const Stdout = {
+ *   concat(...args) {
+ *     console.log(...args)
+ *     return this
+ *   },
+ * }
+ *
+ * transform(
+ *   streamRandomInts(10),
+ *   compose([
+ *     Transducer.map(square),
+ *     Transducer.map(toString),
+ *   ]),
+ *   Stdout,
+ * )
+ * // 8281
+ * // 8836
+ * // 1156
+ * // 8649
+ * // 5625
+ * // 2500
+ * // ...
+ * ```
+ *
+ * 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]
  * transform(
- *   streamRandomInts(),
- *   Transducer.map(pipe([square, toString])),
- *   process.stdout,
- * ) // 9216576529289484980147613249169774446246768649...
+ *   Promise.resolve([1, 2, 3, 4, 5]),
+ *   Transducer.map(n => n ** 2),
+ *   [],
+ * ).then(console.log) // [1, 4, 9, 16, 25]
  * ```
  *
  * @execution series

package/tryCatch.js

@@ -61,6 +61,20 @@ const _tryCatch = function (tryer, catcher, args) {
  *   console.error(error.message) // the sum is 6
  * })
  * ```
+ *
+ * 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]
+ * tryCatch(Promise.resolve(1), 2, Promise.resolve(3), (a, b, c) => {
+ *   const sum = a + b + c
+ *   if (sum > 5) {
+ *     throw new Error('limit exceeded')
+ *   }
+ *   console.log('sum:', sum)
+ * }, (error, a, b, c) => {
+ *   console.error(`${a} + ${b} + ${c}: ${error.message}`)
+ * })
+ * ```
  */
 
 const tryCatch = function (...args) {