rubico 2.6.5 → 2.6.6

package/map.js

@@ -93,93 +93,82 @@ const _map = function (value, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map|Iterator|AsyncIterator
+ * type Functor = Array|Object|Set|Generator|AsyncGenerator
  *
  * type Mapper = (
- *   value any,
+ *   item any,
  *   indexOrKey number|string|any,
- *   collection Mappable
+ *   f Map|Functor
  * )=>(resultItem Promise|any)
  *
- * map(collection Promise|Mappable, f Mapper) -> result Promise|Mappable
- * map(f Mapper)(collection Mappable) -> result Promise|Mappable
+ * map(f Promise|Map|Functor, mapper Mapper) -> result Promise|Map|Functor
+ * map(mapper Mapper)(f Map|Functor) -> result Promise|Map|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 transformed items. The order of the items is maintained.
+ *
+ * The following data types are considered functors:
+ *  * `array`
+ *  * `object`
+ *  * `set`
+ *  * `iterator`
+ *  * `async iterator`
  *
- *  * `Array`
- *  * `Object`
- *  * `Set`
- *  * `Map`
- *  * `Iterator`/`Generator`
- *  * `AsyncIterator`/`AsyncGenerator`
+ * The mapper function defines the transformation of a given item in 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.
+ * ```javascript
+ * const mapper = function (item) {
+ *   // resultItem is the result of some operation on item
+ *   return resultItem
+ * }
+ * ```
+ *
+ * `map` works for arrays.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
  *
  * const array = [1, 2, 3, 4, 5]
  *
- * console.log(
- *   map(array, square)
- * ) // [1, 4, 9, 16, 25]
- *
- * console.log(
- *   map(square)(array)
- * ) // [1, 4, 9, 16, 25]
+ * const result = map(array, square)
+ * console.log(result) // [1, 4, 9, 16, 25]
  * ```
  *
- * 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
+ * The mapper function may be asynchronous, in which case it is applied concurrently.
  *
  * ```javascript [playground]
- * const square = number => number ** 2
+ * const asyncSquare = async number => number ** 2
  *
- * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
- *
- * console.log(
- *   map(square)(obj)
- * ) // { a: 1, b: 4, c: 9, d: 16, e: 25 }
+ * 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.
+ * For objects, `map` applies the mapper function to just the values.
  *
  * ```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
+ * For maps, `map` applies the mapper function to the values of the entries.
  *
  * ```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.
+ * For generators, `map` applies the mapper function lazily to each value of the iterator, creating a new iterator with transformed items.
  *
  * ```javascript [playground]
  * const capitalize = string => string.toUpperCase()
@@ -190,16 +179,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
+ * For async generators, `map` applies the mapper function lazily to each value of the async generator, creating a new async generator with transformed items.
  *
  * ```javascript [playground]
  * const capitalize = string => string.toUpperCase()
@@ -210,7 +196,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 +211,6 @@ const _map = function (value, f) {
  *     // B
  *     // C
  *   }
- *
- *   for await (const letter of ABCGenerator2) {
- *     console.log(letter)
- *     // A
- *     // B
- *     // C
- *   }
  * })()
  * ```
  *
@@ -334,15 +312,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 +351,16 @@ const _mapSeries = function (collection, f) {
  *
  * @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)
  *
- * map.series(collection Promise|Mappable, f Mapper) -> result Mappable
- * map.series(f Mapper)(collection Mappable) -> result Mappable
+ * map.series(f Promise|Functor, f Mapper) -> result Functor
+ * map.series(f Mapper)(f Functor) -> result Functor
  * ```
  *
  * @description
@@ -425,31 +403,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,15 +435,15 @@ const _mapPool = function (collection, concurrency, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Mappable = Array|Object|Set|Map
+ * type Functor = Array|Object|Set|Map
  *
  * map.pool(
  *   concurrency number,
  *   mapper (value any)=>Promise|any,
- * )(collection Mappable) -> result Promise|Array
+ * )(f Functor) -> result Promise|Array
  *
  * map.pool(
- *   collection Mappable,
+ *   f Functor,
  *   concurrency number,
  *   mapper (value any)=>Promise|any,
  * ) -> result Promise|Array
@@ -517,15 +495,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "2.6.5",
+  "version": "2.6.6",
   "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/reduce.js

@@ -21,19 +21,19 @@ const _reduce = function (collection, reducer, initialValue) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Foldable = Array|Object|Map|Iterator|AsyncIterator
+ * type Foldable = Iterable|AsyncIterable|Object<value any>
  *
  * type Reducer = (
  *   accumulator any,
- *   value any,
+ *   item any,
  *   indexOrKey? number|string,
- *   collection? Foldable,
+ *   f? Map|Foldable,
  * )=>(nextAccumulator Promise|any)
  *
- * type Resolver = (collection Foldable)=>Promise|any
+ * type Resolver = (f Map|Foldable)=>Promise|any
  *
  * reduce(
- *   collection Foldable,
+ *   f Map|Foldable,
  *   reducer Reducer,
  *   initialValue? Resolver|any
  * ) -> result Promise|any
