rubico 2.6.6 → 2.7.1

package/filter.js

@@ -90,38 +90,74 @@ const _filter = function (value, predicate) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Filterable = Array|Object|Set|Generator|AsyncGenerator
+ * type Filterable = Array|Set|Map|Generator|AsyncGenerator|{ filter: function }|Object
  *
  * type Predicate = (
  *   value any,
- *   indexOrKey number|string,
- *   collection Filterable,
+ *   indexOrKey number|string|any,
+ *   filt Filterable,
  * )=>boolean
  *
- * filter(f Map|Filterable, predicate Predicate) -> result Promise|Map|Filterable
- * filter(predicate Predicate)(f Map|Filterable) -> result Promise|Map|Filterable
+ * filter(filt Filterable, predicate Predicate) -> result Promise|Filterable
+ * filter(predicate Predicate)(filt Filterable) -> result Promise|Filterable
  * ```
  *
  * @description
- * Filter out items from a filterable. Returns a filterable of the same type.
+ * Filters out items from a filterable. Returns a filterable of the same type. The order of the items in the filterable is preserved.
  *
- * The following data types are considered filterable:
+ * The following data types are considered to be filterables:
  *  * `array`
- *  * `object`
  *  * `set`
+ *  * `map`
  *  * `generator`
  *  * `async generator`
+ *  * `object with .filter method`
+ *  * `object`
  *
  * The filtering operation is defined by a given predicate function. The predicate function dictates whether a given item from the filterable should be included in the returned filterable.
  *
  * ```javascript
  * const predicate = function (item) {
- *   // condition is a boolean value involving item
+ *   // condition is the boolean result of the predicate test on item
  *   return condition
  * }
  * ```
  *
- * `filter` applies a provided predicate function to each item of a filterable, returning a filterable of the same type containing only the items with truthy conditions by the predicate. The order of the items is preserved.
+ * The predicate function signature changes depending on the provided filterable.
+ *
+ * If the filterable is an array:
+ * ```coffeescript [specscript]
+ * predicate(item any, index number, filt Array) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is a set:
+ * ```coffeescript [specscript]
+ * predicate(item any, item any, filt Set) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is a map:
+ * ```coffeescript [specscript]
+ * predicate(item any, key any, filt Map) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is a generator:
+ * ```coffeescript [specscript]
+ * predicate(item any) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is an async generator:
+ * ```coffeescript [specscript]
+ * predicate(item any) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is an object with a `.filter` method, the predicate function signature is defined externally.
+ *
+ * If the filterable is a plain object:
+ * ```coffeescript [specscript]
+ * predicate(item any, key string, filt Object) -> condition Promise|boolean|any
+ * ```
+ *
+ * `filter` works for arrays.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -132,7 +168,7 @@ const _filter = function (value, predicate) {
  * console.log(result) // [1, 3, 5]
  * ```
  *
- * The predicate may be asynchronous, in which case the returned promise is concurrently resolved for its boolean condition before deciding whether to include the corresponding item in the result.
+ * If the predicate is asynchronous, the returned promise is concurrently resolved for its boolean condition before continuing with the filtering operation.
  *
  * ```javascript [playground]
  * const asyncIsOdd = async number => number % 2 == 1
@@ -143,7 +179,7 @@ const _filter = function (value, predicate) {
  * promise.then(console.log) // [1, 3, 5]
  * ```
  *
- * For objects, `filter` applies the predicate function to just the values.
+ * `filter` applies the predicate function to just the values of an object.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -154,7 +190,7 @@ const _filter = function (value, predicate) {
  * console.log(result) // { a: 1, c: 3, e: 5 }
  * ```
  *
- * For maps, `filter` applies the predicate to the values of the entries. The order of the entries is preserved.
+ * `filter` applies the predicate to the values of the entries of a map.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -165,7 +201,7 @@ const _filter = function (value, predicate) {
  * console.log(result) // Map(3) { 'a' => 1, 'c' => 3, 'e' => 5 }
  * ```
  *
- * For generators, `filter` returns a lazily filtered generator. All values that are normally yielded by the generator that test falsy by the predicate are skipped.
+ * For generators, `filter` returns a lazily filtered generator. All values that are normally yielded by the generator that test false by the predicate are excluded from the returned generator.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -192,7 +228,7 @@ const _filter = function (value, predicate) {
  * }
  * ```
  *
- * For async generators, `filter` returns a lazily filtered async generator. All values that are normally yielded by the async generator that test falsy by the predicate are skipped.
+ * For async generators, `filter` returns a lazily filtered async generator. All values that are normally yielded by the async generator that test falsy by the predicate are excluded from the returned async generator.
  *
  * ```javascript [playground]
  * const asyncIsOdd = async number => number % 2 == 1
@@ -229,6 +265,14 @@ const _filter = function (value, predicate) {
  * // [1, 3, 5]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @execution concurrent
  *
  * @transducing

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.1
  * 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) {
@@ -3274,11 +3282,15 @@ const omit = function (arg0, arg1) {
   return _omit(arg0, arg1)
 }
 
-const thunkify = (func, ...args) => function thunk() {
+const thunkify = function (func, ...args) {
   if (areAnyValuesPromises(args)) {
-    return promiseAll(args).then(curry2(funcApply, func, __))
+    return promiseAll(args).then(resolvedArgs => function thunk() {
+      return func(...resolvedArgs)
+    })
+  }
+  return function thunk() {
+    return func(...args)
   }
-  return func(...args)
 }
 
 const curry = (func, ...args) => curryArity(func.length, func, 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)