rubico 2.6.2 → 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/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/all.js

@@ -113,12 +113,22 @@ const _allValues = function (values) {
  * getAndLogUserById('1') // Got user {"_id":1,"name":"George"} by id 1
  * ```
  *
- * Values passed in resolver position 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.
+ * 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({}, [
+ * 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.
@@ -161,26 +171,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)
-  */
 }
 
 /**

package/map.js

@@ -53,39 +53,39 @@ const symbolAsyncIterator = require('./_internal/symbolAsyncIterator')
  * ```
  */
 
-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)
 }
 
 /**
@@ -106,7 +106,7 @@ const _map = function (value, mapper) {
  * ```
  *
  * @description
- * Applies a synchronous or asynchronous mapper function concurrently to each item of a collection, returning the results in a new collection of the same type. If order is implied by the collection, it is maintained in the result. `map` accepts the following collections:
+ * Applies a synchronous or asynchronous mapper function `f` concurrently to each item of a collection, returning the results in a new collection of the same type. If order is implied by the collection, it is maintained in the result. `map` accepts the following collections:
  *
  *  * `Array`
  *  * `Object`
@@ -115,7 +115,7 @@ const _map = function (value, mapper) {
  *  * `Iterator`/`Generator`
  *  * `AsyncIterator`/`AsyncGenerator`
  *
- * With arrays (type `Array`), `map` applies the mapper function to each item of the array, returning the transformed results in a new array ordered the same as the original array.
+ * With arrays (type `Array`), `map` applies the mapper function `f` to each item of the array, returning the transformed results in a new array ordered the same as the original array.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -131,7 +131,7 @@ const _map = function (value, mapper) {
  * ) // [1, 4, 9, 16, 25]
  * ```
  *
- * With objects (type `Object`), `map` applies the mapper function to each value of the object, returning the transformed results as values in a new object ordered by the keys of the original object
+ * With objects (type `Object`), `map` applies the mapper function `f` to each value of the object, returning the transformed results as values in a new object ordered by the keys of the original object
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -147,7 +147,7 @@ const _map = function (value, mapper) {
  * ) // { a: 1, b: 4, c: 9, d: 16, e: 25 }
  * ```
  *
- * With sets (type `Set`), `map` applies the mapper function to each value of the set, returning the transformed results unordered in a new set.
+ * With sets (type `Set`), `map` applies the mapper function `f` to each value of the set, returning the transformed results unordered in a new set.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -163,7 +163,7 @@ const _map = function (value, mapper) {
  * ) // [1, 4, 9, 16, 25]
  * ```
  *
- * With maps (type `Map`), `map` applies the mapper function to each value of the map, returning the results at the same keys in a new map. The entries of the resulting map are in the same order as those of the original map
+ * With maps (type `Map`), `map` applies the mapper function `f` to each value of the map, returning the results at the same keys in a new map. The entries of the resulting map are in the same order as those of the original map
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -179,7 +179,7 @@ const _map = function (value, mapper) {
  * ) // Map { 'a' => 1, 'b' => 4, 'c' => 9, 'd' => 16, 'e' => 25 }
  * ```
  *
- * With iterators (type `Iterator`) or generators (type `Generator`), `map` applies the mapper function lazily to each value of the iterator/generator, creating a new iterator with transformed iterations.
+ * With iterators (type `Iterator`) or generators (type `Generator`), `map` applies the mapper function `f` lazily to each value of the iterator/generator, creating a new iterator with transformed iterations.
  *
  * ```javascript [playground]
  * const capitalize = string => string.toUpperCase()
@@ -199,7 +199,7 @@ const _map = function (value, mapper) {
  * console.log([...ABCGenerator2]) // ['A', 'B', 'C']
  * ```
  *
- * With asyncIterators (type `AsyncIterator`, or `AsyncGenerator`), `map` applies the mapper function lazily to each value of the asyncIterator, creating a new asyncIterator with transformed iterations
+ * With asyncIterators (type `AsyncIterator`, or `AsyncGenerator`), `map` applies the mapper function `f` lazily to each value of the asyncIterator, creating a new asyncIterator with transformed iterations
  *
  * ```javascript [playground]
  * const capitalize = string => string.toUpperCase()
@@ -258,16 +258,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')
 }
@@ -285,10 +285,10 @@ const _mapEntries = (value, mapper) => {
  *   collection EntriesMappable
  * )=>(resultItem Promise|any)
  *
- * map.entries(value Promise|EntriesMappable, mapper Mapper)
+ * map.entries(value Promise|EntriesMappable, f Mapper)
  *   -> Promise|EntriesMappable
  *
- * map.entries(mapper Mapper)(value EntriesMappable)
+ * map.entries(f Mapper)(value EntriesMappable)
  *   -> Promise|EntriesMappable
  * ```
  *
@@ -512,4 +512,24 @@ map.pool = function mapPool(arg0, arg1, arg2) {
     : _mapPool(arg0, arg1, arg2)
 }
 
+/**
+ * @name map.rate
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Mappable = Array|Object|Set|Map
+ *
+ * map.rate(
+ *   rate number,
+ *   f (value any)=>Promise|any,
+ * )(collection Mappable) -> result Promise|Array
+ *
+ * map.rate(
+ *   collection Mappable,
+ *   rate number,
+ *   f (value any)=>Promise|any,
+ * ) -> result Promise|Array
+ * ```
+ */
+
 module.exports = map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "2.6.2",
+  "version": "2.6.3",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "MIT",