rubico 2.6.5 → 2.7.0

package/filter.js

@@ -3,6 +3,7 @@ const curry2 = require('./_internal/curry2')
 const FilteringIterator = require('./_internal/FilteringIterator')
 const FilteringAsyncIterator = require('./_internal/FilteringAsyncIterator')
 const isArray = require('./_internal/isArray')
+const isPromise = require('./_internal/isPromise')
 const arrayFilter = require('./_internal/arrayFilter')
 const stringFilter = require('./_internal/stringFilter')
 const setFilter = require('./_internal/setFilter')
@@ -89,74 +90,118 @@ const _filter = function (value, predicate) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Filterable = Array|Object|Set|Map|Iterator|AsyncIterator
+ * type Filterable = Array|Set|Map|Generator|AsyncGenerator|{ filter: function }|Object
  *
  * type Predicate = (
  *   value any,
- *   indexOrKey number|string,
- *   collection Filterable,
+ *   indexOrKey number|string|any,
+ *   filt Filterable,
  * )=>boolean
  *
- * filter(collection Filterable, predicate Predicate) -> result Promise|Filterable
- * filter(predicate Predicate)(collection Filterable) -> result Promise|Filterable
+ * filter(filt Filterable, predicate Predicate) -> result Promise|Filterable
+ * filter(predicate Predicate)(filt Filterable) -> result Promise|Filterable
  * ```
  *
  * @description
- * Filter out items from a collection based on the results of their concurrent executions with a synchronous or asynchronous predicate function. `filter` accepts the following collections:
+ * Filters out items from a filterable. Returns a filterable of the same type. The order of the items in the filterable is preserved.
+ *
+ * The following data types are considered to be filterables:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .filter method`
+ *  * `object`
+ *
+ * The filtering operation is defined by a given predicate function. The predicate function dictates whether a given item from the filterable should be included in the returned filterable.
+ *
+ * ```javascript
+ * const predicate = function (item) {
+ *   // condition is the boolean result of the predicate test on item
+ *   return condition
+ * }
+ * ```
+ *
+ * The predicate function signature changes depending on the provided filterable.
+ *
+ * If the filterable is an array:
+ * ```coffeescript [specscript]
+ * predicate(item any, index number, filt Array) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is a set:
+ * ```coffeescript [specscript]
+ * predicate(item any, item any, filt Set) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is a map:
+ * ```coffeescript [specscript]
+ * predicate(item any, key any, filt Map) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is a generator:
+ * ```coffeescript [specscript]
+ * predicate(item any) -> condition Promise|boolean|any
+ * ```
  *
- *  * `Array`
- *  * `Object`
- *  * `Set`
- *  * `Map`
- *  * `Iterator`/`Generator`
- *  * `AsyncIterator`/`AsyncGenerator`
+ * If the filterable is an async generator:
+ * ```coffeescript [specscript]
+ * predicate(item any) -> condition Promise|boolean|any
+ * ```
+ *
+ * If the filterable is an object with a `.filter` method, the predicate function signature is defined externally.
  *
- * For arrays (type `Array`), `filter` applies the predicate function to each item of the array, returning a new array containing only the items that tested truthy by the predicate. The order of the items is preserved. On each iteration, the predicate is passed the item, the index of the item, and a reference to the array.
+ * If the filterable is a plain object:
+ * ```coffeescript [specscript]
+ * predicate(item any, key string, filt Object) -> condition Promise|boolean|any
+ * ```
+ *
+ * `filter` works for arrays.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
  * const array = [1, 2, 3, 4, 5]
  *
- * console.log(filter(isOdd)(array)) // [1, 3, 5]
- * console.log(filter(array, isOdd)) // [1, 3, 5]
+ * const result = filter(array, isOdd)
+ * console.log(result) // [1, 3, 5]
  * ```
  *
