rubico 2.7.2 → 2.7.4

package/_internal/reducerMap.js

@@ -21,11 +21,11 @@ const curry2 = require('./curry2')
  */
 const reducerMap = (
   reducer, mapper,
-) => function mappingReducer(result, reducerItem) {
-  const mappingReducerItem = mapper(reducerItem)
-  return isPromise(mappingReducerItem)
-    ? mappingReducerItem.then(curry2(reducer, result, __))
-    : reducer(result, mappingReducerItem)
+) => function mappingReducer(result, reducerElement) {
+  const mappingReducerElement = mapper(reducerElement)
+  return isPromise(mappingReducerElement)
+    ? mappingReducerElement.then(curry2(reducer, result, __))
+    : reducer(result, mappingReducerElement)
 }
 
 module.exports = reducerMap

package/_internal/reducerSome.d.ts

@@ -6,11 +6,11 @@ export = reducerSome;
  * ```coffeescript [specscript]
  * reducerSome(
  *   predicate any=>boolean,
- * ) -> anyReducer (result boolean, item any)=>boolean
+ * ) -> anyReducer (result boolean, element any)=>boolean
  * ```
  *
  * @related foldableAllReducer
  *
  * @TODO throw to break early?
  */
-declare function reducerSome(predicate: any): (result: any, item: any) => any;
+declare function reducerSome(predicate: any): (result: any, element: any) => any;

package/_internal/reducerSome.js

@@ -10,17 +10,17 @@ const isPromise = require('./isPromise')
  * ```coffeescript [specscript]
  * reducerSome(
  *   predicate any=>boolean,
- * ) -> anyReducer (result boolean, item any)=>boolean
+ * ) -> anyReducer (result boolean, element any)=>boolean
  * ```
  *
  * @related foldableAllReducer
  *
  * @TODO throw to break early?
  */
