rubico 2.6.5 → 2.6.6

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,7 +90,7 @@ const _filter = function (value, predicate) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Filterable = Array|Object|Set|Map|Iterator|AsyncIterator
+ * type Filterable = Array|Object|Set|Generator|AsyncGenerator
  *
  * type Predicate = (
  *   value any,
@@ -97,66 +98,74 @@ const _filter = function (value, predicate) {
  *   collection Filterable,
  * )=>boolean
  *
- * filter(collection Filterable, predicate Predicate) -> result Promise|Filterable
- * filter(predicate Predicate)(collection Filterable) -> result Promise|Filterable
+ * filter(f Map|Filterable, predicate Predicate) -> result Promise|Map|Filterable
+ * filter(predicate Predicate)(f Map|Filterable) -> result Promise|Map|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:
+ * Filter out items from a filterable. Returns a filterable of the same type.
  *
- *  * `Array`
- *  * `Object`
- *  * `Set`
- *  * `Map`
- *  * `Iterator`/`Generator`
- *  * `AsyncIterator`/`AsyncGenerator`
+ * The following data types are considered filterable:
+ *  * `array`
+ *  * `object`
+ *  * `set`
+ *  * `generator`
+ *  * `async generator`
  *
- * 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.
+ * 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 a boolean value involving item
+ *   return condition
+ * }
+ * ```
+ *
+ * `filter` applies a provided predicate function to each item of a filterable, returning a filterable of the same type containing only the items with truthy conditions by the predicate. The order of the items is preserved.
  *
  * ```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.
+ * The predicate may be asynchronous, in which case the returned promise is concurrently resolved for its boolean condition before deciding whether to include the corresponding item in the result.
  *
  * ```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.
+ * For objects, `filter` applies the predicate function to just the values.
  *
  * ```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.
+ * For maps, `filter` applies the predicate to the values of the entries. The order of the entries is preserved.
  *
  * ```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 falsy by the predicate are skipped.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -167,7 +176,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 +190,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 skipped.
  *
  * ```javascript [playground]
  * const asyncIsOdd = async number => number % 2 == 1
@@ -203,8 +205,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 +218,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.
@@ -243,7 +237,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|Iterator|AsyncIterator
  * 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,35 @@ 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|Iterator|AsyncIterator
+ * type Flattenable = Iterable|AsyncIterable|Object<value any>
  *
  * type FlatMapper = (
  *   item any,
  *   indexOrKey string,
- *   collection FlatMappable
- * )=>Promise|FlatMappable
+ *   m Monad
+ * )=>Promise|Flattenable|any
  *
