rubico 2.6.1 → 2.6.3

package/README.md

@@ -2,7 +2,7 @@
 ![rubico](https://raw.githubusercontent.com/a-synchronous/assets/master/rubico-logo.png)
 > a shallow river in northeastern Italy, just south of Ravenna
 
-![Node.js CI](https://github.com/a-synchronous/rubico/workflows/Node.js%20CI/badge.svg?branch=master)
+![Node.js CI](https://github.com/a-synchronous/rubico/workflows/Node.js%20CI/badge.svg)
 [![codecov](https://codecov.io/gh/a-synchronous/rubico/branch/master/graph/badge.svg)](https://codecov.io/gh/a-synchronous/rubico)
 [![npm version](https://img.shields.io/npm/v/rubico.svg?style=flat)](https://www.npmjs.com/package/rubico)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -26,7 +26,7 @@ pipe(numbers, [
 ```
 
 # Installation
-[Core build](https://unpkg.com/rubico/index.js) ([~6.8 kB minified and gzipped](https://unpkg.com/rubico/dist/rubico.min.js))
+[Core build](https://unpkg.com/rubico/index.js) ([~9.8 kB minified and gzipped](https://unpkg.com/rubico/dist/rubico.min.js))
 
 with `npm`
 ```bash
@@ -86,15 +86,12 @@ When you import this library, you obtain the freedom that comes from having thos
 
 # Introduction
 
-rubico is a library for async-enabled functional programming in JavaScript. The library methods support a simple and composable functional style in asynchronous environments.
+rubico is a library for async-enabled functional programming in JavaScript. The library supports a simple and composable functional style in asynchronous environments.
 
 ```javascript
 const {
   // compose functions
-  pipe, compose,
-
-  // handle effects
-  tap, forEach,
+  pipe, compose, tap,
 
   // control flow
   switchCase,
@@ -102,9 +99,12 @@ const {
   // handle errors
   tryCatch,
 
-  // handle objects
+  // compose data
   all, assign, get, set, pick, omit,
 
+  // iterate
+  forEach,
+
   // transform data
   map, filter, reduce, transform, flatMap,
 
@@ -119,7 +119,7 @@ const {
 } = rubico
 ```
 
-With async-enabled, or [a]synchronous, functional programming, functions provided to the rubico methods may be asynchronous and return a Promise. Any promises in argument position are also resolved before continuing with the operation.
+With async-enabled, or [a]synchronous, functional programming, functions provided to the rubico operators may be asynchronous and return a Promise. Any promises in argument position are also resolved before continuing with the operation.
 
 ```javascript [playground]
 const helloPromise = Promise.resolve('hello')
@@ -133,7 +133,7 @@ pipe(helloPromise, [ // helloPromise is resolved for 'hello'
 ])
 ```
 
-Most methods support both an eager and a lazy API. The eager API takes all required arguments and executes at once, while its lazy API takes only the non-data arguments and executes lazily, returning a function that expects the data arguments. This dual API supports a natural and composable code style.
+All rubico operators support both an eager and a lazy API. The eager API takes all required arguments and executes at once, while its lazy API takes only the non-data arguments and executes lazily, returning a function that expects the data arguments. This dual API supports a natural and composable code style.
 
 ```javascript [playground]
 const myObj = { a: 1, b: 2, c: 3 }
@@ -150,7 +150,7 @@ console.log(myDuplicatedSquaredObject)
 // { a: [1, 1], b: [4, 4], c: [9, 9] }
 ```
 
-The rubico methods are versatile and act on a wide range of vanilla JavaScript types to create declarative, extensible, and async-enabled function compositions. The same operator `map` can act on an array and also a `Map` data structure.
+The rubico operators are versatile and act on a wide range of vanilla JavaScript types to create declarative, extensible, and async-enabled function compositions. The same operator `map` can act on an array and also a `Map` data structure.
 
 ```javascript [playground]
 const { pipe, tap, map, filter } = rubico
@@ -203,7 +203,7 @@ pipe(todoIDs, [
 ])
 ```
 
-rubico offers transducers in its `Transducer` module. You can consume these transducers with the `transform` and `compose` methods. You should use `compose` over `pipe` to chain a left-to-right composition of transducers.
+rubico offers transducers in its `Transducer` module. You can consume these transducers with the `transform` and `compose` operators. You should use `compose` over `pipe` to chain a left-to-right composition of transducers.
 
 ```javascript [playground]
 const isOdd = number => number % 2 == 1
@@ -227,12 +227,12 @@ pipe(generateNumbers(), [
 ])
 ```
 
-For advanced asynchronous use cases, some of the methods have property functions that have different asynchronous behavior, e.g.
+For advanced asynchronous use cases, some of the operators have property functions that have different asynchronous behavior, e.g.
  * `map` - apply a mapper function concurrently
  * `map.pool` - apply a mapper function concurrently with a concurrency limit
  * `map.series` - apply a mapper function serially
 
-For more functions beyond the core methods, please visit `rubico/x`. You can find the full documentation at [rubico.land/docs](https://rubico.land/docs).
+For more functions beyond the core operators, please visit `rubico/x`. You can find the full documentation at [rubico.land/docs](https://rubico.land/docs).
 
 # Benchmarks
 Please find the published benchmark output inside the [benchmark-output](https://github.com/a-synchronous/rubico/tree/master/benchmark-output) folder. You can run the benchmarks on your own system with the following command:

package/_internal/areAllValuesNonfunctions.js

@@ -1,16 +1,28 @@
+const isArray = require('./isArray')
+
 /**
  * @name areAllValuesNonfunctions
  *
  * @synopsis
  * ```coffeescript [specscript]
  * areAllValuesNonfunctions(values Array<function|value>) -> boolean
+ * areAllValuesNonfunctions(values Object<function|value>) -> boolean
  * ```
  */
 const areAllValuesNonfunctions = function (values) {
-  const length = values.length
-  let index = -1
-  while (++index < length) {
-    if (typeof values[index] == 'function') {
+  if (isArray(values)) {
+    const length = values.length
+    let index = -1
+    while (++index < length) {
+      if (typeof values[index] == 'function') {
+        return false
+      }
+    }
+    return true
+  }
+
+  for (const key in values) {
+    if (typeof values[key] == 'function') {
       return false
     }
   }

package/_internal/areAnyValuesPromises.js

@@ -1,3 +1,4 @@
+const isArray = require('./isArray')
 const isPromise = require('./isPromise')
 
 /**
@@ -6,13 +7,24 @@ const isPromise = require('./isPromise')
  * @synopsis
  * ```coffeescript [specscript]
  * areAnyValuesPromises(values Array) -> boolean
+ * areAnyValuesPromises(values Object) -> boolean
  * ```
  */
 const areAnyValuesPromises = function (values) {
-  const length = values.length
-  let index = -1
-  while (++index < length) {
-    const value = values[index]
+  if (isArray(values)) {
+    const length = values.length
+    let index = -1
+    while (++index < length) {
+      const value = values[index]
+      if (isPromise(value)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  for (const key in values) {
+    const value = values[key]
     if (isPromise(value)) {
       return true
     }

package/_internal/arrayMapPool.js

@@ -48,7 +48,7 @@ const arrayMapPoolAsync = async function (
  *
  * @synopsis
  * ```coffeescript [specscript]
- * arrayMapPool(array Array, concurrency number, f function) -> Promise|string
+ * arrayMapPool(array Array, concurrency number, f function) -> Promise|array
  * ```
  *
  * @description

package/_internal/arrayMapRate.js

@@ -0,0 +1,85 @@
+const curry3 = require('./curry3')
+const __ = require('./placeholder')
+const isPromise = require('./isPromise')
+const promiseAll = require('./promiseAll')
+const sleep = require('./sleep')
+
+/**
+ * @name arrayMapRate
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * arrayMapRate(
+ *   array Array,
+ *   rate number,
+ *   f function,
+ * ) -> Promise<Array>
+ * ```
+ */
+const arrayMapRate = async function (array, rate, f) {
+  const length = array.length
+  const result = Array(length)
+  const minPeriodMs = 1 / rate * 1000
+  let index = -1
+  let lastExecutionTime = 0
+  const totalStart = performance.now()
+  while (++index < length) {
+    if (index > 0 && lastExecutionTime < minPeriodMs) {
+      await sleep(minPeriodMs - lastExecutionTime)
+    }
+    const start = performance.now()
+    let resultItem = f(array[index], index, array)
+    if (isPromise(resultItem)) {
+      resultItem = await resultItem
+    }
+    const end = performance.now()
+    const executionTime = end - start
+    lastExecutionTime = executionTime
+    result[index] = resultItem
+  }
+  const totalEnd = performance.now()
+  return result
+}
+
+/**
+ * @name range
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * range(lower number, upper number) -> numbers Array<number>
+ * ```
+ */
+const range = function (lower, upper) {
+  const result = []
+  let start = lower
+  while (start <= upper) {
+    result.push(start)
+    start += 1
+  }
+  return result
+}
+
+/*
+const start = performance.now()
+arrayMapRate(
+  range(0, 10),
+  2,
+  async n => {
+    const duration = Math.random() * 1000
+    console.log('duration', duration)
+    // const duration = 500
+    await sleep(duration)
+    return n ** 2
+  }
+  async n => {
+    console.log('n', n)
+    return n ** 2
+  },
+).then(result => {
+  const end = performance.now()
+  console.log('average period:', (end - start) / result.length)
+  console.log(result)
+})
+*/
+
+module.exports = arrayMapRate

package/_internal/functionArrayAll.js

@@ -14,7 +14,8 @@ const functionArrayAll = function (funcs, args) {
     result = Array(funcsLength)
   let funcsIndex = -1, isAsync = false
   while (++funcsIndex < funcsLength) {
-    const resultItem = funcs[funcsIndex](...args)
+    const f = funcs[funcsIndex]
+    const resultItem = typeof f == 'function' ? f(...args) : f
     if (isPromise(resultItem)) {
       isAsync = true
     }

package/_internal/functionObjectAll.js

@@ -19,7 +19,8 @@ const objectSet = require('./objectSet')
 const functionObjectAll = function (funcs, args) {
   const result = {}, promises = []
   for (const key in funcs) {
-    const resultItem = funcs[key](...args)
+    const f = funcs[key]
+    const resultItem = typeof f == 'function' ? f(...args) : f
     if (isPromise(resultItem)) {
       promises.push(resultItem.then(curry3(objectSet, result, key, __)))
     } else {

package/all.js

@@ -1,5 +1,8 @@
+const isPromise = require('./_internal/isPromise')
 const areAnyValuesPromises = require('./_internal/areAnyValuesPromises')
+const areAllValuesNonfunctions = require('./_internal/areAllValuesNonfunctions')
 const promiseAll = require('./_internal/promiseAll')
+const promiseObjectAll = require('./_internal/promiseObjectAll')
 const isArray = require('./_internal/isArray')
 const __ = require('./_internal/placeholder')
 const curry2 = require('./_internal/curry2')
@@ -9,21 +12,54 @@ const functionArrayAllSeries = require('./_internal/functionArrayAllSeries')
 const functionObjectAll = require('./_internal/functionObjectAll')
 
 /**
- * @name all
+ * @name _allValues
  *
  * @synopsis
  * ```coffeescript [specscript]
- * all(...args, funcsArray Array<function>) -> result Promise|Array
- *
- * all(funcsArray Array<function>)(...args) -> result Promise|Array
- *
- * all(...args, funcsObject Object<function>) -> result Promise|Object
+ * _allValues(values Array<Promise|any>) -> Promise<Array>
+ * _allValues(values Object<Promise|any>) -> Promise<Object>
+ * ```
+ */
+const _allValues = function (values) {
+  if (isArray(values)) {
+    return areAnyValuesPromises(values)
+      ? promiseAll(values)
+      : values
+  }
+  return areAnyValuesPromises(values)
+    ? promiseObjectAll(values)
+    : values
+}
+
+/**
+ * @name all
  *
- * all(funcsObject Object<function>)(...args) -> result Promise|Object
+ * @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
  * ```
  *
  * @description
- * 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.
+ * Calls an array or object of resolver functions or values `resolversOrValues` with provided arguments.
  *
  * ```javascript [playground]
  * const createArrayOfGreetingsFor = all([
@@ -32,24 +68,29 @@ const functionObjectAll = require('./_internal/functionObjectAll')
  *   name => `Hello ${name}`,
  * ])
  *
- * const arrayOfGreetingsForFred = createArrayOfGreetingsFor('Fred')
+ * const arrayOfGreetingsFor1 = createArrayOfGreetingsFor('1')
  *
- * console.log(arrayOfGreetingsForFred)
- * // ['Hi Fred', 'Hey Fred', 'Hello Fred']
- *
- * const createObjectOfGreetingsFor = all({
- *   hi: name => `Hi ${name}`,
- *   hey: name => `Hey ${name}`,
- *   hello: name => `Hello ${name}`,
- * })
+ * console.log(arrayOfGreetingsFor1)
+ * // ['Hi 1', 'Hey 1', 'Hello 1']
+ * ```
  *
- * const objectOfGreetingsForJane = createObjectOfGreetingsFor('Jane')
+ * If provided only values for `resolversOrValues`, returns an array or object with the same shape as `resolversOrValues` with any Promises resolved.
  *
- * console.log(objectOfGreetingsForJane)
- * // { hi: 'Hi Jane', hey: 'Hey Jane', hello: 'Hello Jane' }
+ * ```javascript [playground]
+ * all([
+ *   Promise.resolve(1),
+ *   Promise.resolve(2),
+ *   3,
+ * ]).then(console.log) // [1, 2, 3]
+ *
+ * all({
+ *   a: Promise.resolve(1),
+ *   b: Promise.resolve(2),
+ *   c: 3,
+ * }).then(console.log) // { a: 1, b: 2, c: 3 }
  * ```
  *
- * `all` can simultaneously compose objects and handle promises.
+ * `all` can be used in a pipeline to compose and manpulate data.
  *
  * ```javascript [playground]
  * const identity = value => value
@@ -72,6 +113,24 @@ const functionObjectAll = require('./_internal/functionObjectAll')
  * getAndLogUserById('1') // Got user {"_id":1,"name":"George"} 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.
+ *
+ * ```javascript [playground]
+ * all({}, {
+ *   a: Promise.resolve(1),
+ *   b: 2,
+ *   c: () => 3,
+ *   d: async () => 4,
+ * }).then(console.log) // { a: 1, b: 2, c: 3, d: 4 }
+ *
+ * all([], [
+ *   Promise.resolve(1),
+ *   2,
+ *   () => 3,
+ *   async () => 4,
+ * ]).then(console.log) // [1, 2, 3, 4]
+ * ```
+ *
  * 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]
@@ -84,24 +143,34 @@ const functionObjectAll = require('./_internal/functionObjectAll')
  *
  * @execution concurrent
  */
-
 const all = function (...args) {
-  const funcs = args.pop()
-  if (args.length == 0) {
-    return isArray(funcs)
-      ? curryArgs2(functionArrayAll, funcs, __)
-      : curryArgs2(functionObjectAll, funcs, __)
+  if (args.length == 1) {
+    const resolversOrValues = args[0]
+    if (isPromise(resolversOrValues)) {
+      return resolversOrValues.then(_allValues)
+    }
+    if (areAllValuesNonfunctions(resolversOrValues)) {
+      return _allValues(resolversOrValues)
+    }
+    return isArray(resolversOrValues)
+      ? curryArgs2(functionArrayAll, resolversOrValues, __)
+      : curryArgs2(functionObjectAll, resolversOrValues, __)
   }
 
-  if (areAnyValuesPromises(args)) {
-    return isArray(funcs)
-      ? promiseAll(args).then(curry2(functionArrayAll, funcs, __))
-      : promiseAll(args).then(curry2(functionObjectAll, funcs, __))
+  const resolversOrValues = args[args.length - 1]
+  const argValues = args.slice(0, -1)
+
+  if (areAnyValuesPromises(argValues)) {
+    return isArray(resolversOrValues)
+      ? promiseAll(argValues)
+        .then(curry2(functionArrayAll, resolversOrValues, __))
+      : promiseAll(argValues)
+        .then(curry2(functionObjectAll, resolversOrValues, __))
   }
 
-  return isArray(funcs)
-    ? functionArrayAll(funcs, args)
-    : functionObjectAll(funcs, args)
+  return isArray(resolversOrValues)
+    ? functionArrayAll(resolversOrValues, argValues)
+    : functionObjectAll(resolversOrValues, argValues)
 }
 
 /**

package/assign.js

@@ -18,13 +18,18 @@ const _assign = function (object, funcs) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * assign(object Promise|Object, resolvers Object<function>) -> result Promise|Object
+ * assign(
+ *   o Promise|Object,
+ *   resolversOrValues Object<function|Promise|any>
+ * ) -> result Promise|Object
  *
- * assign(resolvers Object<function>)(object Object) -> result Promise|Object
+ * assign(
+ *   resolversOrValues Object<function|Promise|any>
+ * )(o Object) -> result Promise|Object
  * ```
  *
  * @description
- * Function executor and composer. Accepts an object of resolver functions and an argument object. Creates a result object from the argument object, evaluates each resolver with the argument object, and assigns to the result object the evaluations at the corresponding resolver keys.
+ * Function executor and composer. Accepts an object of resolver functions or values and an object `o`. Creates a result object from the argument object, evaluates each resolver with the argument object, and assigns to the result object the evaluations at the corresponding resolver keys.
  *
  * ```javascript [playground]
  * const assignSquaredAndCubed = assign({
@@ -55,6 +60,17 @@ const _assign = function (object, funcs) {
  * // { numbers: [1, 2, 3, 4, 5], total: 15 }
  * ```
  *
+ * Values passed in resolver position are set on the result object directly. If any of these values are promises, they are resolved for their values before being set on the result object.
+ *
+ * ```javascript [playground]
+ * assign({}, {
+ *   a: 1,
+ *   b: Promise.resolve(2),
+ *   c: () => 3,
+ *   d: async o => Object.keys(o).length,
+ * }).then(console.log) // { a: 1, b: 2, c: 3, d: 0 }
+ * ```
+ *
  * 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/dist/Transducer.es.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/Transducer.es.min.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/Transducer.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/Transducer.min.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/Transducer.mjs

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/__.es.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/__.es.min.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/__.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/__.min.js

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.

package/dist/__.mjs

@@ -1,5 +1,5 @@
 /**
- * rubico v2.6.1
+ * rubico v2.6.2
  * https://github.com/a-synchronous/rubico
  * (c) 2019-2024 Richard Tong
  * rubico may be freely distributed under the MIT license.