rubico 2.5.0 → 2.6.0

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,9 +2,12 @@ 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 __ = 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) {
@@ -36,12 +39,20 @@ 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()
   if (args.length == 0) {
     return curryArgs2(_tap, __, func)
   }
+  if (areAnyValuesPromises(args)) {
+    return promiseAll(args).then(curry2(_tap, __, func))
+  }
   return _tap(args, func)
 }
 

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) {