- * For objects (type `Object`), `filter` applies the predicate function to each value of the object, returning a new object containing only the values that tested truthy by the predicate. On each iteration, the predicate is passed the object value, the key of the object value, and a reference to the object.
+ * If the predicate is asynchronous, the returned promise is concurrently resolved for its boolean condition before continuing with the filtering operation.
  *
  * ```javascript [playground]
- * const isOdd = number => number % 2 == 1
+ * const asyncIsOdd = async number => number % 2 == 1
  *
- * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+ * const array = [1, 2, 3, 4, 5]
  *
- * console.log(filter(isOdd)(obj)) // { a: 1, c: 3, e: 5 }
- * console.log(filter(obj, isOdd)) // { a: 1, c: 3, e: 5 }
+ * const promise = filter(array, asyncIsOdd)
+ * promise.then(console.log) // [1, 3, 5]
  * ```
  *
- * For sets (type `Set`), `filter` applies the predicate function to each item in the set, returning a new set containing only the items that tested truthy by the predicate. On each iteration, the predicate is passed the item, the same item as the key argument, and a reference to the set.
+ * `filter` applies the predicate function to just the values of an object.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
- * const set = new Set([1, 2, 3, 4, 5])
+ * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
  *
- * console.log(filter(isOdd)(set)) // Set { 1, 3, 5 }
- * console.log(filter(set, isOdd)) // Set { 1, 3, 5 }
+ * const result = filter(obj, isOdd)
+ * console.log(result) // { a: 1, c: 3, e: 5 }
  * ```
  *
- * For maps (type `Map`), `filter` applies the predicate function to the value of each entry of the map, returning a new map containing only the entries where the values tested truthy by the predicate. The order of the entries are preserved. On each iteration, the predicate is passed the map value, the key of the value, and a reference to the map.
+ * `filter` applies the predicate to the values of the entries of a map.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
  *
- * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
- * const m = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
+ * const myMap = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
  *
- * console.log(filter(isOdd)(m)) // Map(3) { 'a' => 1, 'c' => 3, 'e' => 5 }
- * console.log(filter(m, isOdd)) // Map(3) { 'a' => 1, 'c' => 3, 'e' => 5 }
+ * const result = filter(myMap, isOdd)
+ * console.log(result) // Map(3) { 'a' => 1, 'c' => 3, 'e' => 5 }
  * ```
  *
