rubico 2.6.6 → 2.7.0

package/flatMap.js

@@ -15,7 +15,7 @@ const __ = require('./_internal/placeholder')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Monad = Array|String|Set|Iterator|AsyncIterator
+ * type Monad = Array|String|Set|Generator|AsyncGenerator
  * type Iterable = Iterable|AsyncIterable|Object<value any>
  *
  * _flatMap(
@@ -64,35 +64,36 @@ const _flatMap = function (value, flatMapper) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Monad = Array|String|Set|Iterator|AsyncIterator
- * type Flattenable = Iterable|AsyncIterable|Object<value any>
+ * type Monad = Array|String|Set|Generator|AsyncGenerator|{ flatMap: string }|{ chain: string }|Object
  *
  * type FlatMapper = (
  *   item any,
- *   indexOrKey string,
- *   m Monad
- * )=>Promise|Flattenable|any
+ *   indexOrKey number|string|any,
+ *   mon Monad
+ * )=>Promise|Monad|any
  *
- * flatMap(m Monad, flatMapper FlatMapper) -> result Promise|Monad
- * flatMap(flatMapper FlatMapper)(m Monad) -> result Promise|Monad
+ * flatMap(mon Monad, flatMapper FlatMapper) -> result Promise|Monad
+ * flatMap(flatMapper FlatMapper)(mon Monad) -> result Promise|Monad
  * ```
  *
  * @description
- * Applies a flatMapper function concurrently to each item of a monad, returning a monad of the same type. A flatMapping operation iterates through each item of a monad and applies the flatMapper function to each item, flattening the result of the execution into the returned monad. The result of an individual execution can be any iterable, async iterable, or object with enumerable values. The flatMapper function may be asynchronous.
+ * Applies a flatMapper function to each item of a monad, returning a monad of the same type.
  *
- * The following data types are considered monads:
+ * A flatMapping operation iterates through each item of a monad and applies the flatMapper function to each item, flattening the result of the execution into the returned monad.
+ *
+ * If the flatMapper is asynchronous, it is executed concurrently. The execution result may be asynchronously iterable, in which case it is muxed into the returned monad.
+ *
+ * The following data types are considered to be monads, all are flattenable into other monads:
  *  * `array`
  *  * `string`
  *  * `set`
- *  * `iterator`
- *  * `async iterator`
+ *  * `genreator`
+ *  * `async generator`
+ *  * `object with .flatMap method`
+ *  * `object with .chain method`
+ *  * `object`
  *
- * The following data types are considered flattenable:
- *  * `iterable` - the execution result is iterated and each item is added to the result collection
- *  * `async iterable` - the execution result is asynchronously iterated and each item is added to the result collection
- *  * `object` - the execution result values are added to the result collection
- *
- * `flatMap` can flatten various data types.
+ * `flatMap` flattens various data types.
  *
  * ```javascript [playground]
  * const identity = value => value
