core operators promise arguments docs

Author: richytong

all.js

@@ -23,7 +23,7 @@ const functionObjectAll = require('./_internal/functionObjectAll')
  * ```
  *
  * @description
- * Function executor and composer. Accepts either an array of functions or an object of functions as the values. Calls each function of the provided array or object in parallel with the provided arguments. Returns either an array or object of the results of the function executions.
+ * Function executor and composer. Accepts either an array of functions or an object of functions. Calls each function of the provided array or object in parallel with the provided arguments. Returns either an array or object of the execution results.
  *
  * ```javascript [playground]
  * const createArrayOfGreetingsFor = all([
@@ -72,6 +72,16 @@ const functionObjectAll = require('./_internal/functionObjectAll')
  * getAndLogUserById('1') // Got user {"_id":1,"name":"George"} by id 1
  * ```
  *
+ * 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]
+ * all(Promise.resolve({ a: 1 }), [
+ *   obj => obj.a + 1,
+ *   obj => obj.a + 2,
+ *   obj => obj.a + 3,
+ * ]).then(console.log) // [2, 3, 4]
+ * ```
+ *
  * @execution concurrent
  */
 

and.js

@@ -131,6 +131,15 @@ const areAllPredicatesTruthy = function (args, predicates) {
  * ) // 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.
+ *
+ * ```javascript [playground]
+ * and(Promise.resolve(5), [
+ *   n => n > 0,
+ *   n => n < 10,
+ * ]).then(console.log) // true
+ * ```
+ *
  * @execution series
  *
  * @note ...args slows down here by an order of magnitude

assign.js

@@ -18,7 +18,7 @@ const _assign = function (object, funcs) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * assign(object Object, resolvers Object<function>) -> result Promise|Object
+ * assign(object Promise|Object, resolvers Object<function>) -> result Promise|Object
  *
  * assign(resolvers Object<function>)(object Object) -> result Promise|Object
  * ```
@@ -55,6 +55,19 @@ const _assign = function (object, funcs) {
  * // { numbers: [1, 2, 3, 4, 5], total: 15 }
  * ```
  *
+ * 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]
+ * assign(Promise.resolve({}), {
+ *   a() {
+ *     return 1
+ *   },
+ *   b() {
+ *     return 2
+ *   },
+ * }).then(console.log)
+ * ```
+ *
  * @execution concurrent
  */
 const assign = function (arg0, arg1) {

compose.js

@@ -27,6 +27,14 @@ const funcConcat = require('./_internal/funcConcat')
  *   compose(5, [f, g]),
  * ) // 16
  * ```
+ *
+ * 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]
+ * compose(Promise.resolve(1), 2, Promise.resolve(3), [
+ *   console.log, // [1, 2, 3]
+ * ])
+ * ```
  */
 const compose = function (...args) {
   const funcs = args.pop()

eq.js

@@ -48,6 +48,12 @@ const equals = require('./_internal/equals')
  * ])
  * ```
  *
+ * 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]
+ * eq(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
+ * ```
+ *
  * @execution concurrent
  */
 

every.js

@@ -82,6 +82,12 @@ const _every = function (collection, predicate) {
  * ])
  * ```
  *
+ * 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]
+ * every(Promise.resolve([1, 2, 3, 4, 5]), n => n < 6).then(console.log) // true
+ * ```
+ *
  * @execution concurrent
  *
  * @muxing

filter.js

@@ -226,6 +226,15 @@ const _filter = function (value, predicate) {
  * }
  * ```
  *
+ * 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]
+ * const isOdd = number => number % 2 == 1
+ *
+ * filter(Promise.resolve([1, 2, 3, 4, 5]), isOdd).then(console.log)
+ * // [1, 3, 5]
+ * ```
+ *
  * @execution concurrent
  *
  * @transducing

flatMap.js

@@ -157,6 +157,13 @@ const _flatMap = function (value, flatMapper) {
  * ) // 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]
+ * flatMap(Promise.resolve([1, 2, 3, 4, 5]), n => [n, n]).then(console.log)
+ * // [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]
+ * ```
+ *
  * @execution concurrent
  *
  * @transducing

forEach.js

