rubico 2.7.2 → 2.7.4

package/reduce.d.ts

@@ -28,7 +28,7 @@ export = reduce;
  * ```
  *
  * @description
- * Transforms a collection based on a reducer function and optional initial value. In a reducing operation, the result is defined in the beginning as either the initial value if supplied or the first item of the collection. The reducing operation then iterates through the remaining items in the collection, executing the reducer at each iteration to return the result to be used in the next iteration. The final result is the result of the execution of the reducer at the last item of the iteration. `reduce` accepts the following collections:
+ * Transforms a collection based on a reducer function and optional initial value. In a reducing operation, the result is defined in the beginning as either the initial value if supplied or the first element of the collection. The reducing operation then iterates through the remaining elements in the collection, executing the reducer at each iteration to return the result to be used in the next iteration. The final result is the result of the execution of the reducer at the last element of the iteration. `reduce` accepts the following collections:
  *
  *  * `Array`
  *  * `Object`
@@ -37,7 +37,7 @@ export = reduce;
  *  * `Iterator`/`Generator`
  *  * `AsyncIterator`/`AsyncGenerator`
  *
- * For arrays (type `Array`), `reduce` executes the reducer function for each item of the array in order, returning a new result at each execution to be used in the next execution. On each iteration, the reducer is passed the accumulator, the item of the iteration, the index of the item in the array, and a reference to the original array.
+ * For arrays (type `Array`), `reduce` executes the reducer function for each element of the array in order, returning a new result at each execution to be used in the next execution. On each iteration, the reducer is passed the accumulator, the element of the iteration, the index of the element in the array, and a reference to the original array.
  *
  * ```javascript [playground]
  * const max = (a, b) => a > b ? a : b
@@ -51,7 +51,7 @@ export = reduce;
  * ) // 5
  * ```
  *
- * If an optional initial value is provided, the result starts as the provided initial value rather than the first item of the collection.
+ * If an optional initial value is provided, the result starts as the provided initial value rather than the first element of the collection.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -91,7 +91,7 @@ export = reduce;
  * ) // 15
  * ```
  *
- * For sets (type `Set`), `reduce` executes the reducer function for each item of the set. On each iteration, the reducer is passed the accumulator and item of the set.
+ * For sets (type `Set`), `reduce` executes the reducer function for each element of the set. On each iteration, the reducer is passed the accumulator and element of the set.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -107,7 +107,7 @@ export = reduce;
  * ) // 15
  * ```
  *
- * For maps (type `Map`), `reduce` executes the reducer function for each value of each entry of the map. On each iteration, the reducer is passed the accumulator, the map item, the key of the map item, and a reference to the original map.
+ * For maps (type `Map`), `reduce` executes the reducer function for each value of each entry of the map. On each iteration, the reducer is passed the accumulator, the map element, the key of the map element, and a reference to the original map.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -123,7 +123,7 @@ export = reduce;
  * ) // 15
  * ```
  *
- * For iterators (type `Iterator`) and generators (type `Generator`), `reduce` executes the reducer function for each value of the iterator/generator. On each iteration, the reducer is passed the accumulator and the item of the iteration. The iterator/generator is consumed in the process.
+ * For iterators (type `Iterator`) and generators (type `Generator`), `reduce` executes the reducer function for each value of the iterator/generator. On each iteration, the reducer is passed the accumulator and the element of the iteration. The iterator/generator is consumed in the process.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -141,7 +141,7 @@ export = reduce;
  * ) // 15
  * ```
  *
- * For asyncIterators (type `AsyncIterator`) and asyncGenerators (type `AsyncGenerator`), `reduce` executes the reducer function for each value of the asyncIterator/asyncGenerator. On each iteration, the reducer is passed the accumulator and the item of the async iteration. The asyncIterator/asyncGenerator is consumed in the process.
+ * For asyncIterators (type `AsyncIterator`) and asyncGenerators (type `AsyncGenerator`), `reduce` executes the reducer function for each value of the asyncIterator/asyncGenerator. On each iteration, the reducer is passed the accumulator and the element of the async iteration. The asyncIterator/asyncGenerator is consumed in the process.
  *
  * ```javascript [playground]
  * const asyncAdd = async (a, b) => a + b

package/reduce.js

@@ -23,25 +23,20 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
  *
- * type Reducer = (
+ * type SyncOrAsyncReducer = (
  *   accumulator any,
- *   item any,
+ *   element any,
  *   indexOrKey number|string|any,
- *   fold Foldable
+ *   foldable Foldable
  * )=>(nextAccumulator Promise|any)
  *
- * type Resolver = (fold Foldable)=>Promise|any
+ * type UnarySyncOrAsyncResolver = any=>Promise|any
  *
- * reduce(
- *   fold Foldable,
- *   reducer Reducer,
- *   initial? Resolver|any
- * ) -> result Promise|any
+ * reducer SyncOrAsyncReducer
+ * initial UnarySyncOrAsyncResolver|any
  *
- * reduce(
- *   reducer Reducer,
- *   initial? Resolver|any
- * )(fold Foldable) -> result Promise|any
+ * reduce(foldable Promise|Foldable, reducer, initial?) -> result Promise|any
+ * reduce(reducer, initial?)(foldable Foldable) -> result Promise|any
  * ```
  *
  * @description
@@ -56,11 +51,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 item of the foldable.
+ * The reducing operation is dictated by a provided reducer function, which defines a transformation between the accumulator and a given element of the foldable.
  *
  * ```javascript
- * const reducer = function (accumulator, item) {
- *   // nextAccumulator is the result of some operation between accumulator and item
+ * const reducer = function (accumulator, element) {
+ *   // nextAccumulator is the result of some operation between accumulator and element
  *   // and becomes the accumulator for the next iteration and invocation of the reducer
  *   return nextAccumulator
  * }
@@ -72,7 +67,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   item any,
+ *   element any,
  *   index number,
  *   fold Array
  * ) -> nextAccumulator Promise|any
@@ -82,7 +77,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   item any
+ *   element any
  * ) -> nextAccumulator Promise|any
  * ```
  *
@@ -90,7 +85,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   item any,
+ *   element any,
  *   key any,
  *   fold Map
  * ) -> nextAccumulator Promise|any
@@ -100,7 +95,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   item any
+ *   element any
  * ) -> nextAccumulator Promise|any
  * ```
  *
@@ -108,7 +103,7 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   item any
+ *   element any
  * ) -> nextAccumulator Promise|any
  * ```
  *
@@ -118,13 +113,13 @@ const _reduce = function (collection, reducer, initial) {
  * ```coffeescript [specscript]
  * reducer(
  *   accumulator any,
- *   item any,
+ *   element any,
  *   key string,
  *   fold Object
  * ) -> nextAccumulator Promise|any
  * ```
  *
- * `reduce` executes a reducer function for each item of the array in order. 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.
+ * `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
@@ -133,7 +128,7 @@ const _reduce = function (collection, reducer, initial) {
  * console.log(result) // 5
  * ```
  *
- * If an initial value is provided, the accumulator starts as the initial value rather than the first item of the foldable.
+ * 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

package/some.d.ts

@@ -12,7 +12,7 @@ export = some;
  * ```
  *
  * @description
- * Test a predicate concurrently across all items of a collection, returning true if any executions return truthy.
+ * Test a predicate concurrently across all elements of a collection, returning true if any executions return truthy.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1

package/some.js

@@ -41,14 +41,16 @@ const _some = function (collection, predicate) {
  * @synopsis
  * ```coffeescript [specscript]
  * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
+ * type UnarySyncOrAsyncPredicate = any=>Promise|boolean
  *
- * some(collection Foldable, predicate function) -> Promise|boolean
+ * predicate UnarySyncOrAsyncPredicate
  *
- * some(predicate function)(collection Foldable) -> Promise|boolean
+ * some(foldable Foldable, predicate) -> Promise|boolean
+ * some(predicate)(foldable Foldable) -> Promise|boolean
  * ```
  *
  * @description
- * Test a predicate concurrently across all items of a foldable, returning true if any executions return true.
+ * Test a predicate concurrently across all elements of a foldable, returning true if any executions return true.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1

package/switchCase.d.ts

@@ -61,7 +61,7 @@ export = switchCase;
  * ])(false).then(console.log) // default
  * ```
  *
- * If every item in the conditional array is a nonfunction value, `switchCase` executes eagerly.
+ * If every element in the conditional array is a nonfunction value, `switchCase` executes eagerly.
  *
  * ```javascript [playground]
  * const age = 26

package/switchCase.js

@@ -12,20 +12,21 @@ const curryArgs3 = require('./_internal/curryArgs3')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * switchCase(conditionalValues Array<boolean|any>) -> Promise|any
+ * args Array<any>
+ * argsOrPromises Array<Promise|any>
  *
- * switchCase(
- *   ...args,
- *   conditionalFuncsOrValues Array<function|boolean|any>
- * ) -> Promise|any
+ * type SyncOrAsyncPredicate = (...args)=>Promise|boolean|any
  *
- * switchCase(
- *   conditionalFuncsOrValues Array<function|boolean|any>
- * )(...args) -> Promise|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
  * ```
  *
  * @description
- * Functional 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.
+ * 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.
  *
  * ```javascript [playground]
  * const fruitIsYellow = fruit => fruit.color == 'yellow'
@@ -60,16 +61,16 @@ const curryArgs3 = require('./_internal/curryArgs3')
  * Any function can be replaced with a nonfunction (object or primitive) value to be used directly in the operation.
  *
  * ```javascript [playground]
- * switchCase([
+ * switchCase(false, [
  *   async function asyncIdentity(value) {
  *     return value
  *   },
  *   'something',
  *   'default',
- * ])(false).then(console.log) // default
+ * ]).then(console.log) // default
  * ```
  *
- * If every item in the conditional array is a nonfunction value, `switchCase` executes eagerly.
+ * If every element in the conditional array is a nonfunction value, `switchCase` executes eagerly.
  *
  * ```javascript [playground]
  * const age = 26

package/tap.js

@@ -22,8 +22,15 @@ const _tap = function (args, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * tap(...args, f function) -> Promise|args[0]
- * tap(f function)(...args) -> Promise|args[0]
+ * args Array<any>
+ * argsOrPromises Array<Promise|any>
+ *
+ * type SyncOrAsyncFunction = (...args)=>Promise|any
+ *
+ * f SyncOrAsyncFunction
+ *
+ * tap(...argsOrPromises, f) -> Promise|args[0]
+ * tap(f)(...args) -> Promise|args[0]
  * ```
  *
  * @description
@@ -101,8 +108,17 @@ const _tapIf = function (predicate, f, args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * tap.if(...args, predicate function, f function) -> Promise|args[0]
- * tap.if(predicate function, f function)(...args) -> Promise|args[0]
+ * args Array<any>
+ * argsOrPromises Array<Promise|any>
+ *
+ * type SyncOrAsyncPredicate = (...args)=>Promise|boolean|any
+ * type SyncOrAsyncFunction = (...args)=>Promise|any
+ *
+ * predicate SyncOrAsyncPredicate
+ * f SyncOrAsyncFunction
+ *
+ * tap.if(...argsOrPromises, predicate, f) -> Promise|args[0]
+ * tap.if(predicate, f)(...args) -> Promise|args[0]
  * ```
  *
  * @description

package/thunkify.js

@@ -9,6 +9,8 @@ const funcApply = require('./_internal/funcApply')
  *
  * @synopsis
  * ```coffeescript [specscript]
+ * args Array<any>
+ *
  * thunkify(func function, ...args) -> thunk ()=>func(...args)
  * ```
  *

package/transform.d.ts

@@ -40,7 +40,7 @@ export = transform;
  *  * `Set`; concatenation defined by `result.add(...values)`
  *  * `TypedArray`; concatenation defined by `result.set(prevResult); result.set(values, offset)`
  *  * `{ concat: function }`; concatenation defined by `result.concat(values)`
- *  * `{ write: function }`; concatenation defined by `result.write(item)`
+ *  * `{ write: function }`; concatenation defined by `result.write(element)`
  *  * `Object`; concatenation defined by `({ ...result, ...values })`
  *
  * `transform` can transform any of the above collections into any of the other above collections.

package/transform.js

@@ -22,29 +22,19 @@ const _transform = function (collection, transducer, initialValue) {
  * @synopsis
  * ```coffeescript [specscript]
  * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
- *
- * type Reducer = (
- *   accumulator any,
- *   value any,
- * )=>(nextAccumulator Promise|any)
- *
- * type Transducer = Reducer=>Reducer
+ * type SyncOrAsyncReducer = (accumulator any, value any)=>(nextAccumulator Promise|any)
+ * type Transducer = SyncOrAsyncReducer=>SyncOrAsyncReducer
  *
  * type Semigroup =
  *   Array|String|Set|TypedArray|{ concat: function }|{ write: function }|Object
  *
- * type SemigroupResolver = (fold Foldable)=>Promise|Semigroup
+ * type UnarySyncOrAsyncSemigroupResolver = any=>Promise|Semigroup
  *
- * transform(
- *   fold Foldable,
- *   transducer Transducer,
- *   initial? Semigroup|SemigroupResolver,
- * ) -> result Promise|Semigroup
+ * transducer Transducer
+ * initial UnarySyncOrAsyncSemigroupResolver|Semigroup
  *
- * transform(
- *   transducer Transducer,
- *   initial? Semigroup|SemigroupResolver,
- * )(fold Foldable) -> result Promise|Semigroup
+ * transform(foldable Promise|Foldable, transducer, initial?) -> result Promise|Semigroup
+ * transform(transducer, initial?)(foldable Foldable) -> result Promise|Semigroup
  * ```
  *
  * @description
@@ -62,12 +52,8 @@ const _transform = function (collection, transducer, initialValue) {
  * 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:
  *
  * ```coffeescript [specscript]
- * type Reducer = (
- *   accumulator any,
- *   value any,
- * )=>(nextAccumulator Promise|any)
- *
- * type Transducer = Reducer=>Reducer
+ * type SyncOrAsyncReducer = (accumulator any, value any)=>(nextAccumulator Promise|any)
+ * type Transducer = SyncOrAsyncReducer=>SyncOrAsyncReducer
  * ```
  *
  * The following data types are considered to be semigroups:

package/tryCatch.js

@@ -22,13 +22,21 @@ const _tryCatch = function (tryer, catcher, args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * tryCatch(tryer function, catcher function)(...args) -> Promise|any
+ * args Array<any>
+ * argsOrPromises Array<Promise|any>
  *
- * tryCatch(...args, tryer function, catcher function) -> Promise|any
+ * type SyncOrAsyncFunction = (...args)=>Promise|any
+ * type SyncOrAsyncCatcher = (error Error|any, ...args)=>Promise|any
+ *
+ * tryer SyncOrAsyncFunction
+ * catcher SyncOrAsyncCatcher
+ *
+ * tryCatch(tryer, catcher)(...args) -> Promise|any
+ * tryCatch(...argsOrPromises, tryer, catcher) -> Promise|any
  * ```
  *
  * @description
- * Handles errors with a `tryer` and a `catcher` function. Calls the `tryer` function with the provided arguments and catches any errors thrown by the `tryer` function with the `catcher` function. If the `tryer` function is asynchronous and returns a rejected promise, the `catcher` function will execute with the value of the rejected promise. The `catcher` function is called with the error and all arguments supplied to the `tryer` function.
+ * 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.
  *
  * ```javascript [playground]
  * const throwsIfOdd = number => {
@@ -38,18 +46,43 @@ const _tryCatch = function (tryer, catcher, args) {
  *   console.log('did not throw for', number)
  * }
  *
- * const errorHandler = tryCatch(throwsIfOdd, (error, number) => {
+ * const errorHandler = (error, number) => {
  *   console.log('caught error from number', number)
  *   console.log(error)
- * })
+ * }
+ *
+ * const handler = tryCatch(throwsIfOdd, errorHandler)
+ *
+ * handler(2) // did not throw for 2
+ * handler(3) // caught error from number 3
+ *            // Error: 3 is odd
+ *
+ * ```
+ *
+ * If the `tryer` function is asynchronous and throws an error, the `catcher` function will catch 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)
+ * }
+ *
+ * const errorHandler = (error, number) => {
+ *   console.log('caught error from number', number)
+ *   console.log(error)
+ * }
+ *
+ * const asyncHandler = tryCatch(rejectsIfOdd, errorHandler)
  *
- * errorHandler(2) // did not throw for 2
- * errorHandler(3) // caught error from number 3
+ * asyncHandler(2) // did not throw for 2
+ * asyncHandler(3) // caught error from number 3
  *                 // Error: 3 is odd
  *
  * ```
  *
- * `tryCatch` behaves eagerly (executes immediately with a single call and not with multiple calls like a higher order function) when passed any amount of nonfunction (primitive or object) arguments before the `tryer` and `catcher` functions.
+ * When provided any number of arguments before the tryer and catcher functions, `tryCatch` executes immediately.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b

package/x/README.md

@@ -46,7 +46,7 @@ defaultsDeep({
 ```
 
 ### find
-get the first item in a collection that passes the test
+get the first element in a collection that passes the test
 ```javascript
 y = find(xi => boolean)(x)
 ```
@@ -86,20 +86,20 @@ flatten([[1], [2], [3]]), // > [1, 2, 3]
 
 `x` is a String or Array
 
-`y` is the last item of `x`
+`y` is the last element of `x`
 
 ```javascript
 first([1,2,3]) // 1
 ```
 
 ### forEach
-execute a function for each item of a collection, returning input
+execute a function for each element of a collection, returning input
 ```javascript
 y = forEach(f)(x)
 ```
 `f` is a function
 
-`f` is called for each item of `x`
+`f` is called for each element of `x`
 
 `x` is an Iterable, AsyncIterable, Object, or reducer function
 
@@ -232,14 +232,14 @@ y = last(x)
 
 `x` is a String or Array
 
-`y` is the last item of `x`
+`y` is the last element of `x`
 
 ```javascript
 last([1,2,3]) // 3
 ```
 
 ### pluck
-create a new collection by getting a path from every item of an old collection
+create a new collection by getting a path from every element of an old collection
 ```javascript
 y = pluck(path, defaultValue)(x)
 ```
@@ -312,13 +312,13 @@ create a flattened unique array with uniques given by a binary predicate
 ```javascript
 y = unionWith((a, b) => boolean)(x)
 ```
-`a` and `b` are items of items of `x`
+`a` and `b` are elements of elements of `x`
 
 `(a, b) => boolean` returns True if a and b are duplicates
 
 `x` is an Array of Arrays of anything
 
-`y` is a flattened Array of unique items of items of `x` determined by `(a, b) => boolean`
+`y` is a flattened Array of unique elements of elements of `x` determined by `(a, b) => boolean`
 
 `y` is a Promise if any of the following are true
  * `(a, b) => boolean` is asynchronous

package/x/append.d.ts

@@ -5,7 +5,7 @@ export = append;
  * @synopsis
  * ```coffeescript [specscript]
  * append(
- *   item string|Array,
+ *   element string|Array,
  * )(value string|Array) -> string|array
  * ```
  *
@@ -35,4 +35,4 @@ export = append;
  *
  * @since 1.7.3
  */
-declare function append(item: any): (value: any) => string | any[];
+declare function append(element: any): (value: any) => string | any[];

package/x/append.js

@@ -7,7 +7,7 @@ const isArray = require('../_internal/isArray')
  * @synopsis
  * ```coffeescript [specscript]
  * append(
- *   item string|Array,
+ *   element string|Array,
  * )(value string|Array) -> string|array
  * ```
  *
@@ -41,20 +41,20 @@ const isArray = require('../_internal/isArray')
  * @since 1.7.3
  */
 
-const append = item => function appendFunc(value) {
+const append = element => function appendFunc(value) {
 
     if (isArray(value)) {
-      if (isArray(item)){
-        return [...value, ...item]
+      if (isArray(element)){
+        return [...value, ...element]
       }
-      return [...value, item]
+      return [...value, element]
     }
 
     if (isString(value)){
-      if (!isString(item)){
-        throw new TypeError(`${item} is not a string`)
+      if (!isString(element)){
+        throw new TypeError(`${element} is not a string`)
       }
-      return `${value}${item}`
+      return `${value}${element}`
     }
 
     throw new TypeError(`${value} is not an Array or string`)