rubico 2.8.5 → 2.10.0

package/forEach.js

@@ -24,16 +24,16 @@ const _forEach = function (collection, callback) {
   if (collection == null) {
     return collection
   }
-  if (typeof collection.forEach == 'function') {
-    collection.forEach(callback)
-    return collection
-  }
   if (typeof collection[symbolIterator] == 'function') {
     return iteratorForEach(collection[symbolIterator](), callback)
   }
   if (typeof collection[symbolAsyncIterator] == 'function') {
     return asyncIteratorForEach(collection[symbolAsyncIterator](), callback)
   }
+  if (typeof collection.forEach == 'function') {
+    collection.forEach(callback)
+    return collection
+  }
   if (collection.constructor == Object) {
     return objectForEach(collection, callback)
   }
@@ -48,22 +48,19 @@ const _forEach = function (collection, callback) {
  * type Iterable = Array|Set|Map|Generator|AsyncGenerator|{ forEach: function }|Object
  *
  * type SyncOrAsyncCallback = (
- *   element any,
+ *   item any,
  *   indexOrKey number|string|any,
- *   iter Iterable
+ *   iterable Iterable
  * )=>Promise|undefined
  *
- * iterable Iterable
- * cb SyncOrAsyncCallback
- *
- * forEach(iterable, cb) -> unmodifiedIterable Promise|Iterable
- * forEach(cb)(iterable) -> unmodifiedIterable Promise|Iterable
+ * forEach(iterable Promise|Iterable, callback SyncOrAsyncCallback) -> iterable Promise|Iterable
+ * forEach(callback SyncOrAsyncCallback)(iterable Iterable) -> iterable Promise|Iterable
  * ```
  *
  * @description
- * Execute a callback function for each element of an iterable, returning the original iterable unmodified.
+ * Executes a callback function for each item of an iterable, returning the original iterable unmodified.
  *
- * The following data types are considered to be iterables:
+ * The following data types are considered to be iterable:
  *  * `array`
  *  * `set`
  *  * `map`
@@ -76,36 +73,44 @@ const _forEach = function (collection, callback) {
  *
  * If the iterable is an array:
  * ```coffeescript [specscript]
- * callback(element any, index number, iter Array) -> Promise|undefined
+ * callback(item any, index number, iterable Array) -> Promise|undefined
  * ```
  *
  * If the iterable is a set:
  * ```coffeescript [specscript]
- * callback(element any, key any, iter Set) -> Promise|undefined
+ * callback(item any, item any, iterable Set) -> Promise|undefined
  * ```
  *
  * If the iterable is a map:
  * ```coffeescript [specscript]
- * callback(element any, key any, filt Map) -> Promise|undefined
+ * callback(item any, key any, iterable Map) -> Promise|undefined
  * ```
  *
  * If the iterable is a generator:
  * ```coffeescript [specscript]
- * callback(element any) -> Promise|undefined
+ * callback(item any) -> Promise|undefined
  * ```
  *
  * If the iterable is an async generator:
  * ```coffeescript [specscript]
- * callback(element any) -> Promise|undefined
+ * callback(item any) -> Promise|undefined
  * ```
  *
- * If the iterable is an object with a `.forEach` method, the callback function signature is defined externally.
- *
  * If the iterable is a plain object:
  * ```coffeescript [specscript]
- * callback(element any, key string, iter Object) -> Promise|undefined
+ * callback(item any, key string, iterable Object) -> Promise|undefined
  * ```
  *
+ * ```javascript [playground]
+ * console.log('array')
+ * forEach([1, 2, 3, 4, 5], num => console.log(num))
+ *
+ * console.log('object')
+ * forEach({ a: 1, b: 2, c: 3 }, num => console.log(num))
+ * ```
+ *
+ * If the iterable is an object with a `.forEach` method, the callback function signature is defined externally.
+ *
  * If the callback function is asynchronous, it is executed concurrently.
  *
  * ```javascript [playground]
@@ -117,37 +122,20 @@ const _forEach = function (collection, callback) {
  * })
  * ```
  *
- * `forEach` works for arrays.
- *
- * ```javascript [playground]
- * forEach([1, 2, 3, 4, 5], num => console.log(num)) // 1 2 3 4 5
- * ```
- *
- * `forEach` works for objects.
- *
- * ```javascript [playground]
- * forEach({ a: 1, b: 2, c: 3 }, num => console.log(num)) // 1 2 3
- * ```
- *
- * Omit the data argument for a composable API
+ * `forEach` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe([1, 2, 3, 4, 5], [
  *   filter(number => number % 2 == 1),
  *   map(number => number ** 2),
- *   forEach(console.log), // 1
- *                         // 9
- *                         // 25
+ *   forEach(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 iterable is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * forEach(Promise.resolve([1, 2, 3]), console.log)
- * // 1
- * // 2
- * // 3
  * ```
  *
  * See also:
@@ -203,16 +191,13 @@ const _forEachSeries = function (collection, callback) {
  * type Iterable = Array|Set|Map|Generator|AsyncGenerator|{ forEach: function }|Object
  *
  * type SyncOrAsyncCallback = (
- *   element any,
+ *   item any,
  *   indexOrKey number|string|any,
  *   iter Iterable
  * )=>Promise|undefined
  *
- * iterable Iterable
- * cb SyncOrAsyncCallback
- *
- * forEach(iterable, cb) -> unmodifiedIterable Promise|Iterable
- * forEach(cb)(iterable) -> unmodifiedIterable Promise|Iterable
+ * forEach.series(iterable Promise|Iterable, callback SyncOrAsyncCallback) -> iterable Promise|Iterable
+ * forEach.series(callback SyncOrAsyncCallback)(iterable Iterable) -> iterable Promise|Iterable
  * ```
  *
  * @description
@@ -224,21 +209,13 @@ const _forEachSeries = function (collection, callback) {
  *     setTimeout(resolve, 1000)
  *   })
  *   console.log(number)
- *   // 1
- *   // 2
- *   // 3
- *   // 4
- *   // 5
  * })
  * ```
  *
- * 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 iterable is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * forEach.series(Promise.resolve([1, 2, 3]), console.log)
- * // 1
- * // 2
- * // 3
  * ```
  *
  * See also:

package/get.js

@@ -1,6 +1,9 @@
 const isPromise = require('./_internal/isPromise')
+const promiseAll = require('./_internal/promiseAll')
 const __ = require('./_internal/placeholder')
+const curry2 = require('./_internal/curry2')
 const curry3 = require('./_internal/curry3')
+const funcApply = require('./_internal/funcApply')
 const isArray = require('./_internal/isArray')
 const isObject = require('./_internal/isObject')
 const getByPath = require('./_internal/getByPath')
@@ -18,47 +21,62 @@ const _get = function (object, path, defaultValue) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * get(
- *   object Promise|Object,
- *   path string|number|Array<string|number>,
- *   defaultValue? function|any
- * ) -> result Promise|Object
- *
- * get(
- *   path string|number|Array<string|number>,
- *   defaultValue? function|any
- * )(object Object) -> result Promise|Object
+ * path string|number|Array<string|number>
+ * defaultValue any
+ * defaultResolver function
+ *
+ * get(Promise|Object, path) -> Promise|any
+ * get(Promise|Object, path, defaultValue) -> Promise|any
+ * get(Promise|Object, path, defaultResolver) -> Promise|any
+ *
+ * get(path)(Object) -> Promise|any
+ * get(path, defaultValue)(Object) -> Promise|any
+ * get(path, defaultResolver)(Object) -> Promise|any
  * ```
  *
  * @description
- * Accesses a property of an object given a path denoted by a string, number, or an array of string or numbers.
+ * Property accessor. Accesses the property of an object given a path denoted by a string, number, or array of string or numbers.
  *
  * ```javascript [playground]
  * const obj = { hello: 'world' }
  *
- * console.log(get(obj, 'hello')) // world
+ * const value = get(obj, 'hello')
+ *
+ * console.log(value)
  * ```
  *
- * `get` supports a lazy API for composability
+ * `get` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * const obj = { hello: 'world' }
  *
  * const getHello = get('hello')
  *
- * console.log(getHello({ hello: 'world' })) // world
+ * const value = getHello({ hello: 'world' })
+ *
+ * console.log(value)
  * ```
  *
- * If the value at the end of the path is not found on the object, returns an optional default value. The default value can be a function resolver that takes the object as an argument. If no default value is provided, returns `undefined`. The function resolver may be asynchronous (returns a promise).
+ * If the value denoted by the path is not found in the object, `get` returns a default value. The default value can be a function resolver that takes the object as an argument. If no default value is provided, `get` returns `undefined`.
  *
  * ```javascript [playground]
  * const getHelloWithDefaultValue = get('hello', 'default')
  *
- * console.log(getHelloWithDefaultValue({ foo: 'bar' })) // default
+ * console.log(getHelloWithDefaultValue({ foo: 'bar' }))
  *
  * const getHelloWithDefaultResolver = get('hello', object => object.foo)
  *
- * console.log(getHelloWithDefaultResolver({ foo: 'bar' })) // bar
+ * console.log(getHelloWithDefaultResolver({ foo: 'bar' }))
+ * ```
+ *
+ * The default resolver may be asynchronous, in which case `get` returns a promise.
+ *
+ * ```javascript [playground]
+ * const asyncDefaultResolver = async object => object.a
+ *
+ * const promise = get({ a: 1 }, 'notfound', asyncDefaultResolver)
+ *
+ * promise.then(console.log)
  * ```
  *
  * `get` supports three types of path patterns for nested property access.
@@ -70,21 +88,27 @@ const _get = function (object, path, defaultValue) {
  * ```javascript [playground]
  * const getABC0 = get('a.b.c[0]')
  *
- * console.log(getABC0({ a: { b: { c: ['hello'] } } })) // hello
+ * const abc0 = getABC0({ a: { b: { c: ['hello'] } } })
+ *
+ * console.log(abc0)
  *
  * const get00000DotNotation = get('0.0.0.0.0')
  * const get00000BracketNotation = get('[0][0][0][0][0]')
  * const get00000ArrayNotation = get([0, 0, 0, 0, 0])
  *
- * console.log(get00000DotNotation([[[[['foo']]]]])) // foo
- * console.log(get00000BracketNotation([[[[['foo']]]]])) // foo
- * console.log(get00000ArrayNotation([[[[['foo']]]]])) // foo
+ * const nested = [[[[['foo']]]]]
+ *
+ * console.log(get00000DotNotation(nested))
+ * console.log(get00000BracketNotation(nested))
+ * console.log(get00000ArrayNotation(nested))
  * ```
  *
- * 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 or default value is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
- * get(Promise.resolve({ a: 1 }), 'a').then(console.log) // 1
+ * get(Promise.resolve({ a: 1 }), 'a').then(console.log)
+ *
+ * get({}, 'a', Promise.resolve('default-value')).then(console.log)
  * ```
  *
  * See also:
@@ -101,8 +125,8 @@ const get = function (arg0, arg1, arg2) {
   if (typeof arg0 == 'string' || typeof arg0 == 'number' || isArray(arg0)) {
     return curry3(_get, __, arg0, arg1)
   }
-  if (isPromise(arg0)) {
-    return arg0.then(curry3(_get, __, arg1, arg2))
+  if (isPromise(arg0) || isPromise(arg2)) {
+    return promiseAll([arg0, arg1, arg2]).then(curry2(funcApply, _get, __))
   }
   return _get(arg0, arg1, arg2)
 }

package/gt.js

@@ -56,7 +56,7 @@ const greaterThan = require('./_internal/greaterThan')
  * asyncIsOfLegalAge(juvenile).then(console.log) // false
  * ```
  *
- * `gt` supports a lazy API for composability.
+ * `gt` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe({ value: 1 }, [
@@ -65,7 +65,7 @@ const greaterThan = require('./_internal/greaterThan')
  * ])
  * ```
  *
- * 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]
  * gt(Promise.resolve({ a: 2, b: 1 }), get('a'), get('b')).then(console.log) // true

package/gte.js

@@ -60,7 +60,7 @@ const greaterThanOrEqual = require('./_internal/greaterThanOrEqual')
  * asyncIsAtLeast100(101).then(console.log) // true
  * ```
  *
- * `gte` supports a lazy API for composability.
+ * `gte` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * pipe({ value: 1 }, [
@@ -69,7 +69,7 @@ const greaterThanOrEqual = require('./_internal/greaterThanOrEqual')
  * ])
  * ```
  *
- * 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]
  * gte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true