- * flatMap(collection FlatMappable, flatMapper FlatMapper) -> result Promise|FlatMappable
- * flatMap(flatMapper FlatMapper)(collection FlatMappable) -> result Promise|FlatMappable
+ * flatMap(m Monad, flatMapper FlatMapper) -> result Promise|Monad
+ * flatMap(flatMapper FlatMapper)(m 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 concurrently 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. The result of an individual execution can be any iterable, async iterable, or object with enumerable values. The flatMapper function may be asynchronous.
+ *
+ * The following data types are considered monads:
+ *  * `array`
+ *  * `string`
+ *  * `set`
+ *  * `iterator`
+ *  * `async iterator`
  *
- *  * `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
+ * The following data types are considered flattenable:
+ *  * `iterable` - the execution result is iterated and each item is added to the result collection
+ *  * `async iterable` - 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
  *
- * The following example demonstrates various execution results being flattened into the same array.
+ * `flatMap` can flatten various data types.
  *
  * ```javascript [playground]
  * const identity = value => value
@@ -101,7 +108,7 @@ const _flatMap = function (value, flatMapper) {
  * // [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.
+ * `flatMap` muxes 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.
  *
  * ```javascript [playground]
  * const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
@@ -137,7 +144,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 +154,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]

package/index.js

@@ -1,7 +1,7 @@
 /**
- * rubico v2.6.2
+ * rubico v2.6.6
  * https://github.com/a-synchronous/rubico
- * (c) 2019-2024 Richard Tong
+ * (c) 2019-2025 Richard Tong
  * rubico may be freely distributed under the MIT license.
  */
 
@@ -429,26 +429,6 @@ const all = function (...args) {
   return isArray(resolversOrValues)
     ? functionArrayAll(resolversOrValues, argValues)
     : functionObjectAll(resolversOrValues, argValues)
-
-  /*
-  ////////////////////////////////////////////////////////////////
-  const funcs = args.pop()
-  if (args.length == 0) {
-    return isArray(funcs)
-      ? curryArgs2(functionArrayAll, funcs, __)
-      : curryArgs2(functionObjectAll, funcs, __)
-  }
-
-  if (areAnyValuesPromises(args)) {
-    return isArray(funcs)
-      ? promiseAll(args).then(curry2(functionArrayAll, funcs, __))
-      : promiseAll(args).then(curry2(functionObjectAll, funcs, __))
-  }
-
-  return isArray(funcs)
-    ? functionArrayAll(funcs, args)
-    : functionObjectAll(funcs, args)
-  */
 }
 
 all.series = function allSeries(...args) {
@@ -1179,39 +1159,39 @@ const mapMapEntries = function (source, mapper) {
     : promiseAll(promises).then(always(result))
 }
 
-const _map = function (value, mapper) {
+const _map = function (value, f) {
   if (isArray(value)) {
-    return arrayMap(value, mapper)
+    return arrayMap(value, f)
   }
   if (value == null) {
     return value
   }
 
   if (typeof value.then == 'function') {
-    return value.then(mapper)
+    return value.then(f)
   }
   if (typeof value.map == 'function') {
-    return value.map(mapper)
+    return value.map(f)
   }
   if (typeof value == 'string' || value.constructor == String) {
-    return stringMap(value, mapper)
+    return stringMap(value, f)
   }
   if (value.constructor == Set) {
-    return setMap(value, mapper)
+    return setMap(value, f)
   }
   if (value.constructor == Map) {
-    return mapMap(value, mapper)
+    return mapMap(value, f)
   }
   if (typeof value[symbolIterator] == 'function') {
-    return MappingIterator(value[symbolIterator](), mapper)
+    return MappingIterator(value[symbolIterator](), f)
   }
   if (typeof value[symbolAsyncIterator] == 'function') {
-    return MappingAsyncIterator(value[symbolAsyncIterator](), mapper)
+    return MappingAsyncIterator(value[symbolAsyncIterator](), f)
   }
   if (value.constructor == Object) {
-    return objectMap(value, mapper)
+    return objectMap(value, f)
   }
-  return mapper(value)
+  return f(value)
 }
 
 const map = function (arg0, arg1) {
@@ -1223,16 +1203,16 @@ const map = function (arg0, arg1) {
     : _map(arg0, arg1)
 }
 
-// _mapEntries(value Object|Map, mapper function) -> Object|Map
-const _mapEntries = (value, mapper) => {
+// _mapEntries(value Object|Map, f function) -> Object|Map
+const _mapEntries = (value, f) => {
   if (value == null) {
     throw new TypeError('value is not an Object or Map')
   }
   if (value.constructor == Object) {
-    return objectMapEntries(value, mapper)
+    return objectMapEntries(value, f)
   }
   if (value.constructor == Map) {
-    return mapMapEntries(value, mapper)
+    return mapMapEntries(value, f)
   }
   throw new TypeError('value is not an Object or Map')
 }
@@ -1278,26 +1258,26 @@ map.series = function mapSeries(arg0, arg1) {
     : _mapSeries(arg0, arg1)
 }
 
-const _mapPool = function (collection, concurrency, f) {
-  if (isArray(collection)) {
-    return arrayMapPool(collection, concurrency, f)
+const _mapPool = function (f, concurrency, mapper) {
+  if (isArray(f)) {
+    return arrayMapPool(f, concurrency, mapper)
   }
-  if (collection == null) {
-    throw new TypeError(`invalid collection ${collection}`)
+  if (f == null) {
+    throw new TypeError(`invalid functor ${f}`)
   }
-  if (typeof collection == 'string' || collection.constructor == String) {
-    return stringMapPool(collection, concurrency, f)
+  if (typeof f == 'string' || f.constructor == String) {
+    return stringMapPool(f, concurrency, mapper)
   }
-  if (collection.constructor == Set) {
-    return setMapPool(collection, concurrency, f)
+  if (f.constructor == Set) {
+    return setMapPool(f, concurrency, mapper)
   }
-  if (collection.constructor == Map) {
-    return mapMapPool(collection, concurrency, f)
+  if (f.constructor == Map) {
+    return mapMapPool(f, concurrency, mapper)
   }
-  if (collection.constructor == Object) {
-    return objectMapPool(collection, concurrency, f)
+  if (f.constructor == Object) {
+    return objectMapPool(f, concurrency, mapper)
   }
-  throw new TypeError(`invalid collection ${collection}`)
+  throw new TypeError(`invalid functor ${f}`)
 }
 
 map.pool = function mapPool(arg0, arg1, arg2) {
@@ -1502,7 +1482,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)
 }
 
 const objectValues = Object.values