rubico 2.6.5 → 2.7.0

package/map.js

@@ -93,93 +93,118 @@ const _map = function (value, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map|Iterator|AsyncIterator
+ * type Functor = Array|Set|Map|Generator|AsyncGenerator|{ map: function }|Object
  *
  * type Mapper = (
- *   value any,
+ *   item any,
  *   indexOrKey number|string|any,
- *   collection Mappable
+ *   ftor Functor
  * )=>(resultItem Promise|any)
  *
- * map(collection Promise|Mappable, f Mapper) -> result Promise|Mappable
- * map(f Mapper)(collection Mappable) -> result Promise|Mappable
+ * map(ftor Promise|Functor, mapper Mapper) -> result Promise|Functor
+ * map(mapper Mapper)(ftor Functor) -> result Promise|Functor
  * ```
  *
  * @description
- * Applies a synchronous or asynchronous mapper function `f` concurrently to each item of a collection, returning the results in a new collection of the same type. If order is implied by the collection, it is maintained in the result. `map` accepts the following collections:
+ * 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 to be functors:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .map method`
+ *  * `object`
+ *
+ * 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 a mapping from item
+ *   return resultItem
+ * }
+ * ```
  *
- *  * `Array`
- *  * `Object`
- *  * `Set`
- *  * `Map`
- *  * `Iterator`/`Generator`
- *  * `AsyncIterator`/`AsyncGenerator`
+ * The mapper function signature changes depending on the provided functor.
  *
- * With arrays (type `Array`), `map` applies the mapper function `f` to each item of the array, returning the transformed results in a new array ordered the same as the original array.
+ * If the functor is an array:
+ * ```coffeescript [specscript]
+ * mapper(item any, index number, ftor Array) -> resultItem Promise|any
+ * ```
  *
- * ```javascript [playground]
- * const square = number => number ** 2
+ * If the functor is a set:
+ * ```coffeescript [specscript]
+ * mapper(item any, item any, ftor Set) -> resultItem Promise|any
+ * ```
  *
- * const array = [1, 2, 3, 4, 5]
+ * 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
+ * ```
  *
- * console.log(
- *   map(array, square)
- * ) // [1, 4, 9, 16, 25]
+ * If the functor is an object with a `.map` method, the mapper function signature is defined externally.
  *
- * console.log(
- *   map(square)(array)
- * ) // [1, 4, 9, 16, 25]
+ * If the functor is a plain object:
+ * ```coffeescript [specscript]
+ * mapper(item any, key string, ftor Object) -> resultItem Promise|any
  * ```
  *
- * With objects (type `Object`), `map` applies the mapper function `f` to each value of the object, returning the transformed results as values in a new object ordered by the keys of the original object
+ * `map` works for arrays.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
  *
- * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+ * const array = [1, 2, 3, 4, 5]
+ *
+ * const result = map(array, square)
+ * console.log(result) // [1, 4, 9, 16, 25]
+ * ```
  *
- * console.log(
- *   map(square)(obj)
- * ) // { a: 1, b: 4, c: 9, d: 16, e: 25 }
+ * The mapper function may be asynchronous, in which case it is applied concurrently.
+ *
+ * ```javascript [playground]
+ * const asyncSquare = async number => number ** 2
+ *
+ * const array = [1, 2, 3, 4, 5]
  *
- * console.log(
- *   map(obj, square)
- * ) // { a: 1, b: 4, c: 9, d: 16, e: 25 }
+ * const promise = map(array, asyncSquare)
+ * promise.then(console.log) // [1, 4, 9, 16, 25]
  * ```
  *
- * With sets (type `Set`), `map` applies the mapper function `f` to each value of the set, returning the transformed results unordered in a new set.
+ * `map` applies the mapper function to just the values of an object.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
  *
- * const set = new Set([1, 2, 3, 4, 5])
- *
- * console.log(
- *   map(set, square)
- * ) // [1, 4, 9, 16, 25]
+ * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
  *
