rubico 2.11.0 → 2.13.0

package/reduce.js

@@ -23,24 +23,44 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
  *
- * type SyncOrAsyncReducer = (
+ * type Reducer = (
  *   accumulator any,
- *   element any,
+ *   item any,
  *   indexOrKey number|string|any,
  *   foldable Foldable
  * )=>(nextAccumulator Promise|any)
  *
- * type UnarySyncOrAsyncResolver = any=>Promise|any
+ * type Resolver = any=>Promise|any
  *
- * reducer SyncOrAsyncReducer
- * initial UnarySyncOrAsyncResolver|any
+ * reduce(foldable Promise|Foldable, reducer Reducer) -> accumulator Promise|any
+ * reduce(foldable Promise|Foldable, reducer Reducer, initialValue Promise|any) -> accumulator Promise|any
+ * reduce(foldable Promise|Foldable, reducer Reducer, initialResolver Resolver) -> accumulator Promise|any
  *
- * reduce(foldable Promise|Foldable, reducer, initial?) -> result Promise|any
- * reduce(reducer, initial?)(foldable Foldable) -> result Promise|any
+ * reduce(reducer Reducer)(foldable Foldable) -> accumulator Promise|any
+ * reduce(reducer Reducer, initialValue Promise|any)(foldable Foldable) -> accumulator Promise|any
+ * reduce(reducer Reducer, initialResolver Resolver)(foldable Foldable) -> accumulator Promise|any
  * ```
  *
  * @description
- * Reduces a foldable to a single value.
+ * Reduces a foldable to an accumulated value.
+ *
+ * ```javascript [playground]
+ * const max = (a, b) => a > b ? a : b
+ *
+ * const result = reduce([1, 3, 5, 4, 2], max)
+ *
+ * console.log(result)
+ * ```
+ *
+ * `reduce` executes a reducer function for each item of a foldable in order. If an initial value is provided, `reduce` starts iterating from the first item of the foldable. 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 add = (a, b) => a + b
+ *
+ * const result = reduce([1, 2, 3, 4, 5], add, 10)
+ *
+ * console.log(result)
+ * ```
  *
  * The following data types are considered to be foldables:
  *  * `array`
@@ -51,11 +71,11 @@ const _reduce = function (collection, reducer, initial) {
  *  * `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 element of the foldable.
+ * The reducing operation is expressed by the reducer function and optional initial value, which defines a transformation between an accumulator and a given item of the foldable.
  *
  * ```javascript
- * const reducer = function (accumulator, element) {
- *   // nextAccumulator is the result of some operation between accumulator and element
+ * 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
  * }
@@ -67,7 +87,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   element any,
+ *   item any,
  *   index number,
  *   fold Array
  * ) -> nextAccumulator Promise|any
@@ -77,7 +97,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   element any
+ *   item any
  * ) -> nextAccumulator Promise|any
  * ```
  *
@@ -85,7 +105,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   element any,
+ *   item any,
  *   key any,
  *   fold Map
  * ) -> nextAccumulator Promise|any
@@ -95,7 +115,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   element any
+ *   item any
  * ) -> nextAccumulator Promise|any
  * ```
  *
@@ -103,47 +123,30 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   element any
+ *   item any
  * ) -> nextAccumulator Promise|any
  * ```
  *
- * If the foldable is an object with a `.reduce` method, the reducer function signature is defined externally.
- *
  * If the foldable is a plain object:
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   element any,
+ *   item any,
  *   key string,
  *   fold Object
  * ) -> nextAccumulator Promise|any
  * ```
  *
- * `reduce` executes a reducer function for each element of the array in order. If no initial value is provided, `reduce` uses the first element of the foldable as the initial value and starts iterating from the second element of the foldable.
- *
- * ```javascript [playground]
- * const max = (a, b) => a > b ? a : b
- *
- * const result = reduce([1, 3, 5, 4, 2], max)
- * console.log(result) // 5
- * ```
- *
- * If an initial value is provided, the accumulator starts as the initial value rather than the first element of the foldable.
- *
- * ```javascript [playground]
- * const add = (a, b) => a + b
- *
- * const result = reduce([1, 2, 3, 4, 5], add, 0)
- * console.log(result) // 15
- * ```
+ * If the foldable is an object with a `.reduce` method, the reducer function signature is defined externally.
  *
  * 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
+ * const result = await reduce([1, 2, 3, 4, 5], asyncAdd, 0)
+ *
+ * console.log(result)
  * ```
  *
  * If the initialization parameter is a function, it is treated as a resolver of the initial value and called with the foldable.
@@ -151,63 +154,53 @@ const _reduce = function (collection, reducer, initial) {
  * ```javascript [playground]
  * const concatSquares = (array, value) => array.concat(value ** 2)
  *
