rubico 2.11.0 → 2.13.0

package/lte.js

@@ -6,44 +6,37 @@ const lessThanOrEqual = require('./_internal/lessThanOrEqual')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
- *
- * type SyncOrAsyncResolver = (...args)=>Promise|any
- *
- * leftValue Promise|any
- * rightValue Promise|any
- * leftResolver SyncOrAsyncResolver
- * rightResolver SyncOrAsyncResolver
- *
- * lte(leftValue, rightValue) -> Promise|boolean
- * lte(...argsOrPromises, leftResolver, rightValue) -> Promise|boolean
- * lte(...argsOrPromises, leftValue, rightResolver) -> Promise|boolean
- * lte(...argsOrPromises, leftResolver, rightResolver) -> Promise|boolean
- * lte(leftResolver, rightValue)(...args) -> Promise|boolean
- * lte(leftValue, rightResolver)(...args) -> Promise|boolean
- * lte(leftResolver, rightResolver)(...args) -> Promise|boolean
+ * type Resolver = (...arguments)=>Promise|any
+ *
+ * lte(leftValue Promise|any, rightValue Promise|any) -> Promise|boolean
+ * lte(...arguments, leftResolver Resolver, rightValue Promise|any) -> Promise|boolean
+ * lte(...arguments, leftValue Promise|any, rightResolver Resolver) -> Promise|boolean
+ * lte(...arguments, leftResolver Resolver, rightResolver Resolver) -> Promise|boolean
+ *
+ * lte(leftResolver Resolver, rightValue Promise|any)(...arguments) -> Promise|boolean
+ * lte(leftValue Promise|any, rightResolver Resolver)(...arguments) -> Promise|boolean
+ * lte(leftResolver Resolver, rightResolver Resolver)(...arguments) -> Promise|boolean
  * ```
  *
  * @description
- * Functional equivalent of the [Less than or equal (>=)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Less_than_or_equal) operator. Tests if a value is less than or equal (`<=`) to another value.
+ * Comparison operator. Tests if a value is less than or equal (`<=`) to another value.
  *
  * ```javascript [playground]
- * console.log(lte(1, 3)) // true
- * console.log(lte(3, 3)) // true
- * console.log(lte(4, 3)) // false
+ * console.log(lte(1, 3))
+ * console.log(lte(3, 3))
+ * console.log(lte(4, 3))
  * ```
  *
- * If either of the two values are resolver functions, `lte` returns a function that resolves the value(s) to compare.
+ * If either of the two values are resolver functions, `lte` returns a function that resolves the values to compare.
  *
  * ```javascript [playground]
  * const identity = value => value
  *
  * const isLessThanOrEqualTo3 = lte(identity, 3)
  *
- * console.log(isLessThanOrEqualTo3(1)) // true
- * console.log(isLessThanOrEqualTo3(3)) // true
- * console.log(isLessThanOrEqualTo3(5)) // false
+ * console.log(isLessThanOrEqualTo3(1))
+ * console.log(isLessThanOrEqualTo3(3))
+ * console.log(isLessThanOrEqualTo3(5))
  * ```
  *
  * If either of the two resolver functions is asynchronous, `lte` returns an asynchronous function.
@@ -53,9 +46,9 @@ const lessThanOrEqual = require('./_internal/lessThanOrEqual')
  *
  * const asyncIsLessThanOrEqualTo3 = lte(asyncIdentity, 3)
  *
- * asyncIsLessThanOrEqualTo3(1).then(console.log) // true
- * asyncIsLessThanOrEqualTo3(3).then(console.log) // true
- * asyncIsLessThanOrEqualTo3(5).then(console.log) // false
+ * asyncIsLessThanOrEqualTo3(1).then(console.log)
+ * asyncIsLessThanOrEqualTo3(3).then(console.log)
+ * asyncIsLessThanOrEqualTo3(5).then(console.log)
  * ```
  *
  * `lte` supports a lazy interface for composability.
@@ -63,14 +56,14 @@ const lessThanOrEqual = require('./_internal/lessThanOrEqual')
  * ```javascript [playground]
  * pipe({ value: 1 }, [
  *   lte(1, get('value')),
- *   console.log, // true
+ *   console.log,
  * ])
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * lte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
+ * lte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log)
  * ```
  *
  * See also:

package/map.js