- * console.log(
- *   map(square)(set)
- * ) // [1, 4, 9, 16, 25]
+ * const result = map(obj, square)
+ * console.log(result) // { a: 1, b: 4, c: 9, d: 16, e: 25 }
  * ```
  *
- * With maps (type `Map`), `map` applies the mapper function `f` to each value of the map, returning the results at the same keys in a new map. The entries of the resulting map are in the same order as those of the original map
+ * `map` applies the mapper function to the values of the entries of a map.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
  *
  * const m = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
  *
- * console.log(
- *   map(square)(m)
- * ) // Map { 'a' => 1, 'b' => 4, 'c' => 9, 'd' => 16, 'e' => 25 }
- *
- * console.log(
- *   map(m, square)
- * ) // Map { 'a' => 1, 'b' => 4, 'c' => 9, 'd' => 16, 'e' => 25 }
+ * const result = map(m, square)
+ * console.log(result) // Map { 'a' => 1, 'b' => 4, 'c' => 9, 'd' => 16, 'e' => 25 }
  * ```
  *
- * With iterators (type `Iterator`) or generators (type `Generator`), `map` applies the mapper function `f` lazily to each value of the iterator/generator, creating a new iterator with transformed iterations.
+ * `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()
@@ -190,16 +215,13 @@ const _map = function (value, f) {
  *
  * const abcGenerator = abcGeneratorFunc()
  * const ABCGenerator = map(abcGeneratorFunc(), capitalize)
- * const ABCGenerator2 = map(capitalize)(abcGeneratorFunc())
  *
  * console.log([...abcGenerator]) // ['a', 'b', 'c']
  *
  * console.log([...ABCGenerator]) // ['A', 'B', 'C']
- *
- * console.log([...ABCGenerator2]) // ['A', 'B', 'C']
  * ```
  *
- * With asyncIterators (type `AsyncIterator`, or `AsyncGenerator`), `map` applies the mapper function `f` lazily to each value of the asyncIterator, creating a new asyncIterator with transformed iterations
+ * `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()
@@ -210,7 +232,6 @@ const _map = function (value, f) {
  *
  * const abcAsyncGenerator = abcAsyncGeneratorFunc()
  * const ABCGenerator = map(abcAsyncGeneratorFunc(), capitalize)
- * const ABCGenerator2 = map(capitalize)(abcAsyncGeneratorFunc())
  *
  * ;(async function () {
  *   for await (const letter of abcAsyncGenerator) {
@@ -226,13 +247,6 @@ const _map = function (value, f) {
  *     // B
  *     // C
  *   }
- *
- *   for await (const letter of ABCGenerator2) {
- *     console.log(letter)
- *     // A
- *     // B
- *     // C
- *   }
  * })()
  * ```
  *
