rubico 2.8.6 → 2.11.0

package/flatMap.js

@@ -20,7 +20,7 @@ const __ = require('./_internal/placeholder')
  *
  * _flatMap(
  *   m Monad,
- *   flatMapper (element any)=>Promise|Iterable,
+ *   flatMapper (item any)=>Promise|Iterable,
  * ) -> result Promise|Monad
  * ```
  */
@@ -64,66 +64,84 @@ const _flatMap = function (value, flatMapper) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Monad = Array|String|Set|Generator|AsyncGenerator|{ flatMap: string }|{ chain: string }|Object
+ * type Monad = Array|string|Set|Generator|AsyncGenerator|{ flatMap: string }|{ chain: string }|Object
  *
  * type SyncOrAsyncFlatMapper = (
- *   element any,
+ *   item any,
  *   indexOrKey number|string|any,
  *   monad Monad
- * )=>Promise|Monad|any
+ * )=>(flatMappedItem Promise|Monad|any)
  *
- * flatMapper SyncOrAsyncFlatMapper
- *
- * flatMap(monad Promise|Monad, flatMapper) -> result Promise|Monad
- * flatMap(flatMapper)(monad Monad) -> result Promise|Monad
+ * flatMap(monad Promise|Monad, flatMapper SyncOrAsyncFlatMapper) -> flatMappedMonad Promise|Monad
+ * flatMap(flatMapper SyncOrAsyncFlatMapper)(monad Monad) -> flatMappedMonad Promise|Monad
  * ```
  *
  * @description
- * Applies a flatMapper function to each element of a monad, returning a monad of the same type.
+ * Applies a flat-mapper function to each item of a monad, returning a flat-mapped monad of the same type.
  *
- * A flatMapping operation iterates through each element of a monad and applies the flatMapper function to each element, flattening the result of the execution into the returned monad.
+ * A flat-mapping operation iterates through each item of a monad and applies the flat-mapper function to each item, flattening the result of the execution into the returned monad.
  *
- * If the flatMapper is asynchronous, it is executed concurrently. The execution result may be asynchronously iterable, in which case it is muxed into the returned monad.
+ * If the flat-mapper is asynchronous, it is executed concurrently. The execution result may be asynchronously iterable, in which case it is muxed into the returned monad.
  *
- * The following data types are considered to be monads, all are flattenable into other monads:
+ * The following data types are considered to be monads:
  *  * `array`
  *  * `string`
  *  * `set`
- *  * `genreator`
+ *  * `generator`
  *  * `async generator`
  *  * `object with .flatMap method`
  *  * `object with .chain method`
  *  * `object`
  *
- * `flatMap` flattens various data types.
+ * The flat-mapper function signature changes depending on the provided monad.
+ *
+ * If the monad is an array:
+ * ```coffeescript [specscript]
+ * flatMapper(item any, index number, monad Array) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a string:
+ * ```coffeescript [specscript]
+ * flatMapper(character string, index number, monad string) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a set:
+ * ```coffeescript [specscript]
+ * flatMapper(item any, item any, monad set) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a generator:
+ * ```coffeescript [specscript]
+ * flatMapper(item any) -> flatMappedItem Monad|any
+ * ```
+ *
+ * If the monad is an async generator:
+ * ```coffeescript [specscript]
+ * flatMapper(item any) -> flatMappedItem Promise|Monad|any
+ * ```
+ *
+ * If the monad is a plain object:
+ * ```coffeescript [specscript]
+ * flatMapper(item any, key string, monad Object) -> flatMappedItem Promise|Monad|any
+ * ```
  *
  * ```javascript [playground]