- * For iterators (type `Iterator`) or generators (type `Generator`), `filter` returns a lazily filtered iterator/generator; all values that are normally yielded by the iterator/generator that test falsy by the predicate function are skipped by the lazily filtered iterator/generator. On each iteration, the predicate is passed the iteration value only.
+ * For generators, `filter` returns a lazily filtered generator. All values that are normally yielded by the generator that test false by the predicate are excluded from the returned generator.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -167,7 +212,6 @@ const _filter = function (value, predicate) {
  *
  * const numbersGenerator = numbersGeneratorFunction()
  * const oddNumbersGenerator = filter(numbersGeneratorFunction(), isOdd)
- * const oddNumbersGenerator2 = filter(isOdd)(numbersGeneratorFunction())
  *
  * for (const number of numbersGenerator) {
  *   console.log(number) // 1
@@ -182,15 +226,9 @@ const _filter = function (value, predicate) {
  *                       // 3
  *                       // 5
  * }
- *
- * for (const number of oddNumbersGenerator2) {
- *   console.log(number) // 1
- *                       // 3
- *                       // 5
- * }
  * ```
  *
- * With asyncIterators (type `AsyncIterator`) or asyncGenerators (type `AsyncGenerator`), `filter` returns a lazily filtered asyncIterator/asyncGenerator; all values that are normally yielded by the asyncIterator/asyncGenerator that test falsy by the predicate function are skipped by the lazily filtered asyncIterator/asyncGenerator. On each iteration, the predicate is passed the iteration value only.
+ * For async generators, `filter` returns a lazily filtered async generator. All values that are normally yielded by the async generator that test falsy by the predicate are excluded from the returned async generator.
  *
  * ```javascript [playground]
  * const asyncIsOdd = async number => number % 2 == 1
@@ -203,8 +241,6 @@ const _filter = function (value, predicate) {
  *
  * const asyncOddNumbersGenerator = filter(asyncNumbersGeneratorFunction(), asyncIsOdd)
  *
- * const asyncOddNumbersGenerator2 = filter(asyncIsOdd)(asyncNumbersGeneratorFunction())
- *
  * for await (const number of asyncNumbersGenerator) {
  *   console.log(number) // 1
  *                       // 2
@@ -218,12 +254,6 @@ const _filter = function (value, predicate) {
  *                       // 3
  *                       // 5
  * }
- *
- * for await (const number of asyncOddNumbersGenerator2) {
- *   console.log(number) // 1
- *                       // 3
- *                       // 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.
@@ -235,6 +265,14 @@ const _filter = function (value, predicate) {
  * // [1, 3, 5]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @execution concurrent
  *
  * @transducing
@@ -243,7 +281,9 @@ const filter = function (arg0, arg1) {
   if (typeof arg0 == 'function') {
     return curry2(_filter, __, arg0)
   }
-  return _filter(arg0, arg1)
+  return isPromise(arg0)
+    ? arg0.then(curry2(_filter, __, arg1))
+    : _filter(arg0, arg1)
 }
 
 module.exports = filter

package/flatMap.js

@@ -15,13 +15,13 @@ const __ = require('./_internal/placeholder')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type FlatMappable = Array|String|Set|Iterator|AsyncIterator
+ * type Monad = Array|String|Set|Generator|AsyncGenerator
  * type Iterable = Iterable|AsyncIterable|Object<value any>
  *
  * _flatMap(
- *   value FlatMappable,
+ *   m Monad,
  *   flatMapper (item any)=>Promise|Iterable,
- * ) -> result Promise|FlatMappable
+ * ) -> result Promise|Monad
  * ```
  */
 const _flatMap = function (value, flatMapper) {
@@ -64,28 +64,36 @@ const _flatMap = function (value, flatMapper) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type FlatMappable = Array|String|Set|Iterator|AsyncIterator
- *
- * type Iterable = Iterable|AsyncIterable|Object<value any>
+ * type Monad = Array|String|Set|Generator|AsyncGenerator|{ flatMap: string }|{ chain: string }|Object
  *
  * type FlatMapper = (
  *   item any,
- *   indexOrKey string,
- *   collection FlatMappable
- * )=>Promise|FlatMappable
+ *   indexOrKey number|string|any,
+ *   mon Monad
+ * )=>Promise|Monad|any
  *
- * flatMap(collection FlatMappable, flatMapper FlatMapper) -> result Promise|FlatMappable
- * flatMap(flatMapper FlatMapper)(collection FlatMappable) -> result Promise|FlatMappable
+ * flatMap(mon Monad, flatMapper FlatMapper) -> result Promise|Monad
+ * flatMap(flatMapper FlatMapper)(mon Monad) -> result Promise|Monad
  * ```
  *
  * @description
- * Applies a flatMapper function concurrently to each item of a collection, creating a new collection of the same type. A flatMapping operation iterates through each item of a collection and applies the flatMapper function to each item, flattening the result of the execution into the result collection. The result of an individual execution can be any iterable, async iterable, or object values iterable collection. The flatMapper function may be asynchronous.
+ * Applies a flatMapper function to each item of a monad, returning a monad of the same type.
+ *
+ * A flatMapping operation iterates through each item of a monad and applies the flatMapper function to each item, flattening the result of the execution into the returned monad.
  *
- *  * `Iterable` - the execution result is iterated and each item is added to the result collection
- *  * `AsyncIterable` - the execution result is asynchronously iterated and each item is added to the result collection
- *  * `Object` - the execution result values are added to the result collection
+ * 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.
  *
- * The following example demonstrates various execution results being flattened into the same array.
+ * The following data types are considered to be monads, all are flattenable into other monads:
+ *  * `array`
+ *  * `string`
+ *  * `set`
+ *  * `genreator`
+ *  * `async generator`
+ *  * `object with .flatMap method`
+ *  * `object with .chain method`
+ *  * `object`
+ *
+ * `flatMap` flattens various data types.
  *
  * ```javascript [playground]
  * const identity = value => value
@@ -93,15 +101,15 @@ const _flatMap = function (value, flatMapper) {
  * flatMap(identity)([
  *   [1, 1], // array
  *   new Set([2, 2]), // set
- *   (function* () { yield 3; yield 3 })(), // generator
- *   (async function* () { yield 7; yield 7 })(), // asyncGenerator
+ *   (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]
  * ```
  *
- * A flatMapping operation concatenates onto the resulting collection synchronous values and muxes any asynchronous values. 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 items.
+ * 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 items.
  *
  * ```javascript [playground]
  * const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
@@ -122,12 +130,12 @@ const _flatMap = function (value, flatMapper) {
  *   yield message
  * }
  *
- * // async is muxed
+ * // values from async generators are muxed
  * flatMap(['foo', 'bar', 'baz'], asyncRepeat3).then(console.log)
  * // ['foo', 'bar', 'baz', 'foo', 'bar', 'baz', 'foo', 'bar', 'baz']
  * ```
  *
- * For arrays (type `Array`), `flatMap` applies the flatMapper function to each item, pushing (`.push`) the items of each execution into a new array.
+ * `flatMap` applies the flatMapper function to each item of an array, flattening the results into a new array.
  *
  * ```javascript [playground]
  * const duplicate = value => [value, value]
@@ -137,7 +145,7 @@ const _flatMap = function (value, flatMapper) {
  * ) // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
  * ```
  *
- * For strings (type `String`), `flatMap` applies the flatMapper function to each character, adding (`+`) the items of each execution into a new string
+ * `flatMap` acts on each character of a string.
  *
  * ```javascript [playground]
  * const duplicate = value => [value, value]
@@ -147,16 +155,6 @@ const _flatMap = function (value, flatMapper) {
  * ) // 1122334455
  * ```
  *
- * For sets (type `Set`), `flatMap` applies the flatMapper function to each item, adding (`.add`) the items of each execution into a new set
- *
- * ```javascript [playground]
- * const pairPlus100 = value => [value, value + 100]
- *
- * console.log(
- *   flatMap(new Set([1, 2, 3, 4, 5]), pairPlus100)
- * ) // Set(10) { 1, 101, 2, 102, 3, 103, 4, 104, 5, 105 }
- * ```
- *
  * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
  *
  * ```javascript [playground]
@@ -164,6 +162,14 @@ const _flatMap = function (value, flatMapper) {
  * // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [transform](/docs/transform)
+ *  * [some](/docs/some)
+ *
  * @execution concurrent
  *
  * @transducing

package/forEach.js

@@ -45,20 +45,86 @@ const _forEach = function (collection, callback) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Collection = Array|Iterable|AsyncIterable|{ forEach: function }|Object
+ * type Iterable = Array|Set|Map|Generator|AsyncGenerator|{ forEach: function }|Object
+ *
+ * type Callback = (
+ *   item any,
+ *   indexOrKey number|string|any,
+ *   iter Iterable
+ * )=>Promise|undefined
  *
- * forEach(collection Collection, callback function) -> collection Promise|Collection
+ * forEach(iter Iterable, cb Callback) -> iter Promise|Iterable
  *
- * forEach(callback function)(collection Collection) -> collection Promise|Collection
+ * forEach(cb Callback)(iter Iterable) -> iter Promise|Iterable
  * ```
  *
  * @description
- * Execute a callback for each item of a collection, returning a Promise if the execution is asynchronous. Asynchronous execution happens concurrently.
+ * Execute a callback function for each item of an iterable, returning the original iterable unmodified.
+ *
+ * The following data types are considered to be iterables:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .forEach method`
+ *  * `object`
+ *
+ * The callback function signature changes depending on the provided iterable.
+ *
+ * If the iterable is an array:
+ * ```coffeescript [specscript]
+ * callback(item any, index number, iter Array) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is a set:
+ * ```coffeescript [specscript]
+ * callback(item any, key any, iter Set) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is a map:
+ * ```coffeescript [specscript]
+ * callback(item any, key any, filt Map) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is a generator:
+ * ```coffeescript [specscript]
+ * callback(item any) -> Promise|undefined
+ * ```
+ *
+ * If the iterable is an async generator:
+ * ```coffeescript [specscript]
+ * 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(item any, key string, iter Object) -> Promise|undefined
+ * ```
+ *
+ * If the callback function is asynchronous, it is executed concurrently.
+ *
+ * ```javascript [playground]
+ * forEach([1, 2, 3, 4, 5], async number => {
+ *   await new Promise(resolve => {
+ *     setTimeout(resolve, 1000)
+ *   })
+ *   console.log(number)
+ * })
+ * ```
+ *
+ * `forEach` works for arrays.
  *
  * ```javascript [playground]
- * forEach([1, 2, 3, 4, 5], console.log) // 1 2 3 4 5
+ * forEach([1, 2, 3, 4, 5], num => console.log(num)) // 1 2 3 4 5
+ * ```
+ *
+ * `forEach` works for objects.
  *
- * forEach({ a: 1, b: 2, c: 3 }, console.log) // 1 2 3
+ * ```javascript [playground]
+ * forEach({ a: 1, b: 2, c: 3 }, num => console.log(num)) // 1 2 3
  * ```
  *
  * Omit the data argument for a composable API
@@ -81,6 +147,13 @@ const _forEach = function (collection, callback) {
  * // 2
  * // 3
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [tap](/docs/tap)
+ *  * [all](/docs/all)
+ *  * [forEach.series](/docs/forEach.series)
+ *  * [map](/docs/map)
  */
 const forEach = function (arg0, arg1) {
   if (typeof arg0 == 'function') {
@@ -125,20 +198,34 @@ const _forEachSeries = function (collection, callback) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Collection = Array|Iterable|AsyncIterable|{ forEach: function }|Object
+ * type Iterable = Array|Set|Map|Generator|AsyncGenerator|{ forEach: function }|Object
+ *
+ * type Callback = (
+ *   item any,
+ *   indexOrKey number|string|any,
+ *   iter Iterable
+ * )=>Promise|undefined
  *
- * forEach.series(collection Collection, callback function) -> collection Promise|Collection
+ * forEach(iter Iterable, cb Callback) -> iter Promise|Iterable
  *
- * forEach.series(callback function)(collection Collection) -> collection Promise|Collection
+ * forEach(cb Callback)(iter Iterable) -> iter Promise|Iterable
  * ```
  *
  * @description
- * Execute a callback for each item of a collection, returning a Promise if the execution is asynchronous. Asynchronous execution happens in series.
+ * [forEach](/docs/forEach) with serial execution.
  *
  * ```javascript [playground]
- * forEach.series([1, 2, 3, 4, 5], console.log) // 1 2 3 4 5
- *
- * forEach.series({ a: 1, b: 2, c: 3 }, console.log) // 1 2 3
+ * forEach.series([1, 2, 3, 4, 5], async number => {
+ *   await new Promise(resolve => {
+ *     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.
@@ -149,6 +236,13 @@ const _forEachSeries = function (collection, callback) {
  * // 2
  * // 3
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [tap](/docs/tap)
+ *  * [all](/docs/all)
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
  */
 forEach.series = function forEachSeries(arg0, arg1) {
   if (typeof arg0 == 'function') {

package/get.js

@@ -86,6 +86,15 @@ const _get = function (object, path, defaultValue) {
  * ```javascript [playground]
  * get(Promise.resolve({ a: 1 }), 'a').then(console.log) // 1
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [all](/docs/all)
+ *  * [assign](/docs/assign)
+ *  * [set](/docs/set)
+ *  * [pick](/docs/pick)
+ *  * [omit](/docs/omit)
+ *  * [forEach](/docs/forEach)
  */
 
 const get = function (arg0, arg1, arg2) {

package/gt.js

@@ -53,6 +53,15 @@ const greaterThan = require('./_internal/greaterThan')
  * ```javascript [playground]
  * gt(Promise.resolve({ a: 2, b: 1 }), get('a'), get('b')).then(console.log) // true
  * ```
+ *
+ * See also:
+ *  * [and](/docs/and)
+ *  * [eq](/docs/eq)
+ *  * [lt](/docs/lt)
+ *  * [gte](/docs/gte)
+ *  * [lte](/docs/lte)
+ *  * [thunkify](/docs/thunkify)
+ *
  */
 const gt = ComparisonOperator(greaterThan)
 

package/gte.js

@@ -55,6 +55,15 @@ const greaterThanOrEqual = require('./_internal/greaterThanOrEqual')
  * ```javascript [playground]
  * gte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
  * ```
+ *
+ * See also:
+ *  * [and](/docs/and)
+ *  * [eq](/docs/eq)
+ *  * [lt](/docs/lt)
+ *  * [gt](/docs/gt)
+ *  * [lte](/docs/lte)
+ *  * [thunkify](/docs/thunkify)
+ *
  */
 const gte = ComparisonOperator(greaterThanOrEqual)