rubico 2.8.5 → 2.10.0

package/not.js

@@ -59,7 +59,7 @@ const _not = function (args, predicate) {
  * not(promise).then(console.log) // true
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1

package/omit.js

@@ -20,17 +20,21 @@ const _omit = function (source, paths) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * omit(source Promise|Object, paths Array<string>) -> result Object
- * omit(paths Array<string>)(source Object) -> result Object
+ * paths Array<string>
+ *
+ * omit(Promise|Object, paths) -> Object
+ * omit(paths)(Object) -> Object
  * ```
  *
  * @description
- * Create a new object by excluding provided paths on a source object.
+ * Object constructor. Creates a new object by excluding provided paths on an argument object.
  *
  * ```javascript [playground]
- * console.log(
- *   omit({ _id: '1', name: 'John' }, ['_id']),
- * ) // { name: 'John' }
+ * const argumentObject = { _id: '1', name: 'John' }
+ *
+ * const newObject = omit(argumentObject, ['_id'])
+ *
+ * console.log(newObject)
  * ```
  *
  * `omit` supports three types of path patterns for nested property access
@@ -40,33 +44,32 @@ const _omit = function (source, paths) {
  *  * an array of keys or indices - `['a', 0, 'value']`
  *
  * ```javascript [playground]
- * console.log(
- *   omit(['a.b.d'])({
- *     a: {
- *       b: {
- *         c: 'hello',
- *         d: 'goodbye',
- *       },
+ * const omittedABD = omit(['a.b.d'])({
+ *   a: {
+ *     b: {
+ *       c: 'hello',
+ *       d: 'goodbye',
  *     },
- *   }),
- * ) // { a: { b: { c: 'hello' } } }
+ *   },
+ * })
+ *
+ * console.log(omittedABD)
  * ```
  *
- * Compose `omit` inside a `pipe` with its lazy API
+ * `omit` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe({ a: 1, b: 2, c: 3 }, [
  *   map(number => number ** 2),
  *   omit(['a', 'b']),
- *   console.log, // { c: 9 }
+ *   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.
+ * If the argument object is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * omit(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
- * // { c: 3 }
  * ```
  *
  * See also:

package/or.js

@@ -145,7 +145,7 @@ const areAnyPredicatesTruthy = function (args, predicates) {
  * console.log(condition) // false
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * or(Promise.resolve('aaa'), [

package/package.json

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

package/pick.js

@@ -27,17 +27,21 @@ const _pick = function (source, keys) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * pick(source Promise|Object, keys Array<string>) -> result Object
- * pick(keys Array<string>)(source Object) -> result Object
+ * keys Array<string>
+ *
+ * pick(Promise|Object, keys) -> Object
+ * pick(keys)(Object) -> Object
  * ```
  *
  * @description
- * Creates a new object from a source object by selecting provided keys. If a provided key does not exist on the source object, excludes it from the resulting object.
+ * Object constructor. Creates a new object from an argument object by selecting keys from an array. If a key does not exist on the argument object, it is excluded from the new object.
  *
  * ```javascript [playground]
- * console.log(
- *   pick({ goodbye: 1, world: 2 }, ['hello', 'world']),
- * ) // { world: 2 }
+ * const argumentObject = { goodbye: 1, world: 2 }
+ *
+ * const newObject = pick(argumentObject, ['hello', 'world'])
+ *
+ * console.log(newObject)
  * ```
  *
  * `pick` supports three types of path patterns for nested property access
@@ -49,24 +53,23 @@ const _pick = function (source, keys) {
  * ```javascript [playground]
  * const nested = { a: { b: { c: { d: 1, e: [2, 3] } } } }
  *
- * console.log(pick(['a.b.c.d'])(nested)) // { a: { b: { c: { d: 1 } } } }
+ * console.log(pick(nested, ['a.b.c.d']))
  * ```
  *
- * Compose `pick` inside a `pipe` with its lazy API.
+ * `pick` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe({ a: 1, b: 2, c: 3 }, [
  *   map(number => number ** 2),
  *   pick(['a', 'c']),
- *   console.log, // { a: 1, c: 9 }
+ *   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.
+ * If the argument object is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * pick(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
- * // { a: 1, b: 2 }
  * ```
  *
  * See also:

package/pipe.js

@@ -10,41 +10,35 @@ const __ = require('./_internal/placeholder')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
- *
- * type SyncOrAsyncFunction = (...args)=>Promise|any
+ * type SyncOrAsyncFunction = (...arguments)=>Promise|any
  * type UnarySyncOrAsyncFunction = any=>Promise|any
  *
  * funcs [SyncOrAsyncFunction, ...Array<UnarySyncOrAsyncFunction>]
  *
- * pipe(funcs)(...args) -> result Promise|any
- * pipe(...argsOrPromises, funcs) -> result Promise|any
- * pipe(...funcs)(...args) -> result Promise|any
+ * pipe(funcs)(...arguments) -> Promise|any
+ * pipe(...arguments, funcs) -> Promise|any
+ * pipe(...funcs)(...arguments) -> Promise|any
  * ```
  *
  * @description
- * Creates a function pipeline from multiple functions. Each function in the pipeline is evaluated in series, passing its return value as an argument to the next function. The result of a pipeline execution is the return value of the last function in the pipeline. All arguments provided to the pipeline are provided to the first function in the pipeline. If any function in the pipeline is asynchronous, the result of the pipeline execution is a Promise.
+ * Creates a function pipeline from multiple functions. Each function in the function pipeline is evaluated in series starting from the first function in the function pipeline, passing its return value as the first and only argument to the next function in the pipeline. The result of the execution of a function pipeline is the return value of the last function in the function pipeline. If any function in the function pipeline is asynchronous, the result of the execution of the function pipeline is a promise.
  *
- * ```javascript [playground]
- * const syncAdd123 = pipe([
- *   number => number + 1,
- *   number => number + 2,
- *   number => number + 3,
- * ])
+ * Multiple arguments may be provided to a function pipeline, in which case they are passed directly to the first function in the function pipeline.
  *
- * console.log(syncAdd123(5)) // 11
+ * ```javascript [playground]
+ * function add(a, b, c) {
+ *   return a + b + c
+ * }
  *
- * const asyncAdd123 = pipe([
- *   async number => number + 1,
- *   async number => number + 2,
- *   async number => number + 3,
+ * const pipeline = pipe([
+ *   add,
+ *   console.log,
  * ])
  *
- * asyncAdd123(5).then(console.log) // 11
+ * pipeline(1, 2, 3)
  * ```
  *
- * `pipe` supports a mathematical API.
+ * Functions may be passed to `pipe` as arguments instead of as items of an array.
  *
  * ```javascript [playground]
  * const appendB = x => x + 'b'
@@ -52,14 +46,14 @@ const __ = require('./_internal/placeholder')
  *
  * const appendBC = pipe(appendB, appendC)
  *
- * console.log(appendBC('a')) // 'abc'
+ * console.log(appendBC('a'))
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * pipe(Promise.resolve(1), 2, Promise.resolve(3), [
- *   console.log, // [1, 2, 3]
+ *   console.log,
  * ])
  * ```
  *

package/reduce.js

@@ -193,7 +193,7 @@ const _reduce = function (collection, reducer, initial) {
  * 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.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b

package/set.js

@@ -38,20 +38,19 @@ const _set = function (obj, path, value) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * set(
- *   object Promise|Object,
- *   path string|Array<string|number>,
- *   value function|any,
- * ) -> result Promise|Object
+ * path string|Array<string|number>
+ * resolver (...arguments)=>Promise|any
+ * value any
  *
- * set(
- *   path string|Array<string|number>,
- *   value function|any,
- * )(object Object) -> result Promise|Object
+ * set(Promise|Object, path, value) -> Promise|Object
+ * set(Promise|Object, path, resolver) -> Promise|Object
+ *
+ * set(path, value)(Object) -> Promise|Object
+ * set(path, resolver)(Object) -> Promise|Object
  * ```
  *
  * @description
- * Sets a property on a new object shallow cloned from the argument object given a path denoted by a string, number, or an array of string or numbers.
+ * Property setter. Shallow clones the argument object and sets a property on the shallow cloned object at the path denoted by a string, number, or array of string or numbers.
  *
  * `set` supports three types of path patterns for nested property access.
  *
@@ -60,15 +59,15 @@ const _set = function (obj, path, value) {
  *  * an array of keys or indices - `['a', 0, 'value']`
  *
  * ```javascript [playground]
- * console.log(set({ b: 2 }, 'a', 1)) // { a: 1, b: 2 }
+ * console.log(set({ b: 2 }, 'a', 1))
  *
  * const nestedAC2 = { a: { c: 2 } }
  *
- * console.log(set(nestedAC2, 'a.b', 1)) // { a : { b: 1, c: 2 }}
+ * console.log(set(nestedAC2, 'a.b', 1))
  *
  * const nestedA0BC3 = { a: [{ b: { c: 3 } }] }
  *
- * console.log(set(nestedA0BC3, 'a[0].b.c', 4)) // { a: [{ b: { c: 4 } }] }
+ * console.log(set(nestedA0BC3, 'a[0].b.c', 4))
  * ```
  *
  * The property value may be a function, in which case it is treated as a resolver and provided the argument object to resolve the value to set.
@@ -78,22 +77,22 @@ const _set = function (obj, path, value) {
  *
  * const myNewObj = set('b', obj => obj.a + 2)(myObj)
  *
- * console.log(myNewObj) // { a: 1, b: 3 }
+ * console.log(myNewObj)
  * ```
  *
- * `set` supports a lazy API for composability.
+ * `set` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe({ a: 1 }, [
  *   set('b', 2),
- *   console.log, // { a: 1, b: 2 }
+ *   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.
+ * If the argument object is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * set(Promise.resolve({}), 'a', 1).then(console.log) // { a: 1 }
+ * set(Promise.resolve({}), 'a', 1).then(console.log)
  * ```
  *
  * See also:

package/some.js

@@ -94,7 +94,7 @@ const _some = function (collection, predicate) {
  * promise.then(console.log) // true
  * ```
  *
- * `some` supports a lazy API for composability.
+ * `some` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe([1, 2, 3], [
@@ -103,7 +103,7 @@ const _some = function (collection, predicate) {
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * some(Promise.resolve([1, 2, 3, 4, 5]), n => n > 6).then(console.log) // false

package/switchCase.js

@@ -12,84 +12,92 @@ const curryArgs3 = require('./_internal/curryArgs3')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
+ * type SyncOrAsyncPredicate = (...arguments)=>Promise|boolean|any
+ * type SyncOrAsyncFunction = (...arguments)=>Promise|any
  *
- * type SyncOrAsyncPredicate = (...args)=>Promise|boolean|any
+ * conditionalValues Array<Promise|boolean|any>
+ * conditionalFunctionsOrValues Array<SyncOrAsyncPredicate|SyncOrAsyncFunction|Promise|boolean|any>
  *
- * conditionalPromisesOrValues Array<Promise|boolean|any>
- * conditionalFuncsOrPromisesOrValues Array<SyncOrAsyncPredicate|Promise|boolean|any>
- *
- * switchCase(conditionalPromisesOrValues) -> Promise|any
- * switchCase(...argsOrPromises, conditionalFuncsOrPromisesOrValues) -> Promise|any
- * switchCase(conditionalFuncsOrPromisesOrValues)(...args) -> Promise|any
+ * switchCase(conditionalValues) -> Promise|any
+ * switchCase(...arguments, conditionalFunctionsOrValues) -> Promise|any
+ * switchCase(conditionalFunctionsOrValues)(...arguments) -> Promise|any
  * ```
  *
  * @description
- * Function equivalent to the [Conditional (ternary) operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator). Accepts an array of conditional functions that specifies cases as pairings of `predicate` and `resolver` functions with the exception of the last, default resolver. All functions are provided with the same arguments and executed in series. The result of a `switchCase` operation is either the result of the execution the last default resolver, or the result of the execution of the first resolver where the associated predicate tested true.
+ * Conditional function operator. Accepts an array of conditional functions or values that specifies cases as function or value pairs with the exception of the last, default function or value. All functions are provided with the same arguments and executed in series. The result of a conditional execution with `switchCase` is the result of the execution of the first truthy function or value pair, the result of the execution of the last, default function, or the provided last, default value.
  *
  * ```javascript [playground]
- * const fruitIsYellow = fruit => fruit.color == 'yellow'
- *
- * console.log(
- *   switchCase({ name: 'plantain', color: 'yellow' }, [
- *     fruitIsYellow,
- *     fruit => fruit.name + ' is possibly a banana',
- *     fruit => fruit.name + ' is probably not a banana',
- *   ])
- * ) // plantain is possibly a banana
+ * function isOdd(n) {
+ *   return n % 2 == 1
+ * }
+ *
+ * switchCase(1, [
+ *   isOdd,
+ *   n => console.log(`${n} is odd`),
+ *   n => console.log(`${n} is even`),
+ * ])
  * ```
  *
- * For composability `switchCase` supports a lazy API.
+ * `switchCase` supports a lazy interface for composability.
  *
  * ```javascript [playground]
- * const fruitIsYellow = fruit => fruit.color == 'yellow'
- *
  * const fruitsGuesser = switchCase([
- *   fruitIsYellow,
+ *   fruit => fruit.color == 'yellow',
  *   fruit => fruit.name + ' is possibly a banana',
  *   fruit => fruit.name + ' is probably not a banana',
  * ])
  *
- * console.log(fruitsGuesser({ name: 'plantain', color: 'yellow' }))
- * // plantain is possibly a banana
+ * const guess1 = fruitsGuesser({ name: 'plantain', color: 'yellow' })
+ * const guess2 = fruitsGuesser({ name: 'apple', color: 'red' })
  *
- * console.log(fruitsGuesser({ name: 'apple', color: 'red' }))
- * // apple is probably not a banana
+ * console.log(guess1)
+ * console.log(guess2)
  * ```
  *
- * Any function can be replaced with a nonfunction (object or primitive) value to be used directly in the operation.
+ * Any item of the conditional array passed to switchCase can be a nonfunction (object or primitive) value.
  *
  * ```javascript [playground]
- * switchCase(false, [
- *   async function asyncIdentity(value) {
- *     return value
- *   },
- *   'something',
- *   'default',
- * ]).then(console.log) // default
+ * function identity (value) {
+ *   return value
+ * }
+ *
+ * const value = switchCase(false, [
+ *   identity,
+ *   'non-function',
+ *   'default-value',
+ * ])
+ *
+ * console.log(value)
  * ```
  *
- * If every element in the conditional array is a nonfunction value, `switchCase` executes eagerly.
+ * If every item in the conditional array is a nonfunction value, `switchCase` executes eagerly.
  *
  * ```javascript [playground]
  * const age = 26
  *
- * const myDrink = switchCase([age >= 21, 'Beer', 'Juice'])
+ * const myDrink = switchCase([age >= 21, 'Water', 'Juice'])
  *
- * console.log(myDrink) // Beer
+ * console.log(myDrink)
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only. Any promises in the conditional array are resolved before further execution for both the lazy and eager interface.
  *
  * ```javascript [playground]
  * switchCase(Promise.resolve(1), 2, Promise.resolve(3), [
  *   function doValuesAddUpTo6(a, b, c) {
- *     return a + b + c == 6
+ *     return a + b + c === 6
  *   },
- *   (a, b, c) => console.log(`${a} + ${b} + ${c} == 6`),
- *   (a, b, c) => console.log(`${a} + ${b} + ${c} != 6`),
- * ]) // 1 + 2 + 3 == 6
+ *   (a, b, c) => console.log(`${a} + ${b} + ${c} === 6`),
+ *   (a, b, c) => console.log(`${a} + ${b} + ${c} !== 6`),
+ * ])
+ *
+ * const promise = switchCase(true, [
+ *   bool => bool,
+ *   Promise.resolve(1),
+ *   Promise.resolve(2),
+ * ])
+ *
+ * promise.then(console.log)
  * ```
  *
  * See also:

package/tap.js

@@ -22,19 +22,16 @@ const _tap = function (args, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
- *
- * type SyncOrAsyncFunction = (...args)=>Promise|any
+ * type SyncOrAsyncFunction = (...arguments)=>Promise|any
  *
  * f SyncOrAsyncFunction
  *
- * tap(...argsOrPromises, f) -> Promise|args[0]
- * tap(f)(...args) -> Promise|args[0]
+ * tap(...arguments, f) -> Promise|arguments[0]
+ * tap(f)(...arguments) -> Promise|arguments[0]
  * ```
  *
  * @description
- * Call a function with provided arguments, returning the first argument. The return value of the function call is discarded.
+ * Calls a function with provided arguments, returning the first argument. The return value of the function call is discarded.
  *
  * ```javascript [playground]
  * const pipeline = pipe([
@@ -43,15 +40,13 @@ const _tap = function (args, f) {
  *   tap(value => console.log(value + 'barbaz')),
  * ])
  *
- * pipeline('foo') // 'foo'
- *                 // 'foobar'
- *                 // 'foobarbaz'
+ * pipeline('foo')
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * tap(Promise.resolve(1), Promise.resolve(2), 3, console.log) // 1 2 3
+ * tap(Promise.resolve(1), Promise.resolve(2), 3, console.log)
  * ```
  *
  * See also:
@@ -108,21 +103,20 @@ const _tapIf = function (predicate, f, args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
- *
- * type SyncOrAsyncPredicate = (...args)=>Promise|boolean|any
- * type SyncOrAsyncFunction = (...args)=>Promise|any
+ * type SyncOrAsyncPredicate = (...arguments)=>Promise|boolean|any
+ * type SyncOrAsyncFunction = (...arguments)=>Promise|any
  *
  * predicate SyncOrAsyncPredicate
  * f SyncOrAsyncFunction
  *
- * tap.if(...argsOrPromises, predicate, f) -> Promise|args[0]
- * tap.if(predicate, f)(...args) -> Promise|args[0]
+ * tap.if(...arguments, predicate, f) -> Promise|arguments[0]
+ * tap.if(predicate, f)(...arguments) -> Promise|arguments[0]
  * ```
  *
  * @description
- * A version of `tap` that accepts a predicate function (a function that returns a boolean value) before the function `f` to execute. Only executes `f` if the predicate function tests true. The arguments are the same to both the predicate function and the function to execute `f`.
+ * A version of [tap](/docs/tap) that accepts a predicate function before the function to execute and only executes the function if the predicate function tests true.
+ *
+ * Arguments passed to `tap.if` are provided to both the predicate function and the function to execute.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -130,13 +124,13 @@ const _tapIf = function (predicate, f, args) {
  * const logIfOdd = tap.if(isOdd, console.log)
  *
  * logIfOdd(2)
- * logIfOdd(3) // 3
+ * logIfOdd(3)
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises in `arguments` are resolved for their values before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * tap.if(Promise.resolve(1), n => n < 5, console.log) // 1
+ * tap.if(Promise.resolve(1), n => n < 5, console.log)
  * tap.if(Promise.resolve(6), n => n < 5, console.log)
  * ```
  *

package/transform.js

@@ -201,7 +201,7 @@ const _transform = function (collection, transducer, initialValue) {
  * 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.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const promise = transform(