rubico 2.11.0 → 2.12.1

package/or.js

@@ -97,37 +97,28 @@ const areAnyPredicatesTruthy = function (args, predicates) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
+ * type SyncOrAsyncPredicate = (...arguments)=>Promise|boolean|any
  *
- * type SyncOrAsyncPredicate = (...args)=>Promise|boolean|any
- *
- * predicatesOrValues Array<SyncOrAsyncPredicate|boolean|any>
- *
- * or(values Array<boolean|any>) -> result boolean
- * or(...argsOrPromises, predicatesOrValues) -> Promise|boolean
- * or(predicatesOrValues)(...args) -> Promise|boolean
+ * or(values Array<boolean|any>) -> testResult boolean
+ * or(...arguments, predicatesOrValues Array<SyncOrAsyncPredicate|boolean|any>) -> testResult Promise|boolean
+ * or(predicatesOrValues Array<SyncOrAsyncPredicate|boolean|any>)(...arguments) -> testResult Promise|boolean
  * ```
  *
  * @description
- * Function equivalent to the [Logical OR](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_OR) operator. Tests arrays of predicate functions, promises, values, or a mix thereof.
- *
- * If provided an array of boolean values, `or` returns true if any boolean values are truthy.
+ * Logical operator. Tests an array of predicate functions, promises, or values, returning true if any predicate tests true or any value is truthy.
  *
  * ```javascript [playground]
- * const oneIsLessThanZero = 1 < 0
- * const oneIsGreaterThanTwo = 1 > 2
- * const threeIsNotEqualToThree = 3 !== 3
- *
- * const condition = or([
- *   oneIsLessThanZero,
- *   oneIsGreaterThanTwo,
- *   threeIsNotEqualToThree
+ * const isOddOrGreaterThan3 = or([
+ *   n => n % 2 == 1,
+ *   n => n > 3,
  * ])
- * console.log(condition) // false
+ *
+ * console.log(isOddOrGreaterThan3(2))
+ * console.log(isOddOrGreaterThan3(3))
+ * console.log(isOddOrGreaterThan3(6))
  * ```
  *
- * If any predicate functions are provided in the array, `or` returns an aggregate predicate function that returns true for a given set of arguments if any provided predicate functions test true. If any provided predicate functions are asynchronous, the aggregate predicate function becomes asynchronous.
+ * If the array contains predicate functions, `or` returns an aggregate predicate function that returns true if some predicate function test true. If any predicate function is asynchronous, the aggregate predicate function is asynchronous.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -141,17 +132,34 @@ const areAnyPredicatesTruthy = function (args, predicates) {
  *   asyncIsGreaterThan3,
  * ])
  *
- * const condition = await aggregatePredicate(2)
- * console.log(condition) // false
+ * const booleanResult = await aggregatePredicate(2)
+ *
+ * console.log(booleanResult)
+ * ```
+ *
+ * If the array contains only values, `or` returns a boolean value.
+ *
+ * ```javascript [playground]
+ * const oneIsLessThanZero = 1 < 0
+ * const oneIsGreaterThanTwo = 1 > 2
+ * const threeIsNotEqualToThree = 3 !== 3
+ *
+ * const booleanResult = or([
+ *   oneIsLessThanZero,
+ *   oneIsGreaterThanTwo,
+ *   threeIsNotEqualToThree
+ * ])
+ *
+ * console.log(booleanResult)
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * Any promises in the array are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * or(Promise.resolve('aaa'), [
  *   s => s.startsWith('b'),
  *   s => s.endsWith('a'),
- * ]).then(console.log) // true
+ * ]).then(console.log)
  * ```
  *
  * See also:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "CFOSS",

package/reduce.js

@@ -25,22 +25,42 @@ const _reduce = function (collection, reducer, initial) {
  *
  * type SyncOrAsyncReducer = (
  *   accumulator any,
- *   element any,
+ *   item any,
  *   indexOrKey number|string|any,
  *   foldable Foldable
  * )=>(nextAccumulator Promise|any)
  *
  * type UnarySyncOrAsyncResolver = any=>Promise|any
  *
- * reducer SyncOrAsyncReducer
- * initial UnarySyncOrAsyncResolver|any
+ * reduce(foldable Promise|Foldable, reducer SyncOrAsyncReducer) -> accumulator Promise|any
+ * reduce(foldable Promise|Foldable, reducer SyncOrAsyncReducer, initialValue Promise|any) -> accumulator Promise|any
+ * reduce(foldable Promise|Foldable, reducer SyncOrAsyncReducer, initialResolver UnarySyncOrAsyncResolver) -> accumulator Promise|any
  *
- * reduce(foldable Promise|Foldable, reducer, initial?) -> result Promise|any
- * reduce(reducer, initial?)(foldable Foldable) -> result Promise|any
+ * reduce(reducer SyncOrAsyncReducer)(foldable Foldable) -> accumulator Promise|any
+ * reduce(reducer SyncOrAsyncReducer, initialValue Promise|any)(foldable Foldable) -> accumulator Promise|any
+ * reduce(reducer SyncOrAsyncReducer, initialResolver UnarySyncOrAsyncResolver)(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

@@ -45,19 +45,21 @@ const _some = function (collection, predicate) {
  *
  * predicate UnarySyncOrAsyncPredicate
  *
- * 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

@@ -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/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())
  * ```