@@ -96,19 +96,32 @@ const _map = function (value, f) {
  * ```coffeescript [specscript]
  * type Functor = Array|Set|Map|Generator|AsyncGenerator|{ map: function }|Object
  *
- * type SyncOrAsyncMapper = (
+ * type Mapper = (
  *   item any,
  *   indexOrKey number|string|any,
  *   functor Functor
  * )=>(mappedItem Promise|any)
  *
- * map(functor Promise|Functor, mapper SyncOrAsyncMapper) -> mappedFunctor Promise|Functor
- * map(mapper SyncOrAsyncMapper)(functor Functor) -> mappedFunctor Promise|Functor
+ * map(functor Promise|Functor, mapper Mapper) -> mappedFunctor Promise|Functor
+ * map(mapper Mapper)(functor Functor) -> mappedFunctor Promise|Functor
  * ```
  *
  * @description
  * Applies a mapper function to each item of a functor, returning a mapped functor of the same type with the mapped items. The order of the items of the functor is preserved.
  *
+ * ```javascript [playground]
+ * const square = number => number ** 2
+ *
+ * const array = [1, 2, 3, 4, 5]
+ * const object = { a: 1, b: 2, c: 3 }
+ *
+ * const mappedArray = map(array, square)
+ * const mappedObject = map(object, square)
+ *
+ * console.log(mappedArray)
+ * console.log(mappedObject)
+ * ```
+ *
  * The following data types are considered to be functors:
  *  * `array`
  *  * `set`
@@ -160,36 +173,23 @@ const _map = function (value, f) {
  * mapper(item any, key string, functor Object) -> mappedItem Promise|any
  * ```
  *
- * ```javascript [playground]
- * const square = number => number ** 2
- *
- * const array = [1, 2, 3, 4, 5]
- * const object = { a: 1, b: 2, c: 3 }
- *
- * const mappedArray = map(array, square)
- * const mappedObject = map(object, square)
- *
- * console.log(mappedArray)
- * console.log(mappedObject)
- * ```
- *
  * If the functor is an object with a `.map` method, the mapper function signature is defined externally.
  *
- * If the mapper function is asynchronous, it is executed concurrently.
- *
  * If the functor is a generator, the mapper function must be synchronous.
  *
+ * If the mapper function is asynchronous, it is executed concurrently.
+ *
  * ```javascript [playground]
  * const asyncSquare = async number => number ** 2
  *
  * const array = [1, 2, 3, 4, 5]
  *
- * const promise = map(array, asyncSquare)
+ * const result = await map(array, asyncSquare)
  *
- * promise.then(console.log)
+ * console.log(result)
  * ```
  *
- * `map` applies the mapper function to just the values of objects and maps.
+ * `map` iterates over just the values of objects and maps.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -298,6 +298,19 @@ const _mapEntries = (value, f) => {
  * @description
  * [map](/docs/map) that applies the mapper function to the entries of a functor as opposed to the values.
  *
+ * ```javascript [playground]
+ * const upperCaseKeysAndSquareValues =
+ *   map.entries(([key, value]) => [key.toUpperCase(), value ** 2])
+ *
+ * const object = { a: 1, b: 2, c: 3 }
+ *
+ * console.log(upperCaseKeysAndSquareValues(object))
+ *
+ * const m = new Map([['a', 1], ['b', 2], ['c', 3]])
+ *
+ * console.log(upperCaseKeysAndSquareValues(m))
+ * ```
+ *
  * The following data types are considered to be functors with entries:
  *   * `map`
  *   * `object`
@@ -316,19 +329,6 @@ const _mapEntries = (value, f) => {
  *   mappedEntry Promise|[mappedKey string, mappedValue any]
  * ```
  *
- * ```javascript [playground]
- * const upperCaseKeysAndSquareValues =
- *   map.entries(([key, value]) => [key.toUpperCase(), value ** 2])
- *
- * const object = { a: 1, b: 2, c: 3 }
- *
- * console.log(upperCaseKeysAndSquareValues(object))
- *
- * const m = new Map([['a', 1], ['b', 2], ['c', 3]])
- *
- * console.log(upperCaseKeysAndSquareValues(m))
- * ```
- *
  * If the functor with entries is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
@@ -369,13 +369,13 @@ map.entries = function mapEntries(arg0, arg1) {
  * ```coffeescript [specscript]
  * type Functor = Array|Object|Set|Map
  *
- * type SyncOrAsyncMapper = (
+ * type Mapper = (
  *   value any,
  *   indexOrKey number|string|any,
  *   f Functor
  * )=>(mappedItem Promise|any)
  *
- * _mapSeries(f Functor, f SyncOrAsyncMapper) -> result Promise|Functor
+ * _mapSeries(f Functor, f Mapper) -> result Promise|Functor
  * ```
  */
 const _mapSeries = function (functor, f) {
@@ -417,7 +417,7 @@ const _mapSeries = function (functor, f) {
  * ```coffeescript [specscript]
  * type Functor = Array|Set|Map|Generator|AsyncGenerator|{ map: function }|Object
  *
- * type SyncOrAsyncMapper = (
+ * type Mapper = (
  *   value any,
  *   indexOrKey number|string|any,
  *   functor Functor,
@@ -425,11 +425,11 @@ const _mapSeries = function (functor, f) {
  *
  * map.series(
  *   functor Promise|Functor,
- *   mapper SyncOrAsyncMapper
+ *   mapper Mapper
  * ) -> mappedFunctor Promise|Functor
  *
  * map.series(
- *   mapper SyncOrAsyncMapper
+ *   mapper Mapper
  * )(functor Functor) -> mappedFunctor Promise|Functor
  * ```
  *
@@ -521,7 +521,7 @@ const _mapPool = function (f, concurrency, mapper) {
  * ```coffeescript [specscript]
  * type MapPoolFunctor = Array|Object|Set|Map
  *
- * type SyncOrAsyncMapper = (
+ * type Mapper = (
  *   item any,
  *   indexOrKey number|string|any,
  *   functor Functor
@@ -530,12 +530,12 @@ const _mapPool = function (f, concurrency, mapper) {
  * map.pool(
  *   functor MapPoolFunctor,
  *   concurrency number,
- *   mapper SyncOrAsyncMapper
+ *   mapper Mapper
  * ) -> result Promise|Array
  *
  * map.pool(
  *   concurrency number,
- *   mapper SyncOrAsyncMapper
+ *   mapper Mapper
  * )(functor MapPoolFunctor) -> result Promise|Array
  * ```
  *
@@ -552,10 +552,7 @@ const _mapPool = function (f, concurrency, mapper) {
  *   return value
  * }
  *
- * map.pool(2, pipe([
- *   delayedIdentity,
- *   console.log,
- * ]))(ids)
+ * map.pool(ids, 2, pipe(delayedIdentity, console.log))
  * ```
  *
  * If the functor is a promise, it is resolved for its value before further execution for the eager interface only.

package/not.js

@@ -19,36 +19,31 @@ const _not = function (args, predicate) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
+ * type Predicate = (...arguments)=>Promise|boolean
  *
- * type SyncOrAsyncPredicate = (...args)=>Promise|boolean
- *
- * predicate SyncOrAsyncPredicate
- *
- * not(value Promise|boolean|any) -> negated Promise|boolean
- * not(...argsOrPromises, predicate) -> negated Promise|boolean
- * not(predicate)(...args) -> negated Promise|boolean
+ * not(value Promise|boolean|any) -> negatedResult Promise|boolean
+ * not(...arguments, predicate Predicate) -> negatedResult Promise|boolean
+ * not(predicate Predicate)(...arguments) -> negatedResult Promise|boolean
  * ```
  *
  * @description
- * Function equivalent to the [Logical NOT (`!`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_NOT) operator. Negates a value.
+ * Logical operator. Negates a predicate or value.
  *
  * ```javascript [playground]
- * const myObj = { a: 1 }
+ * const object = { a: 1 }
  *
- * console.log(not('a' in myObj)) // false
- * console.log(not('b' in myObj)) // true
+ * console.log(not('a' in object))
+ * console.log(not('b' in object))
  * ```
  *
- * If provided a predicate function, `not` returns a logically inverted predicate that returns true everywhere the original predicate would have returned false.
+ * If provided a predicate function, `not` returns a logically inverted predicate.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
  * const isNotOdd = not(isOdd)
  *
- * console.log(isNotOdd(3)) // false
+ * console.log(isNotOdd(3))
  * ```
  *
  * `not` negates the resolved value of a promise.
@@ -56,10 +51,10 @@ const _not = function (args, predicate) {
  * ```javascript [playground]
  * const promise = Promise.resolve(false)
  *
- * not(promise).then(console.log) // true
+ * not(promise).then(console.log)
  * ```
  *
- * Any promises passed in data argument position are resolved for their values before further execution.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1

package/or.js

@@ -97,37 +97,28 @@ const areAnyPredicatesTruthy = function (args, predicates) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
+ * type Predicate = (...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<Predicate|boolean|any>) -> testResult Promise|boolean
+ * or(predicatesOrValues Array<Predicate|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.13.0",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "CFOSS",

package/pipe.js

@@ -10,14 +10,14 @@ const __ = require('./_internal/placeholder')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type SyncOrAsyncFunction = (...arguments)=>Promise|any
- * type UnarySyncOrAsyncFunction = any=>Promise|any
+ * type Function = (...arguments)=>Promise|any
+ * type UnaryFunction = any=>Promise|any
  *
- * funcs [SyncOrAsyncFunction, ...Array<UnarySyncOrAsyncFunction>]
+ * funcs [Function, ...Array<UnaryFunction>]
  *
- * pipe(funcs)(...arguments) -> Promise|any
- * pipe(...arguments, funcs) -> Promise|any
- * pipe(...funcs)(...arguments) -> Promise|any
+ * pipe(funcs)(...arguments) -> result Promise|any
+ * pipe(...arguments, funcs) -> result Promise|any
+ * pipe(...funcs)(...arguments) -> result Promise|any
  * ```
  *
  * @description