- * const contrivedInitializer = array => [`initial length ${array.length}`]
- *
  * const array = [1, 2, 3, 4, 5]
  *
- * console.log(reduce(array, concatSquares, contrivedInitializer))
- * // ['initial length 5', 1, 4, 9, 16, 25]
- * ```
- *
- * 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 }
+ * const result = reduce(array, concatSquares, () => [])
  *
- * const result = reduce(obj, add)
- * console.log(result) // 15
+ * console.log(result)
  * ```
  *
- * For maps, `reduce` iterates over the values of the entries.
+ * `reduce` iterates over just the values of objects and maps.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
  *
- * const m = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
+ * const object = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+ * const map = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
  *
- * const result = reduce(m, add)
- * console.log(result) // 15
+ * const objectResult = reduce(object, add)
+ * const mapResult = reduce(map, add)
+ *
+ * console.log(objectResult)
+ * console.log(mapResult)
  * ```
  *
- * `reduce` works for async generators.
+ * `reduce` reduces async generators.
  *
  * ```javascript [playground]
- * const asyncAdd = async (a, b) => a + b
+ * const add = (a, b) => a + b
  *
- * const asyncGenerate = async function* () {
+ * const generateAsyncNumbers = async function* () {
  *   yield 1; yield 2; yield 3; yield 4; yield 5
  * }
  *
- * reduce(asyncGenerate(), asyncAdd).then(console.log) // 15
+ * const result = await reduce(generateAsyncNumbers(), add)
+ *
+ * console.log(result)
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * If the foldable or initial value is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
  *
- * 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.
+ * const resultWithPromiseFoldable = await reduce(Promise.resolve([1, 2, 3, 4, 5]), add, 0)
  *
- * ```javascript [playground]
- * const add = (a, b) => a + b
+ * const resultWithPromiseInitialValue = await reduce([1, 2, 3, 4, 5], add, Promise.resolve(0))
  *
- * const promise = reduce([1, 2, 3, 4, 5], add, Promise.resolve(0))
- * promise.then(console.log) // 15
+ * console.log(resultWithPromiseFoldable)
+ * console.log(resultWithPromiseInitialValue)
  * ```
  *
  * See also:

package/some.js

@@ -41,23 +41,25 @@ const _some = function (collection, predicate) {
  * @synopsis
  * ```coffeescript [specscript]
  * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
- * type UnarySyncOrAsyncPredicate = any=>Promise|boolean
+ * type Predicate = any=>Promise|boolean
  *
- * predicate UnarySyncOrAsyncPredicate
+ * predicate Predicate
  *
- * some(foldable Foldable, predicate) -> Promise|boolean
- * some(predicate)(foldable Foldable) -> Promise|boolean
+ * some(foldable Promise|Foldable, predicate) -> testResult Promise|boolean
+ * some(predicate)(foldable Foldable) -> testResult Promise|boolean
  * ```
  *
  * @description
- * Test a predicate concurrently across all elements of a foldable, returning true if any executions return true.
+ * Tests a predicate concurrently across all items of a foldable. Returns true if any item tests true by the predicate.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
- * console.log(
- *   some([1, 2, 3, 4, 5], isOdd),
- * ) // true
+ * const array = [1, 2, 3, 4, 5]
+ *
+ * const arrayHasOddNumbers = some(array, isOdd)
+ *
+ * console.log(arrayHasOddNumbers)
  * ```
  *
  * The following data types are considered to be foldables:
@@ -69,44 +71,19 @@ const _some = function (collection, predicate) {
  *  * `object with .reduce method`
  *  * `object`
  *
- * `some` works for async generators.
- *
- * ```javascript [playground]
- * const toTodosUrl = id => 'https://jsonplaceholder.typicode.com/todos/' + id
- *
- * const fetchedToJson = fetched => fetched.json()
- *
- * const fetchTodo = pipe([
- *   toTodosUrl,
- *   fetch,
- *   fetchedToJson,
- * ])
- *
- * const todoIDsGenerator = async function* () {
- *   yield 1; yield 2; yield 3; yield 4; yield 5
- * }
- *
- * const promise = some(todoIDsGenerator(), async id => {
- *   const todo = await fetchTodo(id)
- *   return todo.title.startsWith('fugiat')
- * })
- *
- * promise.then(console.log) // true
- * ```
- *
  * `some` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe([1, 2, 3], [
  *   some(number => number < 5),
- *   console.log, // true
+ *   console.log,
  * ])
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * If the foldable is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * some(Promise.resolve([1, 2, 3, 4, 5]), n => n > 6).then(console.log) // false
+ * some(Promise.resolve([1, 2, 3, 4, 5]), n => n > 6).then(console.log)
  * ```
  *
  * See also:

package/switchCase.js

@@ -12,15 +12,15 @@ const curryArgs3 = require('./_internal/curryArgs3')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type SyncOrAsyncPredicate = (...arguments)=>Promise|boolean|any
- * type SyncOrAsyncFunction = (...arguments)=>Promise|any
+ * type Predicate = (...arguments)=>Promise|boolean|any
+ * type Function = (...arguments)=>Promise|any
  *
  * conditionalValues Array<Promise|boolean|any>
- * conditionalFunctionsOrValues Array<SyncOrAsyncPredicate|SyncOrAsyncFunction|Promise|boolean|any>
+ * conditionalFunctionsOrValues Array<Predicate|Function|Promise|boolean|any>
  *
- * switchCase(conditionalValues) -> Promise|any
- * switchCase(...arguments, conditionalFunctionsOrValues) -> Promise|any
- * switchCase(conditionalFunctionsOrValues)(...arguments) -> Promise|any
+ * switchCase(conditionalValues) -> result Promise|any
+ * switchCase(...arguments, conditionalFunctionsOrValues) -> result Promise|any
+ * switchCase(conditionalFunctionsOrValues)(...arguments) -> result Promise|any
  * ```
  *
  * @description
@@ -44,7 +44,7 @@ const curryArgs3 = require('./_internal/curryArgs3')
  * const fruitsGuesser = switchCase([
  *   fruit => fruit.color == 'yellow',
  *   fruit => fruit.name + ' is possibly a banana',
- *   fruit => fruit.name + ' is probably not a banana',
+ *   fruit => fruit.name + ' is possibly not a banana',
  * ])
  *
  * const guess1 = fruitsGuesser({ name: 'plantain', color: 'yellow' })
@@ -91,13 +91,13 @@ const curryArgs3 = require('./_internal/curryArgs3')
  *   (a, b, c) => console.log(`${a} + ${b} + ${c} !== 6`),
  * ])
  *
- * const promise = switchCase(true, [
+ * const result = await switchCase(true, [
  *   bool => bool,
  *   Promise.resolve(1),
  *   Promise.resolve(2),
  * ])
  *
- * promise.then(console.log)
+ * console.log(result)
  * ```
  *
  * See also:

package/tap.js

@@ -22,12 +22,10 @@ const _tap = function (args, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type SyncOrAsyncFunction = (...arguments)=>Promise|any
+ * type Function = (...arguments)=>Promise|any
  *
- * f SyncOrAsyncFunction
- *
- * tap(...arguments, f) -> Promise|arguments[0]
- * tap(f)(...arguments) -> Promise|arguments[0]
+ * tap(...arguments, f Function) -> result Promise|any
+ * tap(f Function)(...arguments) -> result Promise|any
  * ```
  *
  * @description
@@ -103,14 +101,11 @@ const _tapIf = function (predicate, f, args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type SyncOrAsyncPredicate = (...arguments)=>Promise|boolean|any
- * type SyncOrAsyncFunction = (...arguments)=>Promise|any
- *
- * predicate SyncOrAsyncPredicate
- * f SyncOrAsyncFunction
+ * type Predicate = (...arguments)=>Promise|boolean|any
+ * type Function = (...arguments)=>Promise|any
  *
- * tap.if(...arguments, predicate, f) -> Promise|arguments[0]
- * tap.if(predicate, f)(...arguments) -> Promise|arguments[0]
+ * tap.if(...arguments, predicate Predicate, f Function) -> result Promise|any
+ * tap.if(predicate Predicate, f Function)(...arguments) -> result Promise|any
  * ```
  *
  * @description

package/thunkify.js

@@ -23,20 +23,28 @@ function _thunkifyArgs(func, context, args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- *
- * thunkify(func function, ...args) -> thunk ()=>func(...args)
+ * thunkify(func function, ...arguments) -> thunk function
  * ```
  *
  * @description
- * Creates a thunk from a function and arguments. A thunk takes no arguments, and when called, executes the other function with the arguments. The other function is said to be "thunkified".
+ * Creates a thunk function from a function and arguments. A thunk function takes no arguments, and when called, executes the function and arguments. The function is said to be "thunkified".
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
  *
  * const thunkAdd12 = thunkify(add, 1, 2)
  *
- * console.log(thunkAdd12()) // 3
+ * console.log(thunkAdd12())
+ * ```
+ *
+ * Any promises in `arguments` are resolved for their values during thunk creation.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * const thunkAdd12 = await thunkify(add, Promise.resolve(1), 2)
+ *
+ * console.log(thunkAdd12())
  * ```
  *
  * See also:
@@ -60,13 +68,35 @@ const thunkify = function thunkify(func, ...args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- *
- * thunkify.call(func function, context object, ...args) -> thunk ()=>func(...args)
+ * thunkify.call(func function, context object, ...arguments) -> thunk function
  * ```
  *
  * @description
- * Creates a thunk that calls a function with the specified context and arguments.
+ * Creates a thunk function that calls a function with the specified context and arguments.
+ *
+ * ```javascript [playground]
+ * class Point {
+ *   constructor(x, y) {
+ *     this.x = x
+ *     this.y = y
+ *   }
+ *
+ *   distanceTo(point) {
+ *     const x2 = (point.x - this.x) ** 2
+ *     const y2 = (point.y - this.y) ** 2
+ *     return (x2 + y2) ** 0.5
+ *   }
+ * }
+ *
+ * const point0 = new Point(0, 0)
+ * const point1 = new Point(3, 4)
+ *
+ * const thunk = thunkify.call(point0.distanceTo, point0, point1)
+ *
+ * console.log(thunk())
+ * ```
+ *
+ * Any promises in `arguments` are resolved for their values during thunk creation.
  *
  * ```javascript [playground]
  * class Point {
@@ -75,7 +105,7 @@ const thunkify = function thunkify(func, ...args) {
  *     this.y = y
  *   }
  *
- *   distanceTo() {
+ *   distanceTo(point) {
  *     const x2 = (point.x - this.x) ** 2
  *     const y2 = (point.y - this.y) ** 2
  *     return (x2 + y2) ** 0.5
@@ -83,9 +113,9 @@ const thunkify = function thunkify(func, ...args) {
  * }
  *
  * const point0 = new Point(0, 0)
- * const point = new Point(3, 4)
+ * const point1 = new Point(3, 4)
  *
- * const thunk = thunkify.call(point0.distanceTo, point0, point)
+ * const thunk = await thunkify.call(point0.distanceTo, point0, Promise.resolve(point1))
  *
  * console.log(thunk())
  * ```

package/transform.js

@@ -22,23 +22,55 @@ const _transform = function (collection, transducer, initialValue) {
  * @synopsis
  * ```coffeescript [specscript]
  * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
- * type SyncOrAsyncReducer = (accumulator any, value any)=>(nextAccumulator Promise|any)
- * type Transducer = SyncOrAsyncReducer=>SyncOrAsyncReducer
+ * type Reducer = (accumulator any, value any)=>(nextAccumulator Promise|any)
+ * type Transducer = Reducer=>Reducer
  *
- * type Semigroup =
- *   Array|String|Set|TypedArray|{ concat: function }|{ write: function }|Object
+ * type Semigroup = Array|String|Set|TypedArray|{ concat: function }|{ write: function }|Object
  *
- * type UnarySyncOrAsyncSemigroupResolver = any=>Promise|Semigroup
+ * type SemigroupResolver = any=>Promise|Semigroup
  *
- * transducer Transducer
- * initial UnarySyncOrAsyncSemigroupResolver|Semigroup
+ * transform(foldable Promise|Foldable, transducer, initialValue Promise|any) -> result Promise|Semigroup
+ * transform(foldable Promise|Foldable, transducer, initialResolver SemigroupResolver) -> result Promise|Semigroup
  *
- * transform(foldable Promise|Foldable, transducer, initial?) -> result Promise|Semigroup
- * transform(transducer, initial?)(foldable Foldable) -> result Promise|Semigroup
+ * transform(transducer, initialValue Promise|any)(foldable Foldable) -> result Promise|Semigroup
+ * transform(transducer, initialResolver SemigroupResolver)(foldable Foldable) -> result Promise|Semigroup
  * ```
  *
  * @description
- * Transforms a foldable with [transducers](https://rubico.land/blog/transducers-crash-course-rubico-v2) into a semigroup.
+ * Transforms a foldable into a semigroup with a [transducer](https://rubico.land/blog/transducers-crash-course-rubico-v2).
+ *
+ * ```javascript [playground]
+ * const square = number => number ** 2
+ *
+ * const isOdd = number => number % 2 == 1
+ *
+ * const squaredOdds = compose([
+ *   Transducer.filter(isOdd),
+ *   Transducer.map(square),
+ * ])
+ *
+ * const array = [1, 2, 3, 4, 5]
+ *
+ * // transform arrays into arrays
+ * const squaredOddsArray = transform(array, squaredOdds, [])
+ * console.log('array into array')
+ * console.log(squaredOddsArray)
+ *
+ * // transform arrays into strings
+ * const squaredOddsString = transform(array, squaredOdds, '')
+ * console.log('array into string')
+ * console.log(squaredOddsString)
+ *
+ * // transform arrays into sets
+ * const squaredOddsSet = transform(array, squaredOdds, new Set())
+ * console.log('array into set')
+ * console.log(squaredOddsSet)
+ *
+ * // transform arrays into typed arrays
+ * const squaredOddsUint8Array = transform(array, squaredOdds, new Uint8Array())
+ * console.log('array into binary')
+ * console.log(squaredOddsUint8Array)
+ * ```
  *
  * The following data types are considered to be foldables:
  *  * `array`
@@ -49,11 +81,11 @@ const _transform = function (collection, transducer, initialValue) {
  *  * `object with .reduce method`
  *  * `object`
  *
- * 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:
+ * The transducer defines the transformation done by `transform`. In a transformation, each item of the foldable is processed by the transducer in series.
  *
  * ```coffeescript [specscript]
- * type SyncOrAsyncReducer = (accumulator any, value any)=>(nextAccumulator Promise|any)
- * type Transducer = SyncOrAsyncReducer=>SyncOrAsyncReducer
+ * type Reducer = (accumulator any, value any)=>(nextAccumulator Promise|any)
+ * type Transducer = Reducer=>Reducer
  * ```
  *
  * The following data types are considered to be semigroups:
@@ -106,40 +138,7 @@ const _transform = function (collection, transducer, initialValue) {
  * nextAccumulator = ({ ...accumulator, ...values })
  * ```
  *
- * `transform` transforms numbers from an array into another array.
- *
- * ```javascript [playground]
- * const square = number => number ** 2
- *
- * const isOdd = number => number % 2 == 1
- *
- * const squaredOdds = compose([
- *   Transducer.filter(isOdd),
- *   Transducer.map(square),
- * ])
- *
- * // transform arrays into arrays
- * console.log(
- *   transform([1, 2, 3, 4, 5], squaredOdds, [])
- * ) // [1, 9, 25]
- *
- * // transform arrays into strings
- * console.log(
- *   transform([1, 2, 3, 4, 5], squaredOdds, '')
- * ) // '1925'
- *
- * // transform arrays into sets
- * console.log(
- *   transform([1, 2, 3, 4, 5], squaredOdds, new Set())
- * ) // Set (3) { 1, 9, 25 }
- *
- * // transform arrays into typed arrays
- * console.log(
- *   transform([1, 2, 3, 4, 5], squaredOdds, new Uint8Array()),
- * ) // Uint8Array(3) [ 1, 9, 25 ]
- * ```
- *
- * `transform` transforms arrays into objects that implement `.concat`.
+ * Any object that implements concat may be used as the semigroup for `transform`.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -152,14 +151,9 @@ const _transform = function (collection, transducer, initialValue) {
  * }
  *
  * transform([1, 2, 3, 4, 5], Transducer.map(square), Stdout)
- * // 1
- * // 4
- * // 9
- * // 16
- * // 25
  * ```
  *
- * `transform` transforms an async generator into `process.stdout`, a Node.js writable stream that implements `.write`.
+ * Node.js `process.stdout`, a writable stream (implements the `write` method), may be used as the semigroup for `transform`
  *
  * ```javascript
  * const { pipe, compose, transform } = rubico
@@ -189,28 +183,35 @@ const _transform = function (collection, transducer, initialValue) {
  * )
  * ```
  *
- * If the initial value is a function it is treated as a resolver of the semigroup. The resolver may be asynchronous.
+ * 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(
+ * const result = await transform(
  *   [1, 2, 3, 4, 5],
  *   Transducer.map(number => number ** 2),
- *   async () => ['a'],
+ *   async () => []
  * )
  *
- * promise.then(console.log)
+ * console.log(result)
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * If the foldable or initial value is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * const promise = transform(
+ * const resultFromPromiseFoldable = await transform(
  *   Promise.resolve([1, 2, 3, 4, 5]),
  *   Transducer.map(n => n ** 2),
- *   [],
+ *   []
  * )
  *
- * promise.then(console.log) // [1, 4, 9, 16, 25]
+ * const resultFromPromiseSemigroup = await transform(
+ *   [1, 2, 3, 4, 5],
+ *   Transducer.map(n => n ** 2),
+ *   Promise.resolve([])
+ * )
+  *
+ * console.log(resultFromPromiseFoldable)
+ * console.log(resultFromPromiseSemigroup)
  * ```
  *
  * See also: