rubico 2.8.6 → 2.10.0

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.
+ * 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

@@ -49,7 +49,7 @@ const __ = require('./_internal/placeholder')
  * console.log(appendBC('a'))
  * ```
  *
- * Any promises passed in 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]
  * pipe(Promise.resolve(1), 2, Promise.resolve(3), [

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.
+ * 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.
+ * 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.
+ * 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

@@ -38,7 +38,7 @@ const curryArgs3 = require('./_internal/curryArgs3')
  * ])
  * ```
  *
- * `switchCase` supports a lazy API for composability.
+ * `switchCase` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * const fruitsGuesser = switchCase([
@@ -80,16 +80,24 @@ const curryArgs3 = require('./_internal/curryArgs3')
  * console.log(myDrink)
  * ```
  *
- * Any promises passed in 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. 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
  *   },
- *   (a, b, c) => console.log(`${a} + ${b} + ${c} == 6`),
- *   (a, b, c) => console.log(`${a} + ${b} + ${c} != 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

@@ -31,7 +31,7 @@ const _tap = function (args, f) {
  * ```
  *
  * @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,7 +43,7 @@ const _tap = function (args, f) {
  * pipeline('foo')
  * ```
  *
- * Any promises passed in 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]
  * tap(Promise.resolve(1), Promise.resolve(2), 3, console.log)
@@ -114,7 +114,9 @@ const _tapIf = function (predicate, f, args) {
  * ```
  *
  * @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
@@ -125,7 +127,7 @@ const _tapIf = function (predicate, f, args) {
  * logIfOdd(3)
  * ```
  *
- * Any promises passed in 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]
  * tap.if(Promise.resolve(1), 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.
+ * Any promises passed in data argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const promise = transform(

package/tryCatch.js

@@ -88,7 +88,7 @@ const _tryCatch = function (tryer, catcher, args) {
  * })
  * ```
  *
- * Any promises passed in 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]
  * tryCatch(Promise.resolve(1), 2, Promise.resolve(3), (a, b, c) => {

package/x/defaultsDeep.js

@@ -133,7 +133,7 @@ function _defaultsDeep(data, defaults) {
  * // }
  * ```
  *
- * The `defaults` array or object may be provided to `defaultsDeep` without `data` to create a lazy version of `defaultsDeep` that accepts `data` as a single argument. This "lazy" API can be used for function pipelines and function compositions.
+ * The `defaults` array or object may be provided to `defaultsDeep` without `data` to create a lazy version of `defaultsDeep` that accepts `data` as a single argument. This lazy interface can be used for function pipelines and function compositions.
  *
  * ```javascript [playground]
  * pipe({ a: 1 }, [

package/x/defaultsDeep.test.js

@@ -2,7 +2,7 @@ const assert = require('assert')
 const defaultsDeep = require('./defaultsDeep')
 
 describe('defaultsDeep', () => {
-  it('eager API', async () => {
+  it('eager interface', async () => {
     assert.deepEqual(
       defaultsDeep([3], [1, 2, 3]),
       [3, 2, 3],

package/_internal/NextIteration.js

@@ -1,12 +0,0 @@
-/**
- * @name NextIteration
- *
- * @synopsis
- * NextIteration(value any) -> nextIteration { value, done: false }
- *
- * @description
- * Create an object to send for the next iteration
- */
-const NextIteration = value => ({ value, done: false })
-
-module.exports = NextIteration

package/_internal/generatorFunctionFilter.js

@@ -1,28 +0,0 @@
-const FilteringIterator = require('./FilteringIterator')
-
-/**
- * @name generatorFunctionFilter
- *
- * @synopsis
- * ```coffeescript [specscript]
- * generatorFunctionFilter<
- *   T any,
- *   args ...any,
- *   generatorFunction ...args=>Generator<T>,
- *   predicate T=>boolean,
- * >(generatorFunction, predicate)
- *   -> filteringGeneratorFunction ...args=>Generator
- * ```
- *
- * @description
- * Filter a generator function by predicate.
- *
- * Note: async predicates may beget unexpected results
- */
-const generatorFunctionFilter = (
-  generatorFunction, predicate,
-) => function* filteringGeneratorFunction(...args) {
-  yield* FilteringIterator(generatorFunction(...args), predicate)
-}
-
-module.exports = generatorFunctionFilter

package/_internal/iterationMap.js

@@ -1,27 +0,0 @@
-const NextIteration = require('./NextIteration')
-const isPromise = require('./isPromise')
-
-/**
- * @name iterationMap
- *
- * @synopsis
- * iterationMap<
- *   T any,
- *   iteration { value: T, done: boolean },
- *   mapper T=>any,
- * >(iteration, mapper) -> nextIteration { value: any, done: boolean }
- *
- * @description
- * Apply a mapper to an iteration. Noop if iteration is done.
- */
-const iterationMap = function (iteration, mapper) {
-  if (iteration.done) {
-    return iteration
-  }
-  const mappedValue = mapper(iteration.value)
-  return isPromise(mappedValue)
-    ? mappedValue.then(NextIteration)
-    : { value: mappedValue, done: false }
-}
-
-module.exports = iterationMap