-const reducerSome = predicate => function anyReducer(result, item) {
+const reducerSome = predicate => function anyReducer(result, element) {
   return result === true ? result
-    : isPromise(result) ? result.then(curry2(reducerAnySync(predicate), __, item))
-    : result ? true : predicate(item)
+    : isPromise(result) ? result.then(curry2(reducerAnySync(predicate), __, element))
+    : result ? true : predicate(element)
 }
 
 module.exports = reducerSome

package/_internal/reducerTryCatch.d.ts

@@ -4,7 +4,7 @@ export = reducerTryCatch;
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Reducer = (accum any, item any)=>(nextAccumulator Promise|any)
+ * type Reducer = (accum any, element any)=>(nextAccumulator Promise|any)
  *
  * reducerTryCatch(
  *   reducer function,
@@ -12,4 +12,4 @@ export = reducerTryCatch;
  * ) -> errorHandlingReducer function
  * ```
  */
-declare function reducerTryCatch(reducer: any, transducerTryer: any, catcher: any): (accum: any, item: any) => any;
+declare function reducerTryCatch(reducer: any, transducerTryer: any, catcher: any): (accum: any, element: any) => any;

package/_internal/reducerTryCatch.js

@@ -12,14 +12,14 @@ const curry2 = require('./curry2')
  *   reducer function,
  *   error Error,
  *   accum any,
- *   item any,
+ *   element any,
  * ) -> Promise|any
  * ```
  */
 const _reducerTryCatchErrorHandler = function (
-  catcher, reducer, error, accum, item,
+  catcher, reducer, error, accum, element,
 ) {
-  const c = catcher(error, item)
+  const c = catcher(error, element)
   return isPromise(c) ? c.then(curry2(reducer, accum, __)) : reducer(accum, c)
 }
 
@@ -28,7 +28,7 @@ const _reducerTryCatchErrorHandler = function (
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Reducer = (accum any, item any)=>(nextAccumulator Promise|any)
+ * type Reducer = (accum any, element any)=>(nextAccumulator Promise|any)
  *
  * reducerTryCatch(
  *   reducer function,
@@ -38,15 +38,15 @@ const _reducerTryCatchErrorHandler = function (
  */
 const reducerTryCatch = function (reducer, transducerTryer, catcher) {
   const finalReducer = transducerTryer(reducer)
-  return function errorHandlingReducer(accum, item) {
+  return function errorHandlingReducer(accum, element) {
     try {
-      const ret = finalReducer(accum, item)
+      const ret = finalReducer(accum, element)
       return isPromise(ret) ? ret.catch(curry5(
-        _reducerTryCatchErrorHandler, catcher, reducer, __, accum, item,
+        _reducerTryCatchErrorHandler, catcher, reducer, __, accum, element,
       )) : ret
     } catch (error) {
       return _reducerTryCatchErrorHandler(
-        catcher, reducer, error, accum, item,
+        catcher, reducer, error, accum, element,
       )
     }
   }

package/_internal/setFilter.d.ts

@@ -11,6 +11,6 @@ export = setFilter;
  * ```
  *
  * @description
- * Filter items of a Set concurrently by predicate. `predicate` may be asynchronous.
+ * Filter elements of a Set concurrently by predicate. `predicate` may be asynchronous.
  */
 declare function setFilter(value: any, predicate: any): any;

package/_internal/setFilter.js

@@ -19,19 +19,19 @@ const noop = require('./noop')
  * ```
  *
  * @description
- * Filter items of a Set concurrently by predicate. `predicate` may be asynchronous.
+ * Filter elements of a Set concurrently by predicate. `predicate` may be asynchronous.
  */
 const setFilter = function (value, predicate) {
   const result = new Set(),
     resultAdd = result.add.bind(result),
     promises = []
-  for (const item of value) {
-    const predication = predicate(item, item, value)
+  for (const element of value) {
+    const predication = predicate(element, element, value)
     if (isPromise(predication)) {
       promises.push(predication.then(curry3(
-        thunkConditional, __, thunkify1(resultAdd, item), noop)))
+        thunkConditional, __, thunkify1(resultAdd, element), noop)))
     } else if (predication) {
-      result.add(item)
+      result.add(element)
     }
   }
   return promises.length == 0

package/_internal/setFlatten.js

@@ -30,45 +30,45 @@ const setFlatten = function (set) {
   const size = set.size,
     promises = [],
     result = new Set(),
-    resultAddReducer = (_, subItem) => result.add(subItem),
+    resultAddReducer = (_, subElement) => result.add(subElement),
     resultAdd = curry3(callPropUnary, result, 'add', __),
     getResult = () => result
 
-  for (const item of set) {
-    if (isArray(item)) {
-      const itemLength = item.length
-      let itemIndex = -1
-      while (++itemIndex < itemLength) {
-        result.add(item[itemIndex])
+  for (const element of set) {
+    if (isArray(element)) {
+      const elementLength = element.length
+      let elementIndex = -1
+      while (++elementIndex < elementLength) {
+        result.add(element[elementIndex])
       }
-    } else if (item == null) {
-      result.add(item)
-    } else if (typeof item[symbolIterator] == 'function') {
-      for (const subItem of item) {
-        result.add(subItem)
+    } else if (element == null) {
+      result.add(element)
+    } else if (typeof element[symbolIterator] == 'function') {
+      for (const subElement of element) {
+        result.add(subElement)
       }
-    } else if (typeof item[symbolAsyncIterator] == 'function') {
+    } else if (typeof element[symbolAsyncIterator] == 'function') {
       promises.push(
-        asyncIteratorForEach(item[symbolAsyncIterator](), resultAdd))
-    } else if (typeof item.chain == 'function') {
-      const monadValue = item.chain(identity)
+        asyncIteratorForEach(element[symbolAsyncIterator](), resultAdd))
+    } else if (typeof element.chain == 'function') {
+      const monadValue = element.chain(identity)
       isPromise(monadValue)
         ? promises.push(monadValue.then(resultAdd))
         : result.add(monadValue)
-    } else if (typeof item.flatMap == 'function') {
-      const monadValue = item.flatMap(identity)
+    } else if (typeof element.flatMap == 'function') {
+      const monadValue = element.flatMap(identity)
       isPromise(monadValue)
         ? promises.push(monadValue.then(resultAdd))
         : result.add(monadValue)
-    } else if (typeof item.reduce == 'function') {
-      const folded = item.reduce(resultAddReducer, null)
+    } else if (typeof element.reduce == 'function') {
+      const folded = element.reduce(resultAddReducer, null)
       isPromise(folded) && promises.push(folded)
-    } else if (item.constructor == Object) {
-      for (const key in item) {
-        result.add(item[key])
+    } else if (element.constructor == Object) {
+      for (const key in element) {
+        result.add(element[key])
       }
     } else {
-      result.add(item)
+      result.add(element)
     }
   }
   return promises.length == 0 ? result : promiseAll(promises).then(getResult)

package/_internal/setMap.d.ts

@@ -12,6 +12,6 @@ export = setMap;
  * ```
  *
  * @description
- * Apply a mapper concurrently to each item of a set, returning a set of results.
+ * Apply a mapper concurrently to each element of a set, returning a set of results.
  */
 declare function setMap(set: any, mapper: any): any;

package/_internal/setMap.js

@@ -18,17 +18,17 @@ const callPropUnary = require('./callPropUnary')
  * ```
  *
  * @description
- * Apply a mapper concurrently to each item of a set, returning a set of results.
+ * Apply a mapper concurrently to each element of a set, returning a set of results.
  */
 const setMap = function (set, mapper) {
   const result = new Set(),
     promises = []
-  for (const item of set) {
-    const resultItem = mapper(item, item, set)
-    if (isPromise(resultItem)) {
-      promises.push(resultItem.then(curry3(callPropUnary, result, 'add', __)))
+  for (const element of set) {
+    const resultElement = mapper(element, element, set)
+    if (isPromise(resultElement)) {
+      promises.push(resultElement.then(curry3(callPropUnary, result, 'add', __)))
     } else {
-      result.add(resultItem)
+      result.add(resultElement)
     }
   }
   return promises.length == 0

package/_internal/setMapPool.js

@@ -26,15 +26,15 @@ const _setMapPoolAsync = async function (
     if (promises.size >= concurrency) {
       await promiseRace(promises)
     }
-    const resultItem = f(iteration.value, iteration.value, s)
-    if (isPromise(resultItem)) {
-      const selfDeletingPromise = resultItem.then(resolvedValue => {
+    const resultElement = f(iteration.value, iteration.value, s)
+    if (isPromise(resultElement)) {
+      const selfDeletingPromise = resultElement.then(resolvedValue => {
         promises.delete(selfDeletingPromise)
         result.add(resolvedValue)
       })
       promises.add(selfDeletingPromise)
     } else {
-      result.add(resultItem)
+      result.add(resultElement)
     }
     iteration = iterator.next()
   }
@@ -53,24 +53,24 @@ const _setMapPoolAsync = async function (
  * ```
  *
  * @description
- * Apply a function `f` with limited concurrency to each item of a set `s`, returning an array of results.
+ * Apply a function `f` with limited concurrency to each element of a set `s`, returning an array of results.
  */
 const setMapPool = function (s, concurrency, f) {
   const result = new Set()
   const iterator = s[symbolIterator]()
   let iteration = iterator.next()
   while (!iteration.done) {
-    const resultItem = f(iteration.value, iteration.value, s)
-    if (isPromise(resultItem)) {
+    const resultElement = f(iteration.value, iteration.value, s)
+    if (isPromise(resultElement)) {
       const promises = new Set()
-      const selfDeletingPromise = resultItem.then(resolvedValue => {
+      const selfDeletingPromise = resultElement.then(resolvedValue => {
         promises.delete(selfDeletingPromise)
         result.add(resolvedValue)
       })
       promises.add(selfDeletingPromise)
       return _setMapPoolAsync(s, iterator, concurrency, f, result, promises)
     }
-    result.add(resultItem)
+    result.add(resultElement)
     iteration = iterator.next()
   }
   return result

package/_internal/setMapSeries.js

@@ -14,11 +14,11 @@ const symbolIterator = require('./symbolIterator')
 const _setMapSeriesAsync = async function (iterator, f, result) {
   let iteration = iterator.next()
   while (!iteration.done) {
-    let resultItem = f(iteration.value)
-    if (isPromise(resultItem)) {
-      resultItem = await resultItem
+    let resultElement = f(iteration.value)
+    if (isPromise(resultElement)) {
+      resultElement = await resultElement
     }
-    result.add(resultItem)
+    result.add(resultElement)
     iteration = iterator.next()
   }
   return result
@@ -33,27 +33,27 @@ const _setMapSeriesAsync = async function (iterator, f, result) {
  *   value any,
  *   key any,
  *   collection Set
- * )=>(resultItem Promise|any)
+ * )=>(resultElement Promise|any)
  *
  * setMapSeries(set Set, f SetMapper) -> Promise|Set
  * ```
  *
  * @description
- * Apply a mapper in series to each value of a set, returning a new set of mapped items. Mapper may be asynchronous.
+ * Apply a mapper in series to each value of a set, returning a new set of mapped elements. Mapper may be asynchronous.
  */
 const setMapSeries = function (set, f) {
   const result = new Set()
   const iterator = set[symbolIterator]()
   let iteration = iterator.next()
   while (!iteration.done) {
-    const resultItem = f(iteration.value)
-    if (isPromise(resultItem)) {
-      return resultItem.then(funcConcat(
+    const resultElement = f(iteration.value)
+    if (isPromise(resultElement)) {
+      return resultElement.then(funcConcat(
         curry2(setAdd, result, __),
         thunkify3(_setMapSeriesAsync, iterator, f, result),
       ))
     }
-    result.add(resultItem)
+    result.add(resultElement)
     iteration = iterator.next()
   }
   return result

package/_internal/streamFlatExtend.js

@@ -26,49 +26,49 @@ const symbolAsyncIterator = require('./symbolAsyncIterator')
  *
  * streamFlatExtend<T>(
  *   stream Stream<T>,
- *   item <Monad<T>|Foldable<T>|T>
+ *   element <Monad<T>|Foldable<T>|T>
  * ) -> stream
  * ```
  */
-const streamFlatExtend = async function (stream, item) {
+const streamFlatExtend = async function (stream, element) {
   const resultStreamWrite = curry2(streamWrite, stream, __),
-    // resultStreamWriteReducer = (_, subItem) => stream.write(subItem),
+    // resultStreamWriteReducer = (_, subElement) => stream.write(subElement),
     resultStreamWriteReducer = funcConcatSync(getArg1, resultStreamWrite),
     promises = []
-  if (isArray(item)) {
-    const itemLength = item.length
-    let itemIndex = -1
-    while (++itemIndex < itemLength) {
-      stream.write(item[itemIndex])
+  if (isArray(element)) {
+    const elementLength = element.length
+    let elementIndex = -1
+    while (++elementIndex < elementLength) {
+      stream.write(element[elementIndex])
     }
-  } else if (item == null) {
-    stream.write(item)
-  } else if (typeof item[symbolIterator] == 'function') {
-    for (const subItem of item) {
-      stream.write(subItem)
+  } else if (element == null) {
+    stream.write(element)
+  } else if (typeof element[symbolIterator] == 'function') {
+    for (const subElement of element) {
+      stream.write(subElement)
     }
-  } else if (typeof item[symbolAsyncIterator] == 'function') {
+  } else if (typeof element[symbolAsyncIterator] == 'function') {
     promises.push(
-      asyncIteratorForEach(item[symbolAsyncIterator](), resultStreamWrite))
-  } else if (typeof item.chain == 'function') {
-    const monadValue = item.chain(identity)
+      asyncIteratorForEach(element[symbolAsyncIterator](), resultStreamWrite))
+  } else if (typeof element.chain == 'function') {
+    const monadValue = element.chain(identity)
     isPromise(monadValue)
       ? promises.push(monadValue.then(resultStreamWrite))
       : stream.write(monadValue)
-  } else if (typeof item.flatMap == 'function') {
-    const monadValue = item.flatMap(identity)
+  } else if (typeof element.flatMap == 'function') {
+    const monadValue = element.flatMap(identity)
     isPromise(monadValue)
       ? promises.push(monadValue.then(resultStreamWrite))
       : stream.write(monadValue)
-  } else if (typeof item.reduce == 'function') {
-    const folded = item.reduce(resultStreamWriteReducer, null)
+  } else if (typeof element.reduce == 'function') {
+    const folded = element.reduce(resultStreamWriteReducer, null)
     isPromise(folded) && promises.push(folded)
-  } else if (item.constructor == Object) {
-    for (const key in item) {
-      stream.write(item[key])
+  } else if (element.constructor == Object) {
+    for (const key in element) {
+      stream.write(element[key])
     }
   } else {
-    stream.write(item)
+    stream.write(element)
   }
   return promises.length == 0
     ? stream

package/_internal/streamFlatMap.js

@@ -24,8 +24,8 @@ const promiseAll = require('./promiseAll')
  */
 const streamFlatMap = async function (stream, flatMapper) {
   const promises = new Set()
-  for await (const item of stream) {
-    const monad = flatMapper(item)
+  for await (const element of stream) {
+    const monad = flatMapper(element)
     if (isPromise(monad)) {
       const selfDeletingPromise = monad.then(
         curry2(streamFlatExtend, stream, __)).then(

package/all.js

@@ -36,30 +36,27 @@ const _allValues = function (values) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * all(values Promise|Array<Promise|any>) -> result Promise|Array
- * all(values Promise|Object<Promise|any>) -> result Promise|Object
- *
- * all(
- *   ...args,
- *   resolversOrValues Array<function|Promise|any>
- * ) -> result Promise|Array
- *
- * all(
- *   resolversOrValues Array<function|Promise|any>
- * )(...args) -> result Promise|Array
- *
- * all(
- *   ...args,
- *   resolversOrValues Object<function|Promise|any>
- * ) -> result Promise|Object
- *
- * all(
- *   resolversOrValues Object<function|Promise|any>
- * )(...args) -> result Promise|Object
+ * args Array<any>
+ * argsOrPromises Array<Promise|any>
+ *
+ * type SyncOrAsyncResolver = (...args)=>Promise|any
+ *
+ * arrayResolversOrPromisesOrValues Array<SyncOrAsyncResolver|Promise|any>
+ * objectResolversOrPromisesOrValues Object<SyncOrAsyncResolver|Promise|any>
+ *
+ * all(arrayValues Promise|Array<Promise|any>) -> arrayResult Promise|Array
+ * all(...argsOrPromises, arrayResolversOrPromisesOrValues) -> arrayResult Promise|Array
+ * all(arrayResolversOrPromisesOrValues)(...args) -> arrayResult Promise|Array
+ *
+ * all(objectValues Promise|Object<Promise|any>) -> objectResult Promise|Object
+ * all(...argsOrPromises, objectResolversOrPromisesOrValues) -> objectResult Promise|Object
+ * all(objectResolversOrPromisesOrValues)(...args) -> objectResult Promise|Object
  * ```
  *
  * @description
- * Calls an array or object of resolver functions or values `resolversOrValues` with provided arguments.
+ * Constructs an array if provided an array of resolvers, promises, values, or a mix thereof. Constructs an object if provided an object of resolvers, promises, values, or a mix thereof. If provided any resolvers, `all` returns a function that constructs the array or object. Otherwise, if none of the provided values in the array or object are functions, `all` returns the constructed array or object directly.
+ *
+ * `all` constructs an array from resolvers.
  *
  * ```javascript [playground]
  * const createArrayOfGreetingsFor = all([
@@ -74,23 +71,25 @@ const _allValues = function (values) {
  * // ['Hi 1', 'Hey 1', 'Hello 1']
  * ```
  *
- * If provided only values for `resolversOrValues`, returns an array or object with the same shape as `resolversOrValues` with any Promises resolved.
+ * If any provided values are promises, `all` returns a promise.
  *
  * ```javascript [playground]
- * all([
+ * const promise1 = all([
  *   Promise.resolve(1),
  *   Promise.resolve(2),
  *   3,
- * ]).then(console.log) // [1, 2, 3]
+ * ])
+ * promise1.then(console.log) // [1, 2, 3]
  *
- * all({
- *   a: Promise.resolve(1),
+ * const promise2 = all({
+ *   a: 1,
  *   b: Promise.resolve(2),
- *   c: 3,
- * }).then(console.log) // { a: 1, b: 2, c: 3 }
+ *   c: Promise.resolve(3),
+ * })
+ * promise2.then(console.log) // { a: 1, b: 2, c: 3 }
  * ```
  *
- * `all` can be used in a pipeline to compose and manpulate data.
+ * If any provided resolvers are asynchronous, `all` returns a promise. `all` can be used in a pipeline to compose and manpulate data.
  *
  * ```javascript [playground]
  * const identity = value => value
@@ -113,7 +112,7 @@ const _allValues = function (values) {
  * getAndLogUserById('1') // Got user {"_id":1,"name":"John"} by id 1
  * ```
  *
- * Values may be provided along with functions, in which case they are set on the result object or array directly. If any of these values are promises, they are resolved for their values before being set on the result object or array.
+ * Provided no resolvers, `all` returns the constructed array or object.
  *
  * ```javascript [playground]
  * all({}, {

package/and.js

@@ -97,38 +97,52 @@ const areAllPredicatesTruthy = function (args, predicates) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * and(values Array<boolean>) -> result boolean
+ * args Array<any>
+ * argsOrPromises Array<Promise|any>
  *
- * and(...args, predicatesOrValues Array<function|boolean>) -> Promise|boolean
+ * type SyncOrAsyncPredicate = (...args)=>Promise|boolean|any
  *
- * and(predicatesOrValues Array<function|boolean>)(...args) -> Promise|boolean
+ * predicatesOrValues Array<SyncOrAsyncPredicate|boolean|any>
+ *
+ * and(values Array<boolean|any>) -> result boolean
+ * and(...argsOrPromises, predicatesOrValues) -> Promise|boolean
+ * and(predicatesOrValues)(...args) -> Promise|boolean
  * ```
  *
  * @description
- * Tests an array of boolean values, returning true if all boolean values are truthy.
+ * Function equivalent to the [Logical AND](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND) operator. Tests an array of predicate functions, promises, values, or a mix thereof.
+ *
+ * If provided an array of boolean values, `and` returns true if all boolean values are true.
  *
  * ```javascript [playground]
  * const oneIsLessThanThree = 1 < 3
  * const twoIsGreaterThanOne = 2 > 1
  * const threeIsEqualToThree = 3 === 3
  *
- * console.log(
- *   and([oneIsLessThanThree, twoIsGreaterThanOne, threeIsEqualToThree]),
- * ) // true
+ * const condition = and([
+ *   oneIsLessThanThree,
+ *   twoIsGreaterThanOne,
+ *   threeIsEqualToThree
+ * ])
+ * console.log(condition) // true
  * ```
  *
- * If any values in the array are synchronous or asynchronous predicate functions, `and` takes another argument to test concurrently against the predicate functions, returning true if all array values and resolved values from the predicates are truthy.
+ * If any predicate functions are provided in the array, `and` returns an aggregate predicate function that returns true for a given set of arguments if all provided predicate functions test true. If any provided predicate functions are asynchronous, the aggregate predicate function becomes asynchronous.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
- *
  * const isPositive = number => number > 0
+ * const asyncIsLessThan3 = async number => number < 3
  *
- * const isLessThan3 = number => number < 3
+ * const aggregatePredicate = and([
+ *   true,
+ *   isOdd,
+ *   isPositive,
+ *   asyncIsLessThan3,
+ * ])
  *
- * console.log(
- *   and([isOdd, isPositive, isLessThan3])(1),
- * ) // true
+ * const condition = await aggregatePredicate(1)
+ * console.log(condition) // true
  * ```
  *
  * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.