rubico 2.8.4 → 2.8.6

package/get.js

@@ -1,6 +1,9 @@
 const isPromise = require('./_internal/isPromise')
+const promiseAll = require('./_internal/promiseAll')
 const __ = require('./_internal/placeholder')
+const curry2 = require('./_internal/curry2')
 const curry3 = require('./_internal/curry3')
+const funcApply = require('./_internal/funcApply')
 const isArray = require('./_internal/isArray')
 const isObject = require('./_internal/isObject')
 const getByPath = require('./_internal/getByPath')
@@ -18,47 +21,62 @@ const _get = function (object, path, defaultValue) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * get(
- *   object Promise|Object,
- *   path string|number|Array<string|number>,
- *   defaultValue? function|any
- * ) -> result Promise|Object
- *
- * get(
- *   path string|number|Array<string|number>,
- *   defaultValue? function|any
- * )(object Object) -> result Promise|Object
+ * path string|number|Array<string|number>
+ * defaultValue any
+ * defaultResolver function
+ *
+ * get(Promise|Object, path) -> Promise|any
+ * get(Promise|Object, path, defaultValue) -> Promise|any
+ * get(Promise|Object, path, defaultResolver) -> Promise|any
+ *
+ * get(path)(Object) -> Promise|any
+ * get(path, defaultValue)(Object) -> Promise|any
+ * get(path, defaultResolver)(Object) -> Promise|any
  * ```
  *
  * @description
- * Accesses a property of an object given a path denoted by a string, number, or an array of string or numbers.
+ * Property accessor. Accesses the property of an object given a path denoted by a string, number, or array of string or numbers.
  *
  * ```javascript [playground]
  * const obj = { hello: 'world' }
  *
- * console.log(get(obj, 'hello')) // world
+ * const value = get(obj, 'hello')
+ *
+ * console.log(value)
  * ```
  *
- * `get` supports a lazy API for composability
+ * `get` supports a lazy API for composability.
  *
  * ```javascript [playground]
  * const obj = { hello: 'world' }
  *
  * const getHello = get('hello')
  *
- * console.log(getHello({ hello: 'world' })) // world
+ * const value = getHello({ hello: 'world' })
+ *
+ * console.log(value)
  * ```
  *
- * If the value at the end of the path is not found on the object, returns an optional default value. The default value can be a function resolver that takes the object as an argument. If no default value is provided, returns `undefined`. The function resolver may be asynchronous (returns a promise).
+ * If the value denoted by the path is not found in the object, `get` returns a default value. The default value can be a function resolver that takes the object as an argument. If no default value is provided, `get` returns `undefined`.
  *
  * ```javascript [playground]
  * const getHelloWithDefaultValue = get('hello', 'default')
  *
- * console.log(getHelloWithDefaultValue({ foo: 'bar' })) // default
+ * console.log(getHelloWithDefaultValue({ foo: 'bar' }))
  *
  * const getHelloWithDefaultResolver = get('hello', object => object.foo)
  *
- * console.log(getHelloWithDefaultResolver({ foo: 'bar' })) // bar
+ * console.log(getHelloWithDefaultResolver({ foo: 'bar' }))
+ * ```
+ *
+ * The default resolver may be asynchronous, in which case `get` returns a promise.
+ *
+ * ```javascript [playground]
+ * const asyncDefaultResolver = async object => object.a
+ *
+ * const promise = get({ a: 1 }, 'notfound', asyncDefaultResolver)
+ *
+ * promise.then(console.log)
  * ```
  *
  * `get` supports three types of path patterns for nested property access.
@@ -70,18 +88,22 @@ const _get = function (object, path, defaultValue) {
  * ```javascript [playground]
  * const getABC0 = get('a.b.c[0]')
  *
- * console.log(getABC0({ a: { b: { c: ['hello'] } } })) // hello
+ * const abc0 = getABC0({ a: { b: { c: ['hello'] } } })
+ *
+ * console.log(abc0)
  *
  * const get00000DotNotation = get('0.0.0.0.0')
  * const get00000BracketNotation = get('[0][0][0][0][0]')
  * const get00000ArrayNotation = get([0, 0, 0, 0, 0])
  *
