rubico 2.6.6 → 2.7.1

package/map.js

@@ -93,37 +93,73 @@ const _map = function (value, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Functor = Array|Object|Set|Generator|AsyncGenerator
+ * type Functor = Array|Set|Map|Generator|AsyncGenerator|{ map: function }|Object
  *
  * type Mapper = (
  *   item any,
  *   indexOrKey number|string|any,
- *   f Map|Functor
+ *   ftor Functor
  * )=>(resultItem Promise|any)
  *
- * map(f Promise|Map|Functor, mapper Mapper) -> result Promise|Map|Functor
- * map(mapper Mapper)(f Map|Functor) -> result Promise|Map|Functor
+ * map(ftor Promise|Functor, mapper Mapper) -> result Promise|Functor
+ * map(mapper Mapper)(ftor Functor) -> result Promise|Functor
  * ```
  *
  * @description
- * Applies a mapper function to each item of a functor, returning a functor of the same type with the transformed items. The order of the items is maintained.
+ * Applies a mapper function to each item of a functor, returning a functor of the same type with the mapped items. The order of the items is maintained.
  *
- * The following data types are considered functors:
+ * The following data types are considered to be functors:
  *  * `array`
- *  * `object`
  *  * `set`
- *  * `iterator`
- *  * `async iterator`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .map method`
+ *  * `object`
  *
- * The mapper function defines the transformation of a given item in the provided functor.
+ * The mapper function defines a mapping between a given item in the functor to a resulting item in the returned functor.
  *
  * ```javascript
  * const mapper = function (item) {
- *   // resultItem is the result of some operation on item
+ *   // resultItem is the result of a mapping from item
  *   return resultItem
  * }
  * ```
  *
+ * The mapper function signature changes depending on the provided functor.
+ *
+ * If the functor is an array:
+ * ```coffeescript [specscript]
+ * mapper(item any, index number, ftor Array) -> resultItem Promise|any
+ * ```
+ *
+ * If the functor is a set:
+ * ```coffeescript [specscript]
+ * mapper(item any, item any, ftor Set) -> resultItem Promise|any
+ * ```
+ *
+ * If the functor is a map:
+ * ```coffeescript [specscript]
+ * mapper(item any, key any, ftor Map) -> resultItem Promise|any
+ * ```
+ *
+ * If the functor is a generator:
+ * ```coffeescript [specscript]
+ * mapper(item any) -> resultItem Promise|any
+ * ```
+ *
+ * If the functor is an async generator:
+ * ```coffeescript [specscript]
+ * mapper(item any) -> resultItem Promise|any
+ * ```
+ *
+ * If the functor is an object with a `.map` method, the mapper function signature is defined externally.
+ *
+ * If the functor is a plain object:
+ * ```coffeescript [specscript]
+ * mapper(item any, key string, ftor Object) -> resultItem Promise|any
+ * ```
+ *
  * `map` works for arrays.
  *
  * ```javascript [playground]
@@ -146,7 +182,7 @@ const _map = function (value, f) {
  * promise.then(console.log) // [1, 4, 9, 16, 25]
  * ```
  *
- * For objects, `map` applies the mapper function to just the values.
+ * `map` applies the mapper function to just the values of an object.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -157,7 +193,7 @@ const _map = function (value, f) {
  * console.log(result) // { a: 1, b: 4, c: 9, d: 16, e: 25 }
  * ```
  *
- * For maps, `map` applies the mapper function to the values of the entries.
+ * `map` applies the mapper function to the values of the entries of a map.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -168,7 +204,7 @@ const _map = function (value, f) {
  * console.log(result) // Map { 'a' => 1, 'b' => 4, 'c' => 9, 'd' => 16, 'e' => 25 }
  * ```
  *
- * For generators, `map` applies the mapper function lazily to each value of the iterator, creating a new iterator with transformed items.
+ * `map` applies the mapper function lazily to each value of a generator, creating a new generator with mapped items.
  *
  * ```javascript [playground]
  * const capitalize = string => string.toUpperCase()
@@ -185,7 +221,7 @@ const _map = function (value, f) {
  * console.log([...ABCGenerator]) // ['A', 'B', 'C']
  * ```
  *
- * For async generators, `map` applies the mapper function lazily to each value of the async generator, creating a new async generator with transformed items.
+ * `map` applies the mapper function lazily to each value of an async generator, creating a new async generator with mapped items.
  *
  * ```javascript [playground]
  * const capitalize = string => string.toUpperCase()
@@ -223,6 +259,17 @@ const _map = function (value, f) {
  * // [1, 4, 9, 16, 25]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map.entries](/docs/map.entries)
+ *  * [map.series](/docs/map.series)
+ *  * [map.pool](/docs/map.pool)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @execution concurrent
  *
  * @TODO streamMap
@@ -255,23 +302,49 @@ const _mapEntries = (value, f) => {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type EntriesMappable = Object|Map
+ * type FunctorWithEntries = Map|Object
  *
- * type Mapper = (
- *   value any,
- *   key string|any,
- *   collection EntriesMappable
- * )=>(resultItem Promise|any)
+ * type EntryMapper = (
+ *   entry [key string|any, value any],
+ * )=>(resultEntry Promise|[resultKey string|any, resultItem any])
  *
- * map.entries(value Promise|EntriesMappable, f Mapper)
- *   -> Promise|EntriesMappable
+ * map.entries(
+ *   value Promise|FunctorWithEntries,
+ *   mapper EntryMapper
+ * ) -> Promise|FunctorWithEntries
  *
- * map.entries(f Mapper)(value EntriesMappable)
- *   -> Promise|EntriesMappable
+ * map.entries(mapper EntryMapper)(value FunctorWithEntries)
+ *   -> Promise|FunctorWithEntries
  * ```
  *
  * @description
- * `map` over the entries rather than the values of a collection. Accepts collections of type `Map` or `Object`.
+ * `map` over the entries of a functor as opposed to the values.
+ *
+ * The following data types are considered to be functors with entries:
+ *   * `map`
+ *   * `object`
+ *
+ * The signature of the mapper function changes depending on the provided functor:
+ *
+ * If the functor is a map:
+ *
+ * ```coffeescript [specscript]
+ * mapper(entry [key any, value any]) -> resultEntry Promise|[
+ *   resultKey any,
+ *   resultValue any,
+ * ]
+ * ```
+ *
+ * If the functor is an object:
+ *
+ * ```coffeescript [specscript]
+ * mapper(entry [key string, value any]) -> resultEntry Promise|[
+ *   resultKey string,
+ *   resultValue any,
+ * ]
+ * ```
+ *
+ * `map.entries` works for objects and maps.
  *
  * ```javascript [playground]
  * const upperCaseKeysAndSquareValues =
@@ -296,6 +369,17 @@ const _mapEntries = (value, f) => {
  * // { a: 1, b: 4, c: 9 }
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [map.series](/docs/map.series)
+ *  * [map.pool](/docs/map.pool)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @since v1.7.0
  */
 map.entries = function mapEntries(arg0, arg1) {
@@ -351,16 +435,21 @@ const _mapSeries = function (collection, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Functor = Array|Object|Set|Map
+ * type MapSeriesFunctor = Array|Object|Set|Map
  *
  * type Mapper = (
  *   value any,
  *   indexOrKey number|string|any,
- *   f Functor
+ *   ftor MapSeriesFunctor,
  * )=>(mappedItem Promise|any)
  *
- * map.series(f Promise|Functor, f Mapper) -> result Functor
- * map.series(f Mapper)(f Functor) -> result Functor
+ * map.series(
+ *   ftor Promise|MapSeriesFunctor,
+ *   mapper Mapper
+ * ) -> result MapSeriesFunctor
+ *
+ * map.series(mapper Mapper)(ftor MapSeriesFunctor)
+ *   -> result MapSeriesFunctor
  * ```
  *
  * @description
@@ -387,6 +476,17 @@ const _mapSeries = function (collection, f) {
  * // [1, 4, 9, 16, 25]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [map.entries](/docs/map.entries)
+ *  * [map.pool](/docs/map.pool)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @execution series
  */
 map.series = function mapSeries(arg0, arg1) {
@@ -435,18 +535,24 @@ const _mapPool = function (f, concurrency, mapper) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Functor = Array|Object|Set|Map
+ * type MapPoolFunctor = Array|Object|Set|Map
+ *
+ * type Mapper = (
+ *   item any,
+ *   indexOrKey number|string|any,
+ *   ftor Functor
+ * )=>(resultItem Promise|any)
  *
  * map.pool(
+ *   ftor MapPoolFunctor,
  *   concurrency number,
- *   mapper (value any)=>Promise|any,
- * )(f Functor) -> result Promise|Array
+ *   mapper Mapper
+ * ) -> result Promise|Array
  *
  * map.pool(
- *   f Functor,
  *   concurrency number,
- *   mapper (value any)=>Promise|any,
- * ) -> result Promise|Array
+ *   mapper Mapper
+ * )(ftor MapPoolFunctor) -> result Promise|Array
  * ```
  *
  * @description
@@ -477,6 +583,17 @@ const _mapPool = function (f, concurrency, mapper) {
  * // [1, 4, 9, 16, 25]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [map.entries](/docs/map.entries)
+ *  * [map.series](/docs/map.series)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @TODO objectMapPool
  *
  * @execution concurrent

package/not.js

@@ -53,6 +53,13 @@ const _not = function (args, predicate) {
  *
  * not(Promise.resolve(3), isOdd).then(console.log) // false
  * ```
+ *
+ * See also:
+ *  * [some](/docs/some)
+ *  * [and](/docs/and)
+ *  * [or](/docs/or)
+ *  * [eq](/docs/eq)
+ *
  */
 
 const not = function (...args) {

package/omit.d.ts

@@ -14,8 +14,8 @@ export = omit;
  *
  * ```javascript [playground]
  * console.log(
- *   omit({ _id: '1', name: 'George' }, ['_id']),
- * ) // { name: 'George' }
+ *   omit({ _id: '1', name: 'John' }, ['_id']),
+ * ) // { name: 'John' }
  * ```
  *
  * `omit` supports three types of path patterns for nested property access

package/omit.js

@@ -30,8 +30,8 @@ const _omit = function (source, paths) {
  *
  * ```javascript [playground]
  * console.log(
- *   omit({ _id: '1', name: 'George' }, ['_id']),
- * ) // { name: 'George' }
+ *   omit({ _id: '1', name: 'John' }, ['_id']),
+ * ) // { name: 'John' }
  * ```
  *
  * `omit` supports three types of path patterns for nested property access
@@ -69,6 +69,15 @@ const _omit = function (source, paths) {
  * omit(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
  * // { c: 3 }
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [all](/docs/all)
+ *  * [assign](/docs/assign)
+ *  * [get](/docs/get)
+ *  * [set](/docs/set)
+ *  * [pick](/docs/pick)
+ *  * [forEach](/docs/forEach)
  */
 const omit = function (arg0, arg1) {
   if (arg1 == null) {

package/or.js

@@ -138,6 +138,12 @@ const areAnyPredicatesTruthy = function (args, predicates) {
  * ]).then(console.log) // true
  * ```
  *
+ * See also:
+ *  * [some](/docs/some)
+ *  * [and](/docs/and)
+ *  * [not](/docs/not)
+ *  * [eq](/docs/eq)
+ *
  * @execution series
  *
  * @note ...args slows down here by an order of magnitude

package/package.json

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

package/pick.js

@@ -69,6 +69,15 @@ const _pick = function (source, keys) {
  * pick(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
  * // { a: 1, b: 2 }
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [all](/docs/all)
+ *  * [assign](/docs/assign)
+ *  * [get](/docs/get)
+ *  * [set](/docs/set)
+ *  * [omit](/docs/omit)
+ *  * [forEach](/docs/forEach)
  */
 const pick = function (arg0, arg1) {
   if (arg1 == null) {

package/pipe.js

@@ -10,13 +10,19 @@ const __ = require('./_internal/placeholder')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * pipe(funcs Array<function>)(...args) -> result Promise|any
+ * funcs Array<function>
+ * args Array<any>
+ * argsWithPromises Array<Promise|any>
  *
- * pipe(...args, funcs Array<function>) -> result Promise|any
+ * pipe(funcs)(...args) -> result Promise|any
+ *
+ * pipe(...argsWithPromises, funcs Array<function>) -> result Promise|any
+ *
+ * pipe(...funcs)(...args) -> result Promise|any
  * ```
  *
  * @description
- * Creates a function pipeline from an array of functions, where each function passes its return value as a single argument to the next function until all functions have executed. The first function is called with the arguments to the pipeline, while the result of the pipeline execution is the return of its last function. If any function of the pipeline is asynchronous, the result of the execution is a Promise.
+ * Creates a function pipeline from multiple functions. Each function in the pipeline is evaluated in series, passing its return value as an argument to the next function. The result of a pipeline execution is the return value of the last function in the pipeline. If any function in the pipeline is asynchronous, the result of the pipeline execution is a Promise.
  *
  * ```javascript [playground]
  * const syncAdd123 = pipe([
@@ -36,6 +42,17 @@ const __ = require('./_internal/placeholder')
  * asyncAdd123(5).then(console.log) // 11
  * ```
  *
+ * `pipe` supports a mathematical API.
+ *
+ * ```javascript [playground]
+ * const appendB = x => x + 'b'
+ * const appendC = x => x + 'c'
+ *
+ * const appendBC = pipe(appendB, appendC)
+ *
+ * console.log(appendBC('a')) // 'abc'
+ * ```
+ *
  * When passed any amount of arguments before the array of functions, `pipe` executes eagerly; the array of functions is immediately invoked with the supplied arguments.
  *
  * ```javascript [playground]
@@ -54,6 +71,12 @@ const __ = require('./_internal/placeholder')
  * ])
  * ```
  *
+ * See also:
+ *  * [compose](/docs/compose)
+ *  * [tap](/docs/tap)
+ *  * [switchCase](/docs/switchCase)
+ *  * [tryCatch](/docs/tryCatch)
+ *
  * @execution series
  *
  * @transducing
@@ -61,6 +84,10 @@ const __ = require('./_internal/placeholder')
  * @since 1.6.0
  */
 const pipe = function (...args) {
+  if (typeof args[0] == 'function') {
+    return args.reduce(funcConcat)
+  }
+
   const funcs = args.pop()
   const pipeline = funcs.reduce(funcConcat)
 

package/reduce.js

@@ -3,17 +3,17 @@ const __ = require('./_internal/placeholder')
 const curry3 = require('./_internal/curry3')
 const genericReduce = require('./_internal/genericReduce')
 
-// _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)
 }
 
 /**
@@ -21,55 +21,110 @@ const _reduce = function (collection, reducer, initialValue) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Foldable = Iterable|AsyncIterable|Object<value any>
+ * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
  *
  * type Reducer = (
  *   accumulator any,
  *   item any,
- *   indexOrKey? number|string,
- *   f? Map|Foldable,
+ *   indexOrKey number|string|any,
+ *   fold Foldable
  * )=>(nextAccumulator Promise|any)
  *
- * type Resolver = (f Map|Foldable)=>Promise|any
+ * type Resolver = (fold Foldable)=>Promise|any
  *
  * reduce(
- *   f Map|Foldable,
+ *   fold Foldable,
  *   reducer Reducer,
- *   initialValue? Resolver|any
+ *   initial? Resolver|any
  * ) -> result Promise|any
  *
  * reduce(
  *   reducer Reducer,
- *   initialValue? Resolver|any
- * )(f Map|Foldable) -> result Promise|any
+ *   initial? Resolver|any
+ * )(fold Foldable) -> result Promise|any
  * ```
  *
  * @description
- * Reduces a map or foldable to a single value.
+ * Reduces a foldable to a single value.
  *
- * The following data types are considered foldables:
- *  * `iterable`
- *  * `async iterable`
- *  * `object`; only the values of the object are transformed
- *
- * The following data types are considered iterable:
+ * The following data types are considered to be foldables:
  *  * `array`
  *  * `set`
  *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .reduce method`
+ *  * `object`
  *
- * The reducing operation is dictated by a provided reducer function, which defines a transformation between the accumulator and a given item of the map or foldable.
+ * The reducing operation is dictated by a provided reducer function, which defines a transformation between the accumulator and a given item of the foldable.
  *
  * ```javascript
  * const reducer = function (accumulator, item) {
- *   const nextAccumulator = f(accumulator, item)
+ *   // nextAccumulator is the result of some operation between accumulator and item
+ *   // and becomes the accumulator for the next iteration and invocation of the reducer
  *   return nextAccumulator
- *   // nextAccumulator becomes the accumulator for the next iteration and invocation of the reducer
  * }
  * ```
  *
- * The result of the last invocation of the reducer is the result of the reducing operation. The reducer may be asynchronous and return a promise, in which case the promise is resolved for its value before continuing with the reducing operation.
+ * The reducer function signature changes depending on the provided foldable.
+ *
+ * If the foldable is an array:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any,
+ *   index number,
+ *   fold Array
+ * ) -> nextAccumulator Promise|any
+ * ```
+ *
+ * If the foldable is a set:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any
+ * ) -> nextAccumulator Promise|any
+ * ```
+ *
+ * If the foldable is a map:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any,
+ *   key any,
+ *   fold Map
+ * ) -> nextAccumulator Promise|any
+ * ```
+ *
+ * If the foldable is a generator:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any
+ * ) -> nextAccumulator Promise|any
+ * ```
+ *
+ * If the foldable is a async generator:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any
+ * ) -> nextAccumulator Promise|any
+ * ```
+ *
+ * If the foldable is an object with a `.reduce` method, the reducer function signature is defined externally.
  *
- * `reduce` executes a reducer function for each item of the array in order. If no initial value is provided, `reduce` uses the first item of the map or foldable as the initial value and starts iterating from the second item of the map or foldable.
+ * If the foldable is a plain object:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any,
+ *   key string,
+ *   fold Object
+ * ) -> nextAccumulator Promise|any
+ * ```
+ *
+ * `reduce` executes a reducer function for each item of the array in order. If no initial value is provided, `reduce` uses the first item of the foldable as the initial value and starts iterating from the second item of the foldable.
  *
  * ```javascript [playground]
  * const max = (a, b) => a > b ? a : b
@@ -78,7 +133,7 @@ const _reduce = function (collection, reducer, initialValue) {
  * console.log(result) // 5
  * ```
  *
- * If an initial value is provided, the accumulator starts as the initial value rather than the first item of the map or foldable.
+ * If an initial value is provided, the accumulator starts as the initial value rather than the first item of the foldable.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -87,7 +142,16 @@ const _reduce = function (collection, reducer, initialValue) {
  * console.log(result) // 15
  * ```
  *
- * If the initialization parameter is a function, it is treated as a resolver of the initial value and called with the map or foldable.
+ * If the reducer is asynchronous, all promises created by the reducer are resolved before continuing with the reducing operation.
+ *
+ * ```javascript [playground]
+ * const asyncAdd = async (a, b) => a + b
+ *
+ * const promise = reduce([1, 2, 3, 4, 5], asyncAdd, 0)
+ * promise.then(console.log) // 15
+ * ```
+ *
+ * If the initialization parameter is a function, it is treated as a resolver of the initial value and called with the foldable.
  *
  * ```javascript [playground]
  * const concatSquares = (array, value) => array.concat(value ** 2)
@@ -122,7 +186,7 @@ const _reduce = function (collection, reducer, initialValue) {
  * console.log(result) // 15
  * ```
  *
- * `reduce` works for async iterators.
+ * `reduce` works for async generators.
  *
  * ```javascript [playground]
  * const asyncAdd = async (a, b) => a + b
@@ -142,6 +206,23 @@ const _reduce = function (collection, reducer, initialValue) {
  * reduce(Promise.resolve([1, 2, 3, 4, 5]), add, 0).then(console.log) // 15
  * ```
  *
+ * Any promises passed for the initial value are also resolved before further execution.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * const promise = reduce([1, 2, 3, 4, 5], add, Promise.resolve(0))
+ * promise.then(console.log) // 15
+ * ```
+ *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [filter](/docs/filter)
+ *  * [transform](/docs/transform)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @execution series
  *
  * @transducing