@@ -41,43 +41,53 @@ const _reduce = function (collection, reducer, initialValue) {
  * reduce(
  *   reducer Reducer,
  *   initialValue? Resolver|any
- * )(collection Foldable) -> result Promise|any
+ * )(f Map|Foldable) -> result Promise|any
  * ```
  *
  * @description
- * Transforms a collection based on a reducer function and optional initial value. In a reducing operation, the result is defined in the beginning as either the initial value if supplied or the first item of the collection. The reducing operation then iterates through the remaining items in the collection, executing the reducer at each iteration to return the result to be used in the next iteration. The final result is the result of the execution of the reducer at the last item of the iteration. `reduce` accepts the following collections:
+ * Reduces a map or foldable to a single value.
  *
- *  * `Array`
- *  * `Object`
- *  * `Set`
- *  * `Map`
- *  * `Iterator`/`Generator`
- *  * `AsyncIterator`/`AsyncGenerator`
+ * The following data types are considered foldables:
+ *  * `iterable`
+ *  * `async iterable`
+ *  * `object`; only the values of the object are transformed
  *
- * For arrays (type `Array`), `reduce` executes the reducer function for each item of the array in order, returning a new result at each execution to be used in the next execution. On each iteration, the reducer is passed the accumulator, the item of the iteration, the index of the item in the array, and a reference to the original array.
+ * The following data types are considered iterable:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *
+ * 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.
+ *
+ * ```javascript
+ * const reducer = function (accumulator, item) {
+ *   const nextAccumulator = f(accumulator, item)
+ *   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.
+ *
+ * `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.
  *
  * ```javascript [playground]
  * const max = (a, b) => a > b ? a : b
  *
- * console.log(
- *   reduce([1, 3, 5, 4, 2], max)
- * ) // 5
- *
- * console.log(
- *   reduce(max)([1, 3, 5, 4, 2])
- * ) // 5
+ * const result = reduce([1, 3, 5, 4, 2], max)
+ * console.log(result) // 5
  * ```
  *
- * If an optional initial value is provided, the result starts as the provided initial value rather than the first item of the collection.
+ * If an initial value is provided, the accumulator starts as the initial value rather than the first item of the map or foldable.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
  *
- * console.log(reduce([1, 2, 3, 4, 5], add, 0)) // 15
- * console.log(reduce(add, 0)([1, 2, 3, 4, 5])) // 15
+ * const result = reduce([1, 2, 3, 4, 5], add, 0)
+ * console.log(result) // 15
  * ```
  *
- * If the initialization parameter is a function, it is treated as a resolver and called with the arguments to resolve the initial value.
+ * If the initialization parameter is a function, it is treated as a resolver of the initial value and called with the map or foldable.
  *
  * ```javascript [playground]
  * const concatSquares = (array, value) => array.concat(value ** 2)
@@ -86,90 +96,42 @@ const _reduce = function (collection, reducer, initialValue) {
  *
  * const array = [1, 2, 3, 4, 5]
  *
- * console.log(reduce(concatSquares, contrivedInitializer)(array))
- * // ['initial length 5', 1, 4, 9, 16, 25]
  * console.log(reduce(array, concatSquares, contrivedInitializer))
  * // ['initial length 5', 1, 4, 9, 16, 25]
  * ```
  *
- * For objects (type `Object`), `reduce` executes the reducer function for each value of the object. On each iteration, the reducer is passed the accumulator, the object value, the key of the object value, and a reference to the original object.
+ * For objects, `reduce` iterates over just the values.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
  *
  * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
  *
- * console.log(
- *   reduce(obj, add)
- * ) // 15
- *
- * console.log(
- *   reduce(add)(obj)
- * ) // 15
+ * const result = reduce(obj, add)
+ * console.log(result) // 15
  * ```
  *
- * For sets (type `Set`), `reduce` executes the reducer function for each item of the set. On each iteration, the reducer is passed the accumulator and item of the set.
- *
- * ```javascript [playground]
- * const add = (a, b) => a + b
- *
- * const set = new Set([1, 2, 3, 4, 5])
- *
- * console.log(
- *   reduce(set, add)
- * ) // 15
- *
- * console.log(
- *   reduce(add)(set)
- * ) // 15
- * ```
- *
- * For maps (type `Map`), `reduce` executes the reducer function for each value of each entry of the map. On each iteration, the reducer is passed the accumulator, the map item, the key of the map item, and a reference to the original map.
+ * For maps, `reduce` iterates over the values of the entries.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
  *
  * const m = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
  *
- * console.log(
- *   reduce(m, add)
- * ) // 15
- *
- * console.log(
- *   reduce(add)(m)
- * ) // 15
- * ```
- *
- * For iterators (type `Iterator`) and generators (type `Generator`), `reduce` executes the reducer function for each value of the iterator/generator. On each iteration, the reducer is passed the accumulator and the item of the iteration. The iterator/generator is consumed in the process.
- *
- * ```javascript [playground]
- * const add = (a, b) => a + b
- *
- * const generate12345 = function* () {
- *   yield 1; yield 2; yield 3; yield 4; yield 5
- * }
- *
- * console.log(
- *   reduce(generate12345(), add)
- * ) // 15
- *
- * console.log(
- *   reduce(add)(generate12345())
- * ) // 15
+ * const result = reduce(m, add)
+ * console.log(result) // 15
  * ```
  *
- * For asyncIterators (type `AsyncIterator`) and asyncGenerators (type `AsyncGenerator`), `reduce` executes the reducer function for each value of the asyncIterator/asyncGenerator. On each iteration, the reducer is passed the accumulator and the item of the async iteration. The asyncIterator/asyncGenerator is consumed in the process.
+ * `reduce` works for async iterators.
  *
  * ```javascript [playground]
  * const asyncAdd = async (a, b) => a + b
  *
- * const asyncGenerate12345 = async function* () {
+ * const asyncGenerate = async function* () {
  *   yield 1; yield 2; yield 3; yield 4; yield 5
  * }
  *
- * reduce(asyncGenerate12345(), asyncAdd).then(console.log) // 15
- *
- * reduce(asyncAdd)(asyncGenerate12345()).then(console.log) // 15
+ * reduce(asyncGenerate(), asyncAdd).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.

package/transform.js

@@ -26,39 +26,45 @@ const _transform = function (collection, transducer, initialValue) {
  * type Reducer = (
  *   accumulator any,
  *   value any,
- *   indexOrKey? number|string,
- *   collection? Foldable,
+ *   indexOrKey number|string,
+ *   f Foldable,
  * )=>(nextAccumulator Promise|any)
  *
  * type Transducer = Reducer=>Reducer
  *
- * type Transformable =
+ * type Semigroup =
  *   Array|String|Set|TypedArray|{ concat: function }|{ write: function }|Object
  *
- * type TransformableResolver = (collection Foldable)=>Promise|Transformable
+ * type SemigroupResolver = (f Foldable)=>Promise|Semigroup
  *
  * transform(
- *   collection Foldable,
+ *   f Foldable,
  *   transducer Transducer,
- *   initialValue? Transformable|TransformableResolver,
- * ) -> result Promise|Transformable
+ *   initialValue? Semigroup|SemigroupResolver,
+ * ) -> result Promise|Semigroup
  *
  * transform(
  *   transducer Transducer,
- *   initialValue? Transformable|TransformableResolver,
- * )(collection Foldable) -> result Promise|Transformable
+ *   initialValue? Semigroup|SemigroupResolver,
+ * )(f Foldable) -> result Promise|Semigroup
  * ```
  *
  * @description
- * Transforms a transformable collection into any other transformable collection. The type of transformation depends on the collection provided by the initial value. If the initial is a function it is used as a resolver for the provided collection. `transform` accepts transformable collections, or collections that support a concatenation operation:
+ * Transforms a foldable into a semigroup. The type of transformation depends on the type of semigroup provided as the initial value. If the initial value is a function it is treated as a resolver of the semigroup.
  *
- *  * `Array`; concatenation defined by `result.concat(values)`
+ * 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 semigroups:
+ *  * `array`; concatenation defined by `result.concat(values)`
  *  * `string`; concatenation defined by `result + values`
- *  * `Set`; concatenation defined by `result.add(...values)`
- *  * `TypedArray`; concatenation defined by `result.set(prevResult); result.set(values, offset)`
+ *  * `set`; concatenation defined by `result.add(...values)`
+ *  * `binary`; concatenation defined by `result.set(prevResult); result.set(values, offset)`
  *  * `{ concat: function }`; concatenation defined by `result.concat(values)`
  *  * `{ write: function }`; concatenation defined by `result.write(item)`
- *  * `Object`; concatenation defined by `({ ...result, ...values })`
+ *  * `object`; concatenation defined by `({ ...result, ...values })`
  *
  * `transform` can transform any of the above collections into any of the other above collections.
  *
@@ -93,7 +99,7 @@ const _transform = function (collection, transducer, initialValue) {
  * ) // Uint8Array(3) [ 1, 9, 25 ]
  * ```
  *
- * `transform` arrays into objects that implement `.concat`.
+ * `transform` transforms arrays into objects that implement `.concat`.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -113,9 +119,9 @@ const _transform = function (collection, transducer, initialValue) {
  * // 25
  * ```
  *
- * `transform` an async generator into `process.stdout`, a Node.js writable stream that implements `.write`.
+ * `transform` transforms an async generator into `process.stdout`, a Node.js writable stream that implements `.write`.
  *
- * ```javascript [playground]
+ * ```javascript
  * const { pipe, compose, transform } = rubico
  * // global Transducer
  *
@@ -133,28 +139,14 @@ const _transform = function (collection, transducer, initialValue) {
  *   }
  * }
  *
- * const Stdout = {
- *   concat(...args) {
- *     console.log(...args)
- *     return this
- *   },
- * }
- *
  * transform(
  *   streamRandomInts(10),
  *   compose([
  *     Transducer.map(square),
  *     Transducer.map(toString),
  *   ]),
- *   Stdout,
+ *   process.stdout // 2893600784289441449001600409684644624324923044411225
  * )
- * // 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.