- * console.log(get00000DotNotation([[[[['foo']]]]])) // foo
- * console.log(get00000BracketNotation([[[[['foo']]]]])) // foo
- * console.log(get00000ArrayNotation([[[[['foo']]]]])) // foo
+ * const nested = [[[[['foo']]]]]
+ *
+ * console.log(get00000DotNotation(nested))
+ * console.log(get00000BracketNotation(nested))
+ * console.log(get00000ArrayNotation(nested))
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * get(Promise.resolve({ a: 1 }), 'a').then(console.log) // 1
@@ -101,8 +123,8 @@ const get = function (arg0, arg1, arg2) {
   if (typeof arg0 == 'string' || typeof arg0 == 'number' || isArray(arg0)) {
     return curry3(_get, __, arg0, arg1)
   }
-  if (isPromise(arg0)) {
-    return arg0.then(curry3(_get, __, arg1, arg2))
+  if (isPromise(arg0) || isPromise(arg2)) {
+    return promiseAll([arg0, arg1, arg2]).then(curry2(funcApply, _get, __))
   }
   return _get(arg0, arg1, arg2)
 }

package/gt.js

@@ -65,7 +65,7 @@ const greaterThan = require('./_internal/greaterThan')
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * gt(Promise.resolve({ a: 2, b: 1 }), get('a'), get('b')).then(console.log) // true

package/gte.js

@@ -69,7 +69,7 @@ const greaterThanOrEqual = require('./_internal/greaterThanOrEqual')
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * gte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true

package/index.js

@@ -1,5 +1,5 @@
 /**
- * Rubico v2.8.4
+ * Rubico v2.8.6
  * https://rubico.land/
  *
  * © Richard Yufei Tong, King of Software
@@ -1079,7 +1079,7 @@ const _curryArity = (arity, func, context, args) => function curried(...curriedA
     curriedArgsIndex = -1,
     numCurriedPlaceholders = 0
 
-  while (++argsIndex < argsLength) {
+  while ((argsIndex += 1) < argsLength) {
     const arg = args[argsIndex]
     if (arg == __ && (curriedArgsIndex += 1) < curriedArgsLength) {
       const curriedArg = curriedArgs[curriedArgsIndex]
@@ -1103,7 +1103,7 @@ const _curryArity = (arity, func, context, args) => function curried(...curriedA
     }
   }
 
-  while (++curriedArgsIndex < curriedArgsLength) {
+  while ((curriedArgsIndex += 1) < curriedArgsLength) {
     const curriedArg = curriedArgs[curriedArgsIndex]
     if (curriedArg == __) {
       numCurriedPlaceholders += 1
@@ -1133,7 +1133,7 @@ const curryArity = function (arity, func, context, args) {
     return _curryArity(arity, func, context, args)
   }
   let argsIndex = -1
-  while (++argsIndex < argsLength) {
+  while ((argsIndex += 1) < argsLength) {
     const arg = args[argsIndex]
     if (arg == __) {
       return _curryArity(arity, func, context, args)
@@ -3126,8 +3126,8 @@ const get = function (arg0, arg1, arg2) {
   if (typeof arg0 == 'string' || typeof arg0 == 'number' || isArray(arg0)) {
     return curry3(_get, __, arg0, arg1)
   }
-  if (isPromise(arg0)) {
-    return arg0.then(curry3(_get, __, arg1, arg2))
+  if (isPromise(arg0) || isPromise(arg2)) {
+    return promiseAll([arg0, arg1, arg2]).then(curry2(funcApply, _get, __))
   }
   return _get(arg0, arg1, arg2)
 }

package/lt.js

@@ -67,7 +67,7 @@ const lessThan = require('./_internal/lessThan')
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * lt(Promise.resolve({ a: 1, b: 2 }), get('a'), get('b')).then(console.log) // true

package/lte.js

@@ -67,7 +67,7 @@ const lessThanOrEqual = require('./_internal/lessThanOrEqual')
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * lte(Promise.resolve({ a: 1, b: 1 }), get('a'), get('b')).then(console.log) // true

package/map.js

@@ -250,7 +250,7 @@ const _map = function (value, f) {
  * })()
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const asyncSquare = async n => n ** 2
@@ -357,7 +357,7 @@ const _mapEntries = (value, f) => {
  * // 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.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const asyncSquareEntries = async ([k, v]) => [k, v ** 2]
@@ -467,7 +467,7 @@ 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.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const asyncSquare = async n => n ** 2
@@ -574,7 +574,7 @@ const _mapPool = function (f, concurrency, mapper) {
  * ]))(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.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const asyncSquare = async n => n ** 2

package/monad/Mux.js

@@ -1,7 +1,9 @@
-/* rubico v1.5.0
- * https://github.com/a-synchronous/rubico
- * (c) 2019-2020 Richard Tong
- * rubico may be freely distributed under the MIT license.
+/**
+ * Rubico
+ * https://rubico.land/
+ *
+ * © Richard Yufei Tong, King of Software
+ * Rubico may be freely distributed under the CFOSS license.
  */
 
 'use strict'

package/monad/PossiblePromise.js

@@ -1,7 +1,9 @@
-/* rubico v1.5.0
- * https://github.com/a-synchronous/rubico
- * (c) 2019-2020 Richard Tong
- * rubico may be freely distributed under the MIT license.
+/**
+ * Rubico
+ * https://rubico.land/
+ *
+ * © Richard Yufei Tong, King of Software
+ * Rubico may be freely distributed under the CFOSS license.
  */
 
 'use strict'

package/monad/README.md

@@ -1,4 +1,4 @@
-# rubico/monad
+# Monad
 
 This is a place for JavaScript monads.
 
@@ -6,70 +6,91 @@ Warning: this entire directory is experimental; APIs here are subject to change.
 
 # Specification
 
-Each rubico monad must return an object that implements `.chain`, while having some notion of `.map` and `.concat`. Similarly, while `.empty` is not strictly required, there should be some notion of an empty instance of a Monad. For example, `[]` is `empty` for Arrays. All of these methods as well as any others are free to implement; only `.chain` is required. Monads should throw TypeErrors from the constructor for invalid types of arguments. rubico Monads should generally act on objects or primitive values and not functions. A Monad that acts on a function may be better for rubico/x.
+Each monad must have a way to wrap one or more values, either using the constructor or using the `of` method.
 
+Each monad must implement the `chain`, `flatMap`, or `then` methods, or have a combination of the `map` and `concat` methods. Similarly, while `empty` is not strictly required, there should be some notion of an empty instance of a Monad. For example, `[]` is `empty` for Arrays. All of these methods as well as any others not listed may be implemented; only the `chain`, `flatMap`, or `then` methods and the constructor or `of` methods are required.
+
+Each monad should throw TypeErrors from the constructor for invalid types of arguments.
+
+## Monad constructor
 ```coffeescript [specscript]
-Monad = (args ...any)=>({
+new Monad(...arguments) -> Monad {
+  of: function,
   chain: function,
-  map: function?,
-  concat: function?,
-  empty: function?,
-})
+  flatMap: function,
+  then: function,
+  map: function,
+  concat: function,
+}
 ```
 
-## Monad.prototype.chain - required
+## Monad of method
 ```coffeescript [specscript]
-Monad(value any).chain(
-  flatMapper value=>(result Monad|any)) -> result
+Monad.of(...arguments) -> Monad {
+  of: function,
+  chain: function,
+  flatMap: function,
+  then: function,
+  map: function,
+  concat: function,
+}
 ```
 
-## Monad.prototype.map
+## Monad chain method
 ```coffeescript [specscript]
-Monad(value any).map(mapper value=>any) -> mappedMonad Monad
+monad Monad
+
+monad.chain(any=>(Monad|any)) -> Monad
 ```
 
-## Monad.prototype.concat
+## Monad flatMap method
 ```coffeescript [specscript]
-Monad(value any).concat(anotherMonad Monad) -> combinedMonad Monad
+monad Monad
+
+monad.flatMap(any=>(Monad|any)) -> Monad
 ```
 
-## Monad.prototype.empty
+## Monad then method
 ```coffeescript [specscript]
-Monad.empty() -> emptyMonad Monad
-```
+monad Monad
 
-# Examples
+monad.then(any=>(Monad|any)) -> Monad
+```
 
-A monad's effect is activated by calling its `.chain` method with `flatMap`.
+## Monad map method
+```coffeescript [specscript]
+monad Monad
 
-```javascript
-const { flatMap } = require('rubico')
+monad.map(any=>any) -> Monad
+```
 
-const Maybe = value => ({
-  chain(flatMapper) {
-    return value == null ? value : flatMapper(value)
-  },
-})
+## Monad concat method
+```coffeescript [specscript]
+monad Monad
 
-flatMap(console.log)(Maybe(null))
+monad.concat(Monad) -> Monad
+```
 
-flatMap(console.log)(Maybe('hello world')) // hello world
+## Monad empty method
+```coffeescript [specscript]
+Monad.empty() -> Monad
 ```
 
-Additionally, if a monad implements `.concat`, it can be transformed as a Semigroup with a transducer and `transform`.
+# Example
+A monad's effect is activated by calling its `chain` method with a function.
 
 ```javascript
-const { transform } = require('rubico')
-
-const Max = number => ({
-  number,
-  concat(value) {
-    return Max(Math.max(
-      number, value.constructor == Max ? value.number : value))
+const Maybe = value => ({
+  chain(func) {
+    if (value) {
+      func(value)
+    }
+    return this
   },
 })
 
-transform(
-  map(Math.abs), new Max(-Infinity),
-)([-1, -2, -3, -4, -5]) // Max { 5 }
+Maybe(null).chain(console.log)
+
+Maybe('hello world').chain(console.log) // hello world
 ```
+

package/monad/Struct.js

@@ -1,7 +1,9 @@
-/* rubico v1.5.0
- * https://github.com/a-synchronous/rubico
- * (c) 2019-2020 Richard Tong
- * rubico may be freely distributed under the MIT license.
+/**
+ * Rubico
+ * https://rubico.land/
+ *
+ * © Richard Yufei Tong, King of Software
+ * Rubico may be freely distributed under the CFOSS license.
  */
 
 'use strict'

package/not.js

@@ -59,7 +59,7 @@ const _not = function (args, predicate) {
  * not(promise).then(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.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1

package/omit.js

@@ -62,7 +62,7 @@ const _omit = function (source, paths) {
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * omit(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)

package/or.js

@@ -145,7 +145,7 @@ const areAnyPredicatesTruthy = function (args, predicates) {
  * console.log(condition) // 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.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * or(Promise.resolve('aaa'), [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "2.8.4",
+  "version": "2.8.6",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "CFOSS",

package/pick.js

@@ -62,7 +62,7 @@ const _pick = function (source, keys) {
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * pick(Promise.resolve({ a: 1, b: 2, c: 3 }), ['a', 'b']).then(console.log)

package/pipe.js

@@ -10,41 +10,35 @@ const __ = require('./_internal/placeholder')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * args Array<any>
- * argsOrPromises Array<Promise|any>
- *
- * type SyncOrAsyncFunction = (...args)=>Promise|any
+ * type SyncOrAsyncFunction = (...arguments)=>Promise|any
  * type UnarySyncOrAsyncFunction = any=>Promise|any
  *
  * funcs [SyncOrAsyncFunction, ...Array<UnarySyncOrAsyncFunction>]
  *
- * pipe(funcs)(...args) -> result Promise|any
- * pipe(...argsOrPromises, funcs) -> result Promise|any
- * pipe(...funcs)(...args) -> result Promise|any
+ * pipe(funcs)(...arguments) -> Promise|any
+ * pipe(...arguments, funcs) -> Promise|any
+ * pipe(...funcs)(...arguments) -> Promise|any
  * ```
  *
  * @description
- * Creates a function pipeline from multiple functions. Each function in the pipeline is evaluated in series, passing its return value as an argument to the next function. The result of a pipeline execution is the return value of the last function in the pipeline. All arguments provided to the pipeline are provided to the first function in the pipeline. If any function in the pipeline is asynchronous, the result of the pipeline execution is a Promise.
+ * Creates a function pipeline from multiple functions. Each function in the function pipeline is evaluated in series starting from the first function in the function pipeline, passing its return value as the first and only argument to the next function in the pipeline. The result of the execution of a function pipeline is the return value of the last function in the function pipeline. If any function in the function pipeline is asynchronous, the result of the execution of the function pipeline is a promise.
  *
- * ```javascript [playground]
- * const syncAdd123 = pipe([
- *   number => number + 1,
- *   number => number + 2,
- *   number => number + 3,
- * ])
+ * Multiple arguments may be provided to a function pipeline, in which case they are passed directly to the first function in the function pipeline.
  *
- * console.log(syncAdd123(5)) // 11
+ * ```javascript [playground]
+ * function add(a, b, c) {
+ *   return a + b + c
+ * }
  *
- * const asyncAdd123 = pipe([
- *   async number => number + 1,
- *   async number => number + 2,
- *   async number => number + 3,
+ * const pipeline = pipe([
+ *   add,
+ *   console.log,
  * ])
  *
- * asyncAdd123(5).then(console.log) // 11
+ * pipeline(1, 2, 3)
  * ```
  *
- * `pipe` supports a mathematical API.
+ * Functions may be passed to `pipe` as arguments instead of as items of an array.
  *
  * ```javascript [playground]
  * const appendB = x => x + 'b'
@@ -52,14 +46,14 @@ const __ = require('./_internal/placeholder')
  *
  * const appendBC = pipe(appendB, appendC)
  *
- * console.log(appendBC('a')) // 'abc'
+ * console.log(appendBC('a'))
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * pipe(Promise.resolve(1), 2, Promise.resolve(3), [
- *   console.log, // [1, 2, 3]
+ *   console.log,
  * ])
  * ```
  *

package/reduce.js

@@ -193,7 +193,7 @@ const _reduce = function (collection, reducer, initial) {
  * reduce(asyncGenerate(), asyncAdd).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.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b

package/set.js

@@ -90,7 +90,7 @@ const _set = function (obj, path, value) {
  * ])
  * ```
  *
- * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * set(Promise.resolve({}), 'a', 1).then(console.log) // { a: 1 }

package/some.js

@@ -103,7 +103,7 @@ const _some = 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.
+ * Any promises passed in argument position are resolved for their values before further execution.
  *
  * ```javascript [playground]
  * some(Promise.resolve([1, 2, 3, 4, 5]), n => n > 6).then(console.log) // false