@@ -72,6 +72,15 @@ const _forEach = function (collection, callback) {
  *                         // 25
  * ])
  * ```
+ *
+ * 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]
+ * forEach(Promise.resolve([1, 2, 3]), console.log)
+ * // 1
+ * // 2
+ * // 3
+ * ```
  */
 const forEach = function (arg0, arg1) {
   if (typeof arg0 == 'function') {
@@ -131,6 +140,15 @@ const _forEachSeries = function (collection, callback) {
  *
  * forEach.series({ a: 1, b: 2, c: 3 }, console.log) // 1 2 3
  * ```
+ *
+ * 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]
+ * forEach.series(Promise.resolve([1, 2, 3]), console.log)
+ * // 1
+ * // 2
+ * // 3
+ * ```
  */
 forEach.series = function forEachSeries(arg0, arg1) {
   if (typeof arg0 == 'function') {

get.js

@@ -80,6 +80,12 @@ const _get = function (object, path, defaultValue) {
  * console.log(get00000BracketNotation([[[[['foo']]]]])) // foo
  * console.log(get00000ArrayNotation([[[[['foo']]]]])) // foo
  * ```
+ *
+ * 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]
+ * get(Promise.resolve({ a: 1 }), 'a').then(console.log) // 1
+ * ```
  */
 
 const get = function (arg0, arg1, arg2) {

gt.js

@@ -47,6 +47,12 @@ const greaterThan = require('./_internal/greaterThan')
  *   console.log, // 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.
+ *
+ * ```javascript [playground]
+ * gt(Promise.resolve({ a: 2, b: 1 }), get('a'), get('b')).then(console.log) // true
+ * ```
  */
 const gt = ComparisonOperator(greaterThan)
 

gte.js

@@ -49,6 +49,12 @@ const greaterThanOrEqual = require('./_internal/greaterThanOrEqual')
  *   console.log, // 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.
+ *
+ * ```javascript [playground]
+ * gte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
+ * ```
  */
 const gte = ComparisonOperator(greaterThanOrEqual)
 

lt.js

@@ -47,6 +47,12 @@ const lessThan = require('./_internal/lessThan')
  *   console.log, // 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.
+ *
+ * ```javascript [playground]
+ * lt(Promise.resolve({ a: 1, b: 2 }), get('a'), get('b')).then(console.log) // true
+ * ```
  */
 const lt = ComparisonOperator(lessThan)
 

lte.js

@@ -47,6 +47,12 @@ const lessThanOrEqual = require('./_internal/lessThanOrEqual')
  *   console.log, // 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.
+ *
+ * ```javascript [playground]
+ * lte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true
+ * ```
  */
 const lte = ComparisonOperator(lessThanOrEqual)
 

map.js

@@ -236,6 +236,15 @@ const _map = function (value, mapper) {
  * })()
  * ```
  *
+ * 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]
+ * const asyncSquare = async n => n ** 2
+ *
+ * map(Promise.resolve([1, 2, 3, 4, 5]), asyncSquare).then(console.log)
+ * // [1, 4, 9, 16, 25]
+ * ```
+ *
  * @execution concurrent
  *
  * @TODO streamMap
@@ -297,6 +306,18 @@ const _mapEntries = (value, mapper) => {
  * // Map(3) { 'A' => 1, 'B' => 4, 'C' => 9 }
  * ```
  *
+ * 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]
+ * const asyncSquareEntries = async ([k, v]) => [k, v ** 2]
+ *
+ * map.entries(
+ *   Promise.resolve({ a: 1, b: 2, c: 3 }),
+ *   asyncSquareEntries,
+ * ).then(console.log)
+ * // { a: 1, b: 4, c: 9 }
+ * ```
+ *
  * @since v1.7.0
  */
 map.entries = function mapEntries(arg0, arg1) {
@@ -379,6 +400,15 @@ const _mapSeries = function (collection, f) {
  * map.series([1, 2, 3, 4, 5], delayedLog)
  * ```
  *
+ * 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]
+ * const asyncSquare = async n => n ** 2
+ *
+ * map.series(Promise.resolve([1, 2, 3, 4, 5]), asyncSquare).then(console.log)
+ * // [1, 4, 9, 16, 25]
+ * ```
+ *
  * @execution series
  */
 map.series = function mapSeries(arg0, arg1) {
@@ -460,6 +490,15 @@ const _mapPool = function (collection, concurrency, f) {
  * ]))(ids)
  * ```
  *
+ * 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]
+ * const asyncSquare = async n => n ** 2
+ *
+ * map.pool(Promise.resolve([1, 2, 3, 4, 5]), 5, asyncSquare).then(console.log)
+ * // [1, 4, 9, 16, 25]
+ * ```
+ *
  * @TODO objectMapPool
  *
  * @execution concurrent

not.js

@@ -45,6 +45,14 @@ const _not = function (args, predicate) {
  *   not(isOdd)(3),
  * ) // false
  * ```
+ *
+ * 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]
+ * const isOdd = number => number % 2 == 1
+ *
+ * not(Promise.resolve(3), isOdd).then(console.log) // false
+ * ```
  */
 
 const not = function (...args) {

omit.js

@@ -62,6 +62,13 @@ const _omit = function (source, paths) {
  *   console.log, // { c: 9 }
  * ])
  * ```
+ *
+ * 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]
+ * omit(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
+ * // { c: 3 }
+ * ```
  */
 const omit = function (arg0, arg1) {
   if (arg1 == null) {

or.js

@@ -129,6 +129,15 @@ const areAnyPredicatesTruthy = function (args, predicates) {
  * ) // 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.
+ *
+ * ```javascript [playground]
+ * or(Promise.resolve('aaa'), [
+ *   s => s.startsWith('b'),
+ *   s => s.endsWith('a'),
+ * ]).then(console.log) // true
+ * ```
+ *
  * @execution series
  *
  * @note ...args slows down here by an order of magnitude

pick.js

@@ -62,6 +62,13 @@ const _pick = function (source, keys) {
  *   console.log, // { a: 1, c: 9 }
  * ])
  * ```
+ *
+ * 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]
+ * pick(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)
+ * // { a: 1, b: 2 }
+ * ```
  */
 const pick = function (arg0, arg1) {
   if (arg1 == null) {

pipe.js

@@ -46,6 +46,14 @@ const __ = require('./_internal/placeholder')
  * ])
  * ```
  *
+ * 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]
+ * pipe(Promise.resolve(1), 2, Promise.resolve(3), [
+ *   console.log, // [1, 2, 3]
+ * ])
+ * ```
+ *
  * @execution series
  *
  * @transducing

reduce.js

@@ -172,6 +172,14 @@ const _reduce = function (collection, reducer, initialValue) {
  * reduce(asyncAdd)(asyncGenerate12345()).then(console.log) // 15
  * ```
  *
+ * 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]
+ * const add = (a, b) => a + b
+ *
+ * reduce(Promise.resolve([1, 2, 3, 4, 5]), add, 0).then(console.log) // 15
+ * ```
+ *
  * @execution series
  *
  * @transducing