rubico 2.6.5 → 2.7.0

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,155 +21,181 @@ const _reduce = function (collection, reducer, initialValue) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Foldable = Array|Object|Map|Iterator|AsyncIterator
+ * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
  *
  * type Reducer = (
  *   accumulator any,
- *   value any,
- *   indexOrKey? number|string,
- *   collection? Foldable,
+ *   item any,
+ *   indexOrKey number|string|any,
+ *   fold Foldable
  * )=>(nextAccumulator Promise|any)
  *
- * type Resolver = (collection Foldable)=>Promise|any
+ * type Resolver = (fold Foldable)=>Promise|any
  *
  * reduce(
- *   collection Foldable,
+ *   fold Foldable,
  *   reducer Reducer,
- *   initialValue? Resolver|any
+ *   initial? Resolver|any
  * ) -> result Promise|any
  *
  * reduce(
  *   reducer Reducer,
- *   initialValue? Resolver|any
- * )(collection Foldable) -> result Promise|any
+ *   initial? Resolver|any
+ * )(fold 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 foldable to a single value.
+ *
+ * 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 foldable.
+ *
+ * ```javascript
+ * const reducer = function (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
+ * }
+ * ```
  *
- *  * `Array`
- *  * `Object`
- *  * `Set`
- *  * `Map`
- *  * `Iterator`/`Generator`
- *  * `AsyncIterator`/`AsyncGenerator`
+ * The reducer function signature changes depending on the provided foldable.
  *
- * 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.
+ * If the foldable is an array:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any,
+ *   index number,
+ *   fold Array
+ * ) -> nextAccumulator Promise|any
+ * ```
  *
- * ```javascript [playground]
- * const max = (a, b) => a > b ? a : b
+ * If the foldable is a set:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any
+ * ) -> nextAccumulator Promise|any
+ * ```
  *
- * console.log(
- *   reduce([1, 3, 5, 4, 2], max)
- * ) // 5
+ * If the foldable is a map:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any,
+ *   key any,
+ *   fold Map
+ * ) -> nextAccumulator Promise|any
+ * ```
  *
- * console.log(
- *   reduce(max)([1, 3, 5, 4, 2])
- * ) // 5
+ * If the foldable is a generator:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any
+ * ) -> nextAccumulator Promise|any
  * ```
  *
- * If an optional initial value is provided, the result starts as the provided initial value rather than the first item of the collection.
+ * If the foldable is a async generator:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any
+ * ) -> nextAccumulator Promise|any
+ * ```
  *
- * ```javascript [playground]
- * const add = (a, b) => a + b
+ * If the foldable is an object with a `.reduce` method, the reducer function signature is defined externally.
  *
- * console.log(reduce([1, 2, 3, 4, 5], add, 0)) // 15
- * console.log(reduce(add, 0)([1, 2, 3, 4, 5])) // 15
+ * If the foldable is a plain object:
+ * ```coffeescript [specscript]
+ * reducer(
+ *   accumulator any,
+ *   item any,
+ *   key string,
+ *   fold Object
+ * ) -> nextAccumulator Promise|any
  * ```
  *
- * If the initialization parameter is a function, it is treated as a resolver and called with the arguments to resolve the initial value.
+ * `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 concatSquares = (array, value) => array.concat(value ** 2)
- *
- * const contrivedInitializer = array => [`initial length ${array.length}`]
- *
- * const array = [1, 2, 3, 4, 5]
+ * const max = (a, b) => a > b ? a : b
  *
- * 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]
+ * const result = reduce([1, 3, 5, 4, 2], max)
+ * console.log(result) // 5
  * ```
  *
- * 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.
+ * 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
  *
- * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+ * const result = reduce([1, 2, 3, 4, 5], add, 0)
+ * console.log(result) // 15
+ * ```
  *
- * console.log(
- *   reduce(obj, add)
- * ) // 15
+ * 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
  *
- * console.log(
- *   reduce(add)(obj)
- * ) // 15
+ * const promise = reduce([1, 2, 3, 4, 5], asyncAdd, 0)
+ * promise.then(console.log) // 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.
+ * 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 add = (a, b) => a + b
+ * const concatSquares = (array, value) => array.concat(value ** 2)
  *
- * const set = new Set([1, 2, 3, 4, 5])
+ * const contrivedInitializer = array => [`initial length ${array.length}`]
  *
- * console.log(
- *   reduce(set, add)
- * ) // 15
+ * const array = [1, 2, 3, 4, 5]
  *
- * console.log(
- *   reduce(add)(set)
- * ) // 15
+ * console.log(reduce(array, concatSquares, contrivedInitializer))
+ * // ['initial length 5', 1, 4, 9, 16, 25]
  * ```
  *
- * 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 objects, `reduce` iterates over just the values.
  *
  * ```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
+ * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
  *
- * console.log(
- *   reduce(add)(m)
- * ) // 15
+ * const result = reduce(obj, add)
+ * console.log(result) // 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.
+ * For maps, `reduce` iterates over the values of the entries.
  *
  * ```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
+ * const m = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
  *
- * 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 generators.
  *
  * ```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.
@@ -180,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

package/set.js

@@ -96,6 +96,15 @@ const _set = function (obj, path, value) {
  * set(Promise.resolve({}), 'a', 1).then(console.log) // { a: 1 }
  * ```
  *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [all](/docs/all)
+ *  * [assign](/docs/assign)
+ *  * [get](/docs/get)
+ *  * [pick](/docs/pick)
+ *  * [omit](/docs/omit)
+ *  * [forEach](/docs/forEach)
+ *
  * @since 1.7.0
  */
 

package/some.js

@@ -40,7 +40,7 @@ const _some = function (collection, predicate) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Foldable = Array|Iterable|AsyncIterable|{ reduce: function }|Object
+ * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
  *
  * some(collection Foldable, predicate function) -> Promise|boolean
  *
@@ -48,7 +48,7 @@ const _some = function (collection, predicate) {
  * ```
  *
  * @description
- * Test a predicate concurrently across all items of a collection, returning true if any executions return truthy.
+ * Test a predicate concurrently across all items of a foldable, returning true if any executions return true.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -58,7 +58,16 @@ const _some = function (collection, predicate) {
  * ) // true
  * ```
  *
- * The collection can be any iterable, async iterable, or object values iterable collection. Below is an example of `some` accepting an async generator as the collection.
+ * The following data types are considered to be foldables:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .reduce method`
+ *  * `object`
+ *
+ * `some` works for async generators.
  *
  * ```javascript [playground]
  * const toTodosUrl = id => 'https://jsonplaceholder.typicode.com/todos/' + id
@@ -98,6 +107,11 @@ const _some = function (collection, predicate) {
  * some(Promise.resolve([1, 2, 3, 4, 5]), n => n > 6).then(console.log) // false
  * ```
  *
+ * See also:
+ *  * [map](/docs/map)
+ *  * [every](/docs/every)
+ *  * [and](/docs/and)
+ *
  * @execution concurrent
  *
  * @muxing

package/switchCase.js

@@ -91,6 +91,12 @@ const curryArgs3 = require('./_internal/curryArgs3')
  * ]) // 1 + 2 + 3 == 6
  * ```
  *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [tap.if](/docs/tap.if)
+ *  * [tryCatch](/docs/tryCatch)
+ *  * [all](/docs/all)
+ *
  * @execution series
  */
 const switchCase = (...args) => {

package/tap.js

@@ -46,6 +46,13 @@ const _tap = function (args, f) {
  * ```javascript [playground]
  * tap(Promise.resolve(1), Promise.resolve(2), 3, console.log) // 1 2 3
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [compose](/docs/compose)
+ *  * [tap.if](/docs/tap.if)
+ *  * [switchCase](/docs/switchCase)
+ *  * [tryCatch](/docs/tryCatch)
  */
 const tap = function (...args) {
   const f = args.pop()
@@ -116,6 +123,13 @@ const _tapIf = function (predicate, f, args) {
  * tap.if(Promise.resolve(1), n => n < 5, console.log) // 1
  * tap.if(Promise.resolve(6), n => n < 5, console.log)
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [compose](/docs/compose)
+ *  * [tap](/docs/tap)
+ *  * [switchCase](/docs/switchCase)
+ *  * [tryCatch](/docs/tryCatch)
  */
 
 tap.if = function (...args) {

package/thunkify.js

@@ -22,6 +22,14 @@ const funcApply = require('./_internal/funcApply')
  *
  * console.log(thunkAdd12()) // 3
  * ```
+ *
+ * See also:
+ *  * [eq](/docs/eq)
+ *  * [always](/docs/always)
+ *  * [curry](/docs/curry)
+ *  * [__](/docs/__)
+ *  * [Transducer.map](/docs/Transducer.map)
+ *
  */
 const thunkify = (func, ...args) => function thunk() {
   if (areAnyValuesPromises(args)) {

package/transform.js

@@ -21,46 +21,106 @@ const _transform = function (collection, transducer, 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,
  *   value any,
- *   indexOrKey? number|string,
- *   collection? 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 = (fold Foldable)=>Promise|Semigroup
  *
  * transform(
- *   collection Foldable,
+ *   fold Foldable,
  *   transducer Transducer,
- *   initialValue? Transformable|TransformableResolver,
- * ) -> result Promise|Transformable
+ *   initial? Semigroup|SemigroupResolver,
+ * ) -> result Promise|Semigroup
  *
  * transform(
  *   transducer Transducer,
- *   initialValue? Transformable|TransformableResolver,
- * )(collection Foldable) -> result Promise|Transformable
+ *   initial? Semigroup|SemigroupResolver,
+ * )(fold 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 with [transducers](https://rubico.land/blog/transducers-crash-course-rubico-v2) into a semigroup.
  *
- *  * `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)`
- *  * `{ concat: function }`; concatenation defined by `result.concat(values)`
- *  * `{ write: function }`; concatenation defined by `result.write(item)`
- *  * `Object`; concatenation defined by `({ ...result, ...values })`
+ * The following data types are considered to be foldables:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .reduce method`
+ *  * `object`
  *
- * `transform` can transform any of the above collections into any of the other above collections.
+ * Transducers, due to their lazy nature, don't have knowledge of the foldable they are transforming. As such, the transducer signature for all foldables is the same:
+ *
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ * ```
+ *
+ * The following data types are considered to be semigroups:
+ *  * `array`
+ *  * `string`
+ *  * `set`
+ *  * `binary`
+ *  * `{ concat: function }`
+ *  * `{ write: function }`
+ *  * `object`
+ *
+ * The concatenation operation changes depending on the provided semigroup:
+ *
+ * If the semigroup is an array, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator.concat(values)
+ * ```
+ *
+ * If the semigroup is a string, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator + values
+ * ```
+ *
+ * If the semigroup is a set, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator.add(...values)
+ * ```
+ *
+ * If the semigroup is binary, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = new accumulator.constructor(accumulator.length + values.length)
+ * nextAccumulator.set(accumulator)
+ * nextAccumulator.set(values, accumulator.length)
+ * ```
+ *
+ * If the semigroup is an object with a `.concat` method, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator
+ * accumulator.concat(values)
+ * ```
+ *
+ * If the semigroup is an object with a `.write` method, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator
+ * accumulator.write(values)
+ * ```
+ *
+ * If the semigroup is a plain object, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = ({ ...accumulator, ...values })
+ * ```
+ *
+ * `transform` transforms numbers from an array into another array.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -74,26 +134,26 @@ const _transform = function (collection, transducer, initialValue) {
  *
  * // transform arrays into arrays
  * console.log(
- *   transform(squaredOdds, [])([1, 2, 3, 4, 5])
+ *   transform([1, 2, 3, 4, 5], squaredOdds, [])
  * ) // [1, 9, 25]
  *
  * // transform arrays into strings
  * console.log(
- *   transform(squaredOdds, '')([1, 2, 3, 4, 5])
+ *   transform([1, 2, 3, 4, 5], squaredOdds, '')
  * ) // '1925'
  *
  * // transform arrays into sets
  * console.log(
- *   transform(squaredOdds, new Set())([1, 2, 3, 4, 5])
+ *   transform([1, 2, 3, 4, 5], squaredOdds, new Set())
  * ) // Set (3) { 1, 9, 25 }
  *
  * // transform arrays into typed arrays
  * console.log(
- *   transform(squaredOdds, new Uint8Array())([1, 2, 3, 4, 5]),
+ *   transform([1, 2, 3, 4, 5], squaredOdds, new Uint8Array()),
  * ) // 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
@@ -105,7 +165,7 @@ const _transform = function (collection, transducer, initialValue) {
  *   },
  * }
  *
- * transform(Transducer.map(square), Stdout)([1, 2, 3, 4, 5])
+ * transform([1, 2, 3, 4, 5], Transducer.map(square), Stdout)
  * // 1
  * // 4
  * // 9
@@ -113,9 +173,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,40 +193,48 @@ 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
- * // ...
+ * ```
+ *
+ * If the initial value is a function it is treated as a resolver of the semigroup. The resolver may be asynchronous.
+ *
+ * ```javascript [playground]
+ * const promise = transform(
+ *   [1, 2, 3, 4, 5],
+ *   Transducer.map(number => number ** 2),
+ *   async () => ['a'],
+ * )
+ *
+ * promise.then(console.log)
  * ```
  *
  * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
  *
  * ```javascript [playground]
- * transform(
+ * const promise = transform(
  *   Promise.resolve([1, 2, 3, 4, 5]),
  *   Transducer.map(n => n ** 2),
  *   [],
- * ).then(console.log) // [1, 4, 9, 16, 25]
+ * )
+ *
+ * promise.then(console.log) // [1, 4, 9, 16, 25]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @execution series
  *
  * @transducing