rubico 2.8.5 → 2.8.6

package/switchCase.js

@@ -12,84 +12,84 @@ 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 API 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 passed in argument position are resolved for their values before further execution.
  *
  * ```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
+ * ])
  * ```
  *
  * See also:

package/tap.js

@@ -22,15 +22,12 @@ 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
@@ -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 passed in argument position are resolved for their values before further execution.
  *
  * ```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,17 +103,14 @@ 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
@@ -130,13 +122,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 passed in argument position are resolved for their values before further execution.
  *
  * ```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 argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const promise = transform(

package/tryCatch.js

@@ -22,28 +22,25 @@ const _tryCatch = function (tryer, catcher, args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
- *
- * type SyncOrAsyncFunction = (...args)=>Promise|any
- * type SyncOrAsyncCatcher = (error Error|any, ...args)=>Promise|any
+ * type SyncOrAsyncFunction = (...arguments)=>Promise|any
+ * type SyncOrAsyncCatcher = (error Error|any, ...arguments)=>Promise|any
  *
  * tryer SyncOrAsyncFunction
  * catcher SyncOrAsyncCatcher
  *
- * tryCatch(tryer, catcher)(...args) -> Promise|any
- * tryCatch(...argsOrPromises, tryer, catcher) -> Promise|any
+ * tryCatch(tryer, catcher)(...arguments) -> Promise|any
+ * tryCatch(...arguments, tryer, catcher) -> Promise|any
  * ```
  *
  * @description
- * Function equivalent to the [try...catch](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) statement. Accepts two functions: a `tryer` function and a `catcher` function. Calls the `tryer` function and catches any errors thrown by the `tryer` function with the `catcher` function.
+ * Function error handler. Accepts a tryer function and a catcher function. Calls the tryer function and catches any error thrown by the tryer function with the catcher function.
  *
  * ```javascript [playground]
  * const throwsIfOdd = number => {
- *   if (number % 2 == 1) {
+ *   if (number % 2 === 1) {
  *     throw new Error(`${number} is odd`)
  *   }
- *   console.log('did not throw for', number)
+ *   console.log('did not throw for number', number)
  * }
  *
  * const errorHandler = (error, number) => {
@@ -53,20 +50,18 @@ const _tryCatch = function (tryer, catcher, args) {
  *
  * const handler = tryCatch(throwsIfOdd, errorHandler)
  *
- * handler(2) // did not throw for 2
- * handler(3) // caught error from number 3
- *            // Error: 3 is odd
- *
+ * handler(2)
+ * handler(3)
  * ```
  *
- * If the `tryer` function is asynchronous and throws an error, the `catcher` function will catch the rejected promise.
+ * If the tryer function is asynchronous and returns a rejected promise, the catcher function will handle the error from the rejected promise.
  *
  * ```javascript [playground]
  * const rejectsIfOdd = async number => {
  *   if (number % 2 == 1) {
  *     throw new Error(`${number} is odd`)
  *   }
- *   console.log('did not throw for', number)
+ *   console.log('did not reject for number', number)
  * }
  *
  * const errorHandler = (error, number) => {
@@ -76,13 +71,11 @@ const _tryCatch = function (tryer, catcher, args) {
  *
  * const asyncHandler = tryCatch(rejectsIfOdd, errorHandler)
  *
- * asyncHandler(2) // did not throw for 2
- * asyncHandler(3) // caught error from number 3
- *                 // Error: 3 is odd
- *
+ * asyncHandler(2)
+ * asyncHandler(3)
  * ```
  *
- * When provided any number of arguments before the tryer and catcher functions, `tryCatch` executes immediately.
+ * `tryCatch` executes eagerly when provided any number of arguments before the tryer and catcher functions.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -91,11 +84,11 @@ const _tryCatch = function (tryer, catcher, args) {
  *   const sum = numbers.reduce(add)
  *   throw new Error(`the sum is ${sum}`)
  * }, function logErrorMessage(error) {
- *   console.error(error.message) // the sum is 6
+ *   console.error(error.message)
  * })
  * ```
  *
- * 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 argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * tryCatch(Promise.resolve(1), 2, Promise.resolve(3), (a, b, c) => {
@@ -103,7 +96,6 @@ const _tryCatch = function (tryer, catcher, args) {
  *   if (sum > 5) {
  *     throw new Error('limit exceeded')
  *   }
- *   console.log('sum:', sum)
  * }, (error, a, b, c) => {
  *   console.error(`${a} + ${b} + ${c}: ${error.message}`)
  * })