@@ -100,15 +101,15 @@ const _flatMap = function (value, flatMapper) {
  * flatMap(identity)([
  *   [1, 1], // array
  *   new Set([2, 2]), // set
- *   (function* () { yield 3; yield 3 })(), // generator
- *   (async function* () { yield 7; yield 7 })(), // asyncGenerator
+ *   (function* () { yield 3; yield 3 })(),
+ *   (async function* () { yield 7; yield 7 })(),
  *   { a: 5, b: 5 }, // object
  *   new Uint8Array([8]), // typedArray
  * ]).then(console.log)
  * // [1, 1, 2, 3, 3, 5, 5, 8, 7, 7]
  * ```
  *
- * `flatMap` muxes asynchronous values. Muxing, or asynchronously "mixing", is the process of combining multiple asynchronous sources into one source, with order determined by the asynchronous resolution of the individual items.
+ * Values from async generators are muxed. Muxing, or asynchronously "mixing", is the process of combining multiple asynchronous sources into one source, with order determined by the asynchronous resolution of the individual items.
  *
  * ```javascript [playground]
  * const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
@@ -129,12 +130,12 @@ const _flatMap = function (value, flatMapper) {
  *   yield message
  * }
  *
- * // async is muxed
+ * // values from async generators are muxed
  * flatMap(['foo', 'bar', 'baz'], asyncRepeat3).then(console.log)
  * // ['foo', 'bar', 'baz', 'foo', 'bar', 'baz', 'foo', 'bar', 'baz']
  * ```
  *
- * For arrays (type `Array`), `flatMap` applies the flatMapper function to each item, pushing (`.push`) the items of each execution into a new array.
+ * `flatMap` applies the flatMapper function to each item of an array, flattening the results into a new array.
  *
  * ```javascript [playground]
  * const duplicate = value => [value, value]
@@ -161,6 +162,14 @@ const _flatMap = function (value, flatMapper) {
  * // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [some](/docs/some)
+ *
  * @execution concurrent
  *
  * @transducing

package/forEach.js

@@ -45,20 +45,86 @@ const _forEach = function (collection, callback) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Collection = Array|Iterable|AsyncIterable|{ forEach: function }|Object
+ * type Iterable = Array|Set|Map|Generator|AsyncGenerator|{ forEach: function }|Object
+ *
+ * type Callback = (
+ *   item any,
+ *   indexOrKey number|string|any,
+ *   iter Iterable
+ * )=>Promise|undefined
  *
- * forEach(collection Collection, callback function) -> collection Promise|Collection
+ * forEach(iter Iterable, cb Callback) -> iter Promise|Iterable
  *
- * forEach(callback function)(collection Collection) -> collection Promise|Collection
+ * forEach(cb Callback)(iter Iterable) -> iter Promise|Iterable
  * ```
  *
  * @description
- * Execute a callback for each item of a collection, returning a Promise if the execution is asynchronous. Asynchronous execution happens concurrently.
+ * Execute a callback function for each item of an iterable, returning the original iterable unmodified.
+ *
+ * The following data types are considered to be iterables:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .forEach method`
+ *  * `object`
+ *
+ * The callback function signature changes depending on the provided iterable.
+ *
+ * If the iterable is an array:
+ * ```coffeescript [specscript]
+ * callback(item any, index number, iter Array) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is a set:
+ * ```coffeescript [specscript]
+ * callback(item any, key any, iter Set) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is a map:
+ * ```coffeescript [specscript]
+ * callback(item any, key any, filt Map) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is a generator:
+ * ```coffeescript [specscript]
+ * callback(item any) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is an async generator:
+ * ```coffeescript [specscript]
+ * callback(item any) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is an object with a `.forEach` method, the callback function signature is defined externally.
+ *
+ * If the iterable is a plain object:
+ * ```coffeescript [specscript]
+ * callback(item any, key string, iter Object) -> Promise|undefined
+ * ```
+ *
+ * If the callback function is asynchronous, it is executed concurrently.
+ *
+ * ```javascript [playground]
+ * forEach([1, 2, 3, 4, 5], async number => {
+ *   await new Promise(resolve => {
+ *     setTimeout(resolve, 1000)
+ *   })
+ *   console.log(number)
+ * })
+ * ```
+ *
+ * `forEach` works for arrays.
  *
  * ```javascript [playground]
- * forEach([1, 2, 3, 4, 5], console.log) // 1 2 3 4 5
+ * forEach([1, 2, 3, 4, 5], num => console.log(num)) // 1 2 3 4 5
+ * ```
+ *
+ * `forEach` works for objects.
  *
- * forEach({ a: 1, b: 2, c: 3 }, console.log) // 1 2 3
+ * ```javascript [playground]
+ * forEach({ a: 1, b: 2, c: 3 }, num => console.log(num)) // 1 2 3
  * ```
  *
  * Omit the data argument for a composable API
@@ -81,6 +147,13 @@ const _forEach = function (collection, callback) {
  * // 2
  * // 3
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [tap](/docs/tap)
+ *  * [all](/docs/all)
+ *  * [forEach.series](/docs/forEach.series)
+ *  * [map](/docs/map)
  */
 const forEach = function (arg0, arg1) {
   if (typeof arg0 == 'function') {
@@ -125,20 +198,34 @@ const _forEachSeries = function (collection, callback) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Collection = Array|Iterable|AsyncIterable|{ forEach: function }|Object
+ * type Iterable = Array|Set|Map|Generator|AsyncGenerator|{ forEach: function }|Object
+ *
+ * type Callback = (
+ *   item any,
+ *   indexOrKey number|string|any,
+ *   iter Iterable
+ * )=>Promise|undefined
  *
- * forEach.series(collection Collection, callback function) -> collection Promise|Collection
+ * forEach(iter Iterable, cb Callback) -> iter Promise|Iterable
  *
- * forEach.series(callback function)(collection Collection) -> collection Promise|Collection
+ * forEach(cb Callback)(iter Iterable) -> iter Promise|Iterable
  * ```
  *
  * @description
- * Execute a callback for each item of a collection, returning a Promise if the execution is asynchronous. Asynchronous execution happens in series.
+ * [forEach](/docs/forEach) with serial execution.
  *
  * ```javascript [playground]
- * forEach.series([1, 2, 3, 4, 5], console.log) // 1 2 3 4 5
- *
- * forEach.series({ a: 1, b: 2, c: 3 }, console.log) // 1 2 3
+ * forEach.series([1, 2, 3, 4, 5], async number => {
+ *   await new Promise(resolve => {
+ *     setTimeout(resolve, 1000)
+ *   })
+ *   console.log(number)
+ *   // 1
+ *   // 2
+ *   // 3
+ *   // 4
+ *   // 5
+ * })
  * ```
  *
  * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
@@ -149,6 +236,13 @@ const _forEachSeries = function (collection, callback) {
  * // 2
  * // 3
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [tap](/docs/tap)
+ *  * [all](/docs/all)
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
  */
 forEach.series = function forEachSeries(arg0, arg1) {
   if (typeof arg0 == 'function') {

package/get.js

@@ -86,6 +86,15 @@ const _get = function (object, path, defaultValue) {
  * ```javascript [playground]
  * get(Promise.resolve({ a: 1 }), 'a').then(console.log) // 1
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [all](/docs/all)
+ *  * [assign](/docs/assign)
+ *  * [set](/docs/set)
+ *  * [pick](/docs/pick)
+ *  * [omit](/docs/omit)
+ *  * [forEach](/docs/forEach)
  */
 
 const get = function (arg0, arg1, arg2) {

package/gt.js

@@ -53,6 +53,15 @@ const greaterThan = require('./_internal/greaterThan')
  * ```javascript [playground]
  * gt(Promise.resolve({ a: 2, b: 1 }), get('a'), get('b')).then(console.log) // true
  * ```
+ *
+ * See also:
+ *  * [and](/docs/and)
+ *  * [eq](/docs/eq)
+ *  * [lt](/docs/lt)
+ *  * [gte](/docs/gte)
+ *  * [lte](/docs/lte)
+ *  * [thunkify](/docs/thunkify)
+ *
  */
 const gt = ComparisonOperator(greaterThan)
 

package/gte.js

@@ -55,6 +55,15 @@ const greaterThanOrEqual = require('./_internal/greaterThanOrEqual')
  * ```javascript [playground]
  * gte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
  * ```
+ *
+ * See also:
+ *  * [and](/docs/and)
+ *  * [eq](/docs/eq)
+ *  * [lt](/docs/lt)
+ *  * [gt](/docs/gt)
+ *  * [lte](/docs/lte)
+ *  * [thunkify](/docs/thunkify)
+ *
  */
 const gte = ComparisonOperator(greaterThanOrEqual)
 

package/index.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.6
+ * rubico v2.7.0
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2025 Richard Tong
  * rubico may be freely distributed under the MIT license.
@@ -73,6 +73,10 @@ const curry2 = function (baseFunc, arg0, arg1) {
 }
 
 const pipe = function (...args) {
+  if (typeof args[0] == 'function') {
+    return args.reduce(funcConcat)
+  }
+
   const funcs = args.pop()
   const pipeline = funcs.reduce(funcConcat)
 
@@ -88,6 +92,10 @@ const pipe = function (...args) {
 }
 
 const compose = function (...args) {
+  if (typeof args[0] == 'function') {
+    return args.reduceRight(funcConcat)
+  }
+
   const funcs = args.pop()
   const composition = funcs.reduceRight(funcConcat)
 
@@ -1745,17 +1753,17 @@ const genericReduce = function (collection, reducer, result) {
     : reducer(result, collection)
 }
 
-// _reduce(collection any, reducer function, initialValue function|any) -> Promise
-const _reduce = function (collection, reducer, initialValue) {
-  if (typeof initialValue == 'function') {
-    const actualInitialValue = initialValue(collection)
+// _reduce(collection any, reducer function, initial function|any) -> Promise
+const _reduce = function (collection, reducer, initial) {
+  if (typeof initial == 'function') {
+    const actualInitialValue = initial(collection)
     return isPromise(actualInitialValue)
       ? actualInitialValue.then(curry3(genericReduce, collection, reducer, __))
       : genericReduce(collection, reducer, actualInitialValue)
   }
-  return isPromise(initialValue)
-    ? initialValue.then(curry3(genericReduce, collection, reducer, __))
-    : genericReduce(collection, reducer, initialValue)
+  return isPromise(initial)
+    ? initial.then(curry3(genericReduce, collection, reducer, __))
+    : genericReduce(collection, reducer, initial)
 }
 
 const reduce = function (...args) {

package/lte.js

@@ -53,6 +53,15 @@ const lessThanOrEqual = require('./_internal/lessThanOrEqual')
  * ```javascript [playground]
  * lte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
  * ```
+ *
+ * See also:
+ *  * [and](/docs/and)
+ *  * [eq](/docs/eq)
+ *  * [lt](/docs/lt)
+ *  * [gt](/docs/gt)
+ *  * [gte](/docs/gte)
+ *  * [thunkify](/docs/thunkify)
+ *
  */
 const lte = ComparisonOperator(lessThanOrEqual)