- * const identity = value => value
- *
- * flatMap(identity)([
- *   [1, 1], // array
- *   new Set([2, 2]), // set
- *   (function* () { yield 3; yield 3 })(),
- *   (async function* () { yield 7; yield 7 })(),
- *   { a: 5, b: 5 }, // object
- *   new Uint8Array([8]), // typedArray
- * ]).then(console.log)
- * // [1, 1, 2, 3, 3, 5, 5, 8, 7, 7]
+ * const duplicate = value => [value, value]
+ *
+ * const duplicated = flatMap([1, 2, 3, 4, 5], duplicate)
+ *
+ * console.log(duplicated)
  * ```
  *
+ * If the iterable is an object with a `.flatMap` or `.chain` method, the flat-mapper function signature is defined externally.
+ *
  * Values from async generators are muxed. Muxing, or asynchronously "mixing", is the process of combining multiple asynchronous sources into one source, with order determined by the asynchronous resolution of the individual promise elements.
  *
+ * For other types of monads, order is preserved from the original monad and applied to the flat-mapped items, which are then concatenated into the flat-mapped monad. The order of the items of a given flat-mapped item is determined by the structure of the flat-mapped item.
+ *
  * ```javascript [playground]
  * const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
  *
- * const repeat3 = function* (message) {
- *   yield message; yield message; yield message
- * }
- *
- * console.log( // sync is concatenated
- *   flatMap(['foo', 'bar', 'baz'], repeat3),
- * ) // ['foo', 'foo', 'foo', 'bar', 'bar', 'bar', 'baz', 'baz', 'baz']
- *
  * const asyncRepeat3 = async function* (message) {
  *   yield message
  *   await sleep(100)
@@ -133,35 +151,24 @@ const _flatMap = function (value, flatMapper) {
  * }
  *
  * // values from async generators are muxed
- * flatMap(['foo', 'bar', 'baz'], asyncRepeat3).then(console.log)
- * // ['foo', 'bar', 'baz', 'foo', 'bar', 'baz', 'foo', 'bar', 'baz']
- * ```
+ * const muxed = await flatMap(['foo', 'bar', 'baz'], asyncRepeat3)
  *
- * `flatMap` applies the flatMapper function to each element of an array, flattening the results into a new array.
+ * console.log(muxed)
  *
- * ```javascript [playground]
- * const duplicate = value => [value, value]
- *
- * console.log(
- *   flatMap([1, 2, 3, 4, 5], duplicate)
- * ) // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
- * ```
- *
- * `flatMap` acts on each character of a string.
+ * const repeat3 = function* (message) {
+ *   yield message; yield message; yield message
+ * }
  *
- * ```javascript [playground]
- * const duplicate = value => [value, value]
+ * // values from generators and other monads are concatenated
+ * const repeated = flatMap(['foo', 'bar', 'baz'], repeat3)
  *
- * console.log(
- *   flatMap('12345', duplicate)
- * ) // 1122334455
+ * console.log(repeated)
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution.
+ * If the monad is a promise, it is resolved for its value before further execution for the eager interface only.
  *
  * ```javascript [playground]
  * flatMap(Promise.resolve([1, 2, 3, 4, 5]), n => [n, n]).then(console.log)
- * // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
  * ```
  *
  * See also:
@@ -179,7 +186,7 @@ const _flatMap = function (value, flatMapper) {
  * @archive
  *  * For typed arrays (type [`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#typedarray_objects)) and Node.js buffers (type [`Buffer`](https://nodejs.org/api/buffer.html)), `flatMap` applies a flatMapper function to each value of the typed array/buffer, joining the result of each execution with `.set` into the resulting typed array
  *
- *  * For Node.js duplex streams (type [Stream](https://nodejs.org/api/stream.html#class-streamduplex)), `flatMap` applies a flatMapper function to each element of the stream, writing (`.write`) each element of each execution into the duplex stream
+ *  * For Node.js duplex streams (type [Stream](https://nodejs.org/api/stream.html#class-streamduplex)), `flatMap` applies a flatMapper function to each item of the stream, writing (`.write`) each item of each execution into the duplex stream
  */
 const flatMap = (arg0, arg1) => {
   if (typeof arg0 == 'function') {

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

@@ -45,7 +45,7 @@ const _get = function (object, path, defaultValue) {
  * console.log(value)
  * ```
  *
- * `get` supports a lazy API for composability.
+ * `get` supports a lazy interface for composability.
  *
  * ```javascript [playground]
  * const obj = { hello: 'world' }
@@ -103,10 +103,12 @@ const _get = function (object, path, defaultValue) {
  * console.log(get00000ArrayNotation(nested))
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution.
+ * 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:

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