@@ -245,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
@@ -277,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 =
@@ -318,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) {
@@ -334,15 +396,15 @@ map.entries = function mapEntries(arg0, arg1) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map
+ * type Functor = Array|Object|Set|Map
  *
  * type Mapper = (
  *   value any,
  *   indexOrKey number|string|any,
- *   collection Mappable
+ *   f Functor
  * )=>(mappedItem Promise|any)
  *
- * _mapSeries(collection Mappable, f Mapper) -> result Promise|Mappable
+ * _mapSeries(f Functor, f Mapper) -> result Promise|Functor
  * ```
  */
 const _mapSeries = function (collection, f) {
@@ -373,16 +435,21 @@ const _mapSeries = function (collection, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map
+ * type MapSeriesFunctor = Array|Object|Set|Map
  *
  * type Mapper = (
  *   value any,
  *   indexOrKey number|string|any,
- *   collection Mappable
+ *   ftor MapSeriesFunctor,
  * )=>(mappedItem Promise|any)
  *
- * map.series(collection Promise|Mappable, f Mapper) -> result Mappable
- * map.series(f Mapper)(collection Mappable) -> result Mappable
+ * map.series(
+ *   ftor Promise|MapSeriesFunctor,
+ *   mapper Mapper
+ * ) -> result MapSeriesFunctor
+ *
+ * map.series(mapper Mapper)(ftor MapSeriesFunctor)
+ *   -> result MapSeriesFunctor
  * ```
  *
  * @description
@@ -409,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) {
@@ -425,31 +503,31 @@ map.series = function mapSeries(arg0, arg1) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map
+ * type Functor = Array|Object|Set|Map
  *
- * _mapPool(collection Mappable, concurrency number, f function) -> result Promise|Mappable
+ * _mapPool(f Functor, concurrency number, mapper function) -> result Promise|Functor
  * ```
  */
-const _mapPool = function (collection, concurrency, f) {
-  if (isArray(collection)) {
-    return arrayMapPool(collection, concurrency, f)
+const _mapPool = function (f, concurrency, mapper) {
+  if (isArray(f)) {
+    return arrayMapPool(f, concurrency, mapper)
   }
-  if (collection == null) {
-    throw new TypeError(`invalid collection ${collection}`)
+  if (f == null) {
+    throw new TypeError(`invalid functor ${f}`)
   }
-  if (typeof collection == 'string' || collection.constructor == String) {
-    return stringMapPool(collection, concurrency, f)
+  if (typeof f == 'string' || f.constructor == String) {
+    return stringMapPool(f, concurrency, mapper)
   }
-  if (collection.constructor == Set) {
-    return setMapPool(collection, concurrency, f)
+  if (f.constructor == Set) {
+    return setMapPool(f, concurrency, mapper)
   }
-  if (collection.constructor == Map) {
-    return mapMapPool(collection, concurrency, f)
+  if (f.constructor == Map) {
+    return mapMapPool(f, concurrency, mapper)
   }
-  if (collection.constructor == Object) {
-    return objectMapPool(collection, concurrency, f)
+  if (f.constructor == Object) {
+    return objectMapPool(f, concurrency, mapper)
   }
-  throw new TypeError(`invalid collection ${collection}`)
+  throw new TypeError(`invalid functor ${f}`)
 }
 
 /**
@@ -457,18 +535,24 @@ const _mapPool = function (collection, concurrency, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = 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,
- * )(collection Mappable) -> result Promise|Array
+ *   mapper Mapper
+ * ) -> result Promise|Array
  *
  * map.pool(
- *   collection Mappable,
  *   concurrency number,
- *   mapper (value any)=>Promise|any,
- * ) -> result Promise|Array
+ *   mapper Mapper
+ * )(ftor MapPoolFunctor) -> result Promise|Array
  * ```
  *
  * @description
@@ -499,6 +583,17 @@ const _mapPool = function (collection, concurrency, f) {
  * // [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
@@ -517,15 +612,15 @@ map.pool = function mapPool(arg0, arg1, arg2) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map
+ * type Functor = Array|Object|Set|Map
  *
  * map.rate(
  *   rate number,
  *   f (value any)=>Promise|any,
- * )(collection Mappable) -> result Promise|Array
+ * )(f Functor) -> result Promise|Array
  *
  * map.rate(
- *   collection Mappable,
+ *   f Functor,
  *   rate number,
  *   f (value any)=>Promise|any,
  * ) -> result Promise|Array

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.5",
+  "version": "2.7.0",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "MIT",
@@ -115,7 +115,6 @@
     "async": "latest",
     "bluebird": "latest",
     "codecov": "^3.7.1",
-    "eslint": "^9.22.0",
     "fantasy-land": "latest",
     "lodash": "latest",
     "mocha": "^11.1.0",
@@ -129,7 +128,6 @@
   "scripts": {
     "test": "mocha test.js *.test.js */**.test.js",
     "test-coverage": "nyc mocha test.js x/*.test.js monad/*.test.js",
-    "lint": "eslint .",
     "build": "npm run dts && ./build",
     "bench": "./bench",
     "dts": "del *.d.ts _internal/*.d.ts x/*.d.ts && tsc"

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)