rubico 1.9.6 → 2.0.0

package/memory-usage/reduce.js

@@ -15,7 +15,7 @@ const asyncGenerator = async function*(i) {
   yield 3
 }
 
-void (async () => {
+setImmediate(async () => {
   let i = 0, maxHeapUsed = 0
   while (i < iterations) {
     const p = reduce((a, b) => a + b, 0)(asyncGenerator(i))
@@ -35,6 +35,6 @@ void (async () => {
   }
 
   console.log('maxHeapUsed (MiB)', maxHeapUsed / 1024 / 1024)
-})()
+})
 
 // https://stackoverflow.com/questions/62336381/is-this-promise-cancellation-implementation-for-reducing-an-async-iterable-on-th

package/not.js

@@ -1,21 +1,33 @@
+const areAnyValuesPromises = require('./_internal/areAnyValuesPromises')
 const isPromise = require('./_internal/isPromise')
+const promiseAll = require('./_internal/promiseAll')
+const __ = require('./_internal/placeholder')
+const curry2 = require('./_internal/curry2')
+const curryArgs2 = require('./_internal/curryArgs2')
 
-// true -> false
-const _not = value => !value
+// negate(value boolean) -> inverse boolean
+const negate = value => !value
+
+// _not(args Array, predicate function)
+const _not = function (args, predicate) {
+  const boolean = predicate(...args)
+  return isPromise(boolean) ? boolean.then(negate) : !boolean
+}
 
 /**
  * @name not
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var args ...any,
- *   predicate ...args=>Promise|boolean
+ * not(value boolean) -> negated boolean
  *
- * not(predicate)(...args) -> boolean
+ * not(...args, predicate function) -> negated boolean
+ *
+ * not(predicate function)(...args) -> negated boolean
  * ```
  *
  * @description
- * Negate a value (`!`)
+ * Negate a value like the [logical NOT (`!`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_NOT) operator.
  *
  * ```javascript [playground]
  * const myObj = { a: 1 }
@@ -24,7 +36,7 @@ const _not = value => !value
  * console.log(not('b' in myObj)) // true
  * ```
  *
- * If passed a function predicate, `not` returns a logically inverted predicate that returns true everywhere the original predicate would have returned false and vice versa.
+ * If provided a predicate function, `not` returns a logically inverted predicate that returns true everywhere the original predicate would have returned false.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -34,50 +46,19 @@ const _not = value => !value
  * ) // false
  * ```
  */
-const not = function (funcOrValue) {
-  if (typeof funcOrValue == 'function') {
-    return function logicalInverter(value) {
-      const boolean = funcOrValue(value)
-      return isPromise(boolean) ? boolean.then(_not) : !boolean
+
+const not = function (...args) {
+  const predicateOrValue = args.pop()
+  if (typeof predicateOrValue == 'function') {
+    if (args.length == 0) {
+      return curryArgs2(_not, __, predicateOrValue)
     }
+    if (areAnyValuesPromises(args)) {
+      return promiseAll(args).then(curry2(_not, __, predicateOrValue))
+    }
+    return _not(args, predicateOrValue)
   }
-  return !funcOrValue
+  return !predicateOrValue
 }
 
-/**
- * @name notSync
- *
- * @synopsis
- * ```coffeescript [specscript]
- * notSync(func ...any=>boolean) -> negated ...any=>boolean
- * ```
- */
-const notSync = func => function notSync(...args) {
-  return !func(...args)
-}
-
-/**
- * @name not.sync
- *
- * @synopsis
- * ```coffeescript [specscript]
- * var args ...any,
- *   syncPredicate ...args=>boolean
- *
- * not.sync(syncPredicate)(...args) -> boolean
- * ```
- *
- * @description
- * `not` without promise handling.
- *
- * ```javascript [playground]
- * const isOdd = number => number % 2 == 1
- *
- * console.log(
- *   not.sync(isOdd)(2),
- * ) // true
- * ```
- */
-not.sync = notSync
-
 module.exports = not

package/omit.js

@@ -1,27 +1,40 @@
+const isPromise = require('./_internal/isPromise')
 const deleteByPath = require('./_internal/deleteByPath')
 const copyDeep = require('./_internal/copyDeep')
+const curry2 = require('./_internal/curry2')
+const __ = require('./_internal/placeholder')
+
+// _omit(source Object, paths Array<string>) -> result Object
+const _omit = function (source, paths) {
+  const pathsLength = paths.length,
+    result = copyDeep(source)
+  let pathsIndex = -1
+  while (++pathsIndex < pathsLength) {
+    deleteByPath(result, paths[pathsIndex])
+  }
+  return result
+}
 
 /**
  * @name omit
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var paths Array<string>,
- *   source Object
+ * omit(paths Array<string>)(source Object) -> omitted Object
  *
- * omit(paths)(source) -> omitted Object
+ * omit(source Object, paths Array<string>) -> omitted Object
  * ```
  *
  * @description
- * Create a new object by excluding specific paths on a source object.
+ * Create a new object by excluding provided paths on a source object.
  *
  * ```javascript [playground]
  * console.log(
- *   omit(['_id'])({ _id: '1', name: 'George' }),
+ *   omit({ _id: '1', name: 'George' }, ['_id']),
  * ) // { name: 'George' }
  * ```
  *
- * Path patterns are the same as those supported by `get`:
+ * `omit` supports three types of path patterns for nested property access
  *
  *  * dot delimited - `'a.b.c'`
  *  * bracket notation - `'a[0].value'`
@@ -39,15 +52,25 @@ const copyDeep = require('./_internal/copyDeep')
  *   }),
  * ) // { a: { b: { c: 'hello' } } }
  * ```
+ *
+ * Compose `omit` inside a `pipe` with its tacit API
+ *
+ * ```javascript [playground]
+ * pipe({ a: 1, b: 2, c: 3 }, [
+ *   map(number => number ** 2),
+ *   omit(['a', 'b']),
+ *   console.log, // { c: 9 }
+ * ])
+ * ```
  */
-const omit = paths => function omitting(source) {
-  const pathsLength = paths.length,
-    result = copyDeep(source)
-  let pathsIndex = -1
-  while (++pathsIndex < pathsLength) {
-    deleteByPath(result, paths[pathsIndex])
+const omit = function (arg0, arg1) {
+  if (arg1 == null) {
+    return curry2(_omit, __, arg0)
   }
-  return result
+  if (isPromise(arg0)) {
+    return arg0.then(curry2(_omit, __, arg1))
+  }
+  return _omit(arg0, arg1)
 }
 
 module.exports = omit

package/or.js

@@ -1,6 +1,10 @@
+const promiseAll = require('./_internal/promiseAll')
 const isPromise = require('./_internal/isPromise')
-const curry3 = require('./_internal/curry3')
+const areAnyValuesPromises = require('./_internal/areAnyValuesPromises')
 const __ = require('./_internal/placeholder')
+const curry2 = require('./_internal/curry2')
+const curry3 = require('./_internal/curry3')
+const curryArgs2 = require('./_internal/curryArgs2')
 const thunkConditional = require('./_internal/thunkConditional')
 const areAllValuesNonfunctions = require('./_internal/areAllValuesNonfunctions')
 const thunkify2 = require('./_internal/thunkify2')
@@ -18,7 +22,7 @@ const always = require('./_internal/always')
 const areAnyNonfunctionsTruthy = function (predicates, index) {
   const length = predicates.length
   while (++index < length) {
-    let predicate = predicates[index]
+    const predicate = predicates[index]
     if (isPromise(predicate)) {
       return predicate.then(curry3(
         thunkConditional,
@@ -40,20 +44,19 @@ const areAnyNonfunctionsTruthy = function (predicates, index) {
  * @synopsis
  * ```coffeescript [specscript]
  * asyncAreAnyPredicatesTruthy(
+ *   args Array,
  *   predicates Array<predicate function|nonfunction>,
- *   point any,
  *   index number,
  * ) -> allTruthy boolean
  * ```
  */
-const asyncAreAnyPredicatesTruthy = async function (predicates, point, index) {
+const asyncAreAnyPredicatesTruthy = async function (args, predicates, index) {
   const length = predicates.length
   while (++index < length) {
     let predicate = predicates[index]
     if (typeof predicate == 'function') {
-      predicate = predicate(point)
+      predicate = predicate(...args)
     }
-    console.log('hey - or', predicate)
     if (isPromise(predicate)) {
       predicate = await predicate
     }
@@ -64,34 +67,65 @@ const asyncAreAnyPredicatesTruthy = async function (predicates, point, index) {
   return false
 }
 
+// areAnyPredicatesTruthy(args Array, predicates Array<function>) -> Promise|boolean
+const areAnyPredicatesTruthy = function (args, predicates) {
+  const length = predicates.length
+  let index = -1
+
+  while (++index < length) {
+    let predicate = predicates[index]
+    if (typeof predicate == 'function') {
+      predicate = predicate(...args)
+    }
+    if (isPromise(predicate)) {
+      return predicate.then(curry3(
+        thunkConditional,
+        __,
+        always(true),
+        thunkify3(asyncAreAnyPredicatesTruthy, args, predicates, index),
+      ))
+    }
+    if (predicate) {
+      return true
+    }
+  }
+  return false
+}
+
 /**
  * @name or
  *
  * @synopsis
  * ```coffeescript [specscript]
- * or(
- *   predicates Array<predicate function|nonfunction>,
- * )(point any) -> Promise|boolean
+ * or(values Array<boolean>) -> result boolean
+ *
+ * or(...args, predicatesOrValues Array<function|boolean>) -> Promise|boolean
+ *
+ * or(predicatesOrValues Array<function|boolean>)(...args) -> Promise|boolean
  * ```
  *
  * @description
- * Test an array of predicates serially against a single input, returning true if any of them test truthy.
+ * Tests an array of boolean values, returning true if any boolean values are truthy.
  *
  * ```javascript [playground]
- * const isOdd = number => number % 2 == 1
- *
- * const isEven = number => number % 2 == 0
+ * const oneIsLessThanZero = 1 < 0
+ * const oneIsGreaterThanTwo = 1 > 2
+ * const threeIsNotEqualToThree = 3 !== 3
  *
  * console.log(
- *   or([isOdd, isEven])(0),
- * ) // true
+ *   or([oneIsLessThanZero, oneIsGreaterThanTwo, threeIsNotEqualToThree]),
+ * ) // false
  * ```
  *
- * `or` behaves eagerly if provided only nonfunction values
+ * If any values in the array are synchronous or asynchronous predicate functions, `or` takes another argument to test concurrently against the predicate functions, returning true if any array values or resolved values from the predicates are truthy.
  *
  * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * const isEven = number => number % 2 == 0
+ *
  * console.log(
- *   or([false, false, true]),
+ *   or([isOdd, isEven])(0),
  * ) // true
  * ```
  *
@@ -99,33 +133,22 @@ const asyncAreAnyPredicatesTruthy = async function (predicates, point, index) {
  *
  * @note ...args slows down here by an order of magnitude
  */
-const or = predicates => {
-  if (areAllValuesNonfunctions(predicates)) {
-    return areAnyNonfunctionsTruthy(predicates, -1)
+const or = function (...args) {
+  const predicatesOrValues = args.pop()
+  if (areAllValuesNonfunctions(predicatesOrValues)) {
+    return areAnyNonfunctionsTruthy(predicatesOrValues, -1)
   }
-  return function areAnyPredicatesTruthy(point) {
-    const length = predicates.length
-    let index = -1
 
-    while (++index < length) {
-      let predicate = predicates[index]
-      if (typeof predicate == 'function') {
-        predicate = predicate(point)
-      }
-      if (isPromise(predicate)) {
-        return predicate.then(curry3(
-          thunkConditional,
-          __,
-          always(true),
-          thunkify3(asyncAreAnyPredicatesTruthy, predicates, point, index),
-        ))
-      }
-      if (predicate) {
-        return true
-      }
-    }
-    return false
+  if (args.length == 0) {
+    return curryArgs2(areAnyPredicatesTruthy, __, predicatesOrValues)
   }
+
+  if (areAnyValuesPromises(args)) {
+    return promiseAll(args)
+      .then(curry2(areAnyPredicatesTruthy, __, predicatesOrValues))
+  }
+
+  return areAnyPredicatesTruthy(args, predicatesOrValues)
 }
 
 module.exports = or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "1.9.6",
+  "version": "2.0.0",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "MIT",
@@ -33,23 +33,23 @@
     "operator"
   ],
   "devDependencies": {
+    "async": "^3.2.4",
     "bluebird": "^3.7.2",
     "codecov": "^3.7.1",
     "eslint": "^8.4.1",
     "fantasy-land": "^4.1.0",
-    "lodash": "^4.17.19",
+    "lodash": "^4.17.21",
     "mocha": "^7.2.0",
     "node-fetch": "^2.6.1",
     "nyc": "^15.1.0",
-    "ramda": "^0.27.1",
+    "ramda": "^0.29.0",
     "terser": "^5.10.0",
     "thunk-test": "latest"
   },
   "scripts": {
-    "test": "mocha test.js x/*.test.js monad/*.test.js",
+    "test": "mocha test.js *.test.js */**.test.js",
     "test-coverage": "nyc mocha test.js x/*.test.js monad/*.test.js",
-    "lint": "eslint _internal rubico.js x monad",
-    "lint-fix": "eslint --fix _internal rubico.js x monad",
-    "build": "node distributor.js"
+    "lint": "eslint .",
+    "build": "./build"
   }
 }

package/pick.js

@@ -1,46 +1,76 @@
+const isPromise = require('./_internal/isPromise')
 const getByPath = require('./_internal/getByPath')
 const setByPath = require('./_internal/setByPath')
+const curry2 = require('./_internal/curry2')
+const __ = require('./_internal/placeholder')
+
+// _pick(source Object, keys Array<string>) -> result Object
+const _pick = function (source, keys) {
+  if (source == null) {
+    return source
+  }
+  const keysLength = keys.length
+  let result = {}
+  let keysIndex = -1
+  while (++keysIndex < keysLength) {
+    const key = keys[keysIndex],
+      value = getByPath(source, key)
+    if (value != null) {
+      result = setByPath(result, value, key)
+    }
+  }
+  return result
+}
 
 /**
  * @name pick
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var keys Array<string>,
- *   source Object
+ * pick(object Object, keys Array<string>) -> result Object
  *
- * pick(keys)(source) -> picked Object
+ * pick(keys Array<string>)(object Object) -> result Object
  * ```
  *
  * @description
- * Create a new object by including specific keys.
+ * Creates a new object from a source object by selecting provided keys. If a provided key does not exist on the source object, excludes it from the resulting object.
  *
  * ```javascript [playground]
  * console.log(
- *   pick(['hello', 'world'])({ goodbye: 1, world: 2 }),
+ *   pick({ goodbye: 1, world: 2 }, ['hello', 'world']),
  * ) // { world: 2 }
+ * ```
  *
- * console.log(
- *   pick(['a.b.c.d'])({ a: { b: { c: { d: 1, e: [2, 3] } } } }),
- * ) // { a: { b: { c: { d: 1 } } } }
+ * `pick` supports three types of path patterns for nested property access
+ *
+ *  * dot delimited - `'a.b.c'`
+ *  * bracket notation - `'a[0].value'`
+ *  * an array of keys or indices - `['a', 0, 'value']`
+ *
+ * ```javascript [playground]
+ * const nested = { a: { b: { c: { d: 1, e: [2, 3] } } } }
+ *
+ * console.log(pick(['a.b.c.d'])(nested)) // { a: { b: { c: { d: 1 } } } }
+ * ```
+ *
+ * Compose `pick` inside a `pipe` with its tacit API.
+ *
+ * ```javascript [playground]
+ * pipe({ a: 1, b: 2, c: 3 }, [
+ *   map(number => number ** 2),
+ *   pick(['a', 'c']),
+ *   console.log, // { a: 1, c: 9 }
+ * ])
  * ```
  */
-
-const pick = keys => function picking(source) {
-  if (source == null) {
-    return source
+const pick = function (arg0, arg1) {
+  if (arg1 == null) {
+    return curry2(_pick, __, arg0)
   }
-  const keysLength = keys.length
-  let result = {}
-  let keysIndex = -1
-  while (++keysIndex < keysLength) {
-    const key = keys[keysIndex],
-      value = getByPath(source, key)
-    if (value != null) {
-      result = setByPath(result, value, key)
-    }
+  if (isPromise(arg0)) {
+    return arg0.then(curry2(_pick, __, arg1))
   }
-  return result
+  return _pick(arg0, arg1)
 }
 
 module.exports = pick

package/pipe.js

@@ -1,66 +1,42 @@
-const noop = require('./_internal/noop')
+const areAnyValuesPromises = require('./_internal/areAnyValuesPromises')
+const promiseAll = require('./_internal/promiseAll')
 const funcConcat = require('./_internal/funcConcat')
-const funcConcatSync = require('./_internal/funcConcatSync')
-const isGeneratorFunction = require('./_internal/isGeneratorFunction')
-const isAsyncGeneratorFunction = require('./_internal/isAsyncGeneratorFunction')
+const funcApply = require('./_internal/funcApply')
+const curry2 = require('./_internal/curry2')
+const __ = require('./_internal/placeholder')
 
 /**
  * @name pipe
  *
  * @synopsis
  * ```coffeescript [specscript]
- * Reducer<T> = (any, T)=>Promise|any
+ * pipe(funcs Array<function>)(...args) -> result Promise|any
  *
- * var args ...any,
- *   funcs [
- *     ...args=>Promise|any,
- *     ...Array<any=>Promise|any>,
- *   ],
- *   transducers Array<Reducer=>Reducer>
- *   reducer Reducer,
- *
- * pipe(funcs)(...args) -> Promise|any
- *
- * pipe(transducers)(reducer) -> Reducer
+ * pipe(...args, funcs Array<function>) -> result Promise|any
  * ```
  *
  * @description
- * Create a function pipeline, where each function passes its return value as a single argument to the next function until all functions have executed. The result of a pipeline execution is the return of its last function.
+ * Creates a function pipeline from an array of functions, where each function passes its return value as a single argument to the next function until all functions have executed. The first function is called with the arguments to the pipeline, while the result of the pipeline execution is the return of its last function. If any function of the pipeline is asynchronous, the result of the execution is a Promise.
  *
  * ```javascript [playground]
- * console.log(
- *   pipe([
- *     number => number + 1,
- *     number => number + 2,
- *     number => number + 3,
- *   ])(5),
- * ) // 11
- * ```
- *
- * In order to create pipelines of transducers that read left to right, `pipe` chains the functions (assuming they are transducers) in reverse when passed a reducer in argument position. This results in a reducer with chained functionality. For more information on this behavior, see [this blog post on transducers](https://rubico.land/blog/2020/10/02/transducers-crash-course).
- *
- * ```javascript [playground]
- * const isOdd = number => number % 2 == 1
- *
- * const square = number => number ** 2
+ * const syncAdd123 = pipe([
+ *   number => number + 1,
+ *   number => number + 2,
+ *   number => number + 3,
+ * ])
  *
- * const add = (a, b) => a + b
+ * console.log(syncAdd123(5)) // 11
  *
- * const squaredOdds = pipe([
- *   filter(isOdd),
- *   map(square),
+ * const asyncAdd123 = pipe([
+ *   async number => number + 1,
+ *   async number => number + 2,
+ *   async number => number + 3,
  * ])
  *
- * console.log(
- *   [1, 2, 3, 4, 5].reduce(squaredOdds(add), 0),
- * ) // 35
- *
- * console.log(
- *   squaredOdds([1, 2, 3, 4, 5])
- * ) // [1, 9, 25]
+ * asyncAdd123(5).then(console.log) // 11
  * ```
  *
- * For the sake of a sane API, pipe behaves eagerly when passed any amount of arguments before the array of functions.
+ * When passed any amount of arguments before the array of functions, `pipe` executes eagerly; the array of functions is immediately invoked with the supplied arguments.
  *
  * ```javascript [playground]
  * pipe(1, 2, 3, [
@@ -78,58 +54,17 @@ const isAsyncGeneratorFunction = require('./_internal/isAsyncGeneratorFunction')
  */
 const pipe = function (...args) {
   const funcs = args.pop()
+  const pipeline = funcs.reduce(funcConcat)
 
-  if (args.length > 0) {
-    return funcs.reduce(funcConcat)(...args)
+  if (args.length == 0) {
+    return pipeline
   }
 
-  let functionPipeline = noop,
-    functionComposition = noop
-  return function pipeline(...args) {
-    const firstArg = args[0]
-
-    if (
-      typeof firstArg == 'function'
-        && !isGeneratorFunction(firstArg)
-        && !isAsyncGeneratorFunction(firstArg)
-    ) {
-      if (functionComposition == noop) {
-        functionComposition = funcs.reduceRight(funcConcat)
-      }
-      return functionComposition(firstArg)
-    }
-
-    if (functionPipeline == noop) {
-      functionPipeline = funcs.reduce(funcConcat)
-    }
-    return functionPipeline(...args)
+  if (areAnyValuesPromises(args)) {
+    return promiseAll(args).then(curry2(funcApply, pipeline, __))
   }
-}
-
-// funcs Array<function> -> pipeline function
-const pipeSync = funcs => funcs.reduce(funcConcatSync)
 
-/**
- * @name pipe.sync
- *
- * @synopsis
- * ```coffeescript [specscript]
- * var args ...any,
- *   funcs [...args=>any, ...Array<any=>any>]
- *
- * pipe.sync(funcs) -> syncPipeline ...args=>any
- * ```
- *
- * @description
- * `pipe` that doesn't automatically resolve promises. This variant is a good option if more performance is desired or if manual promise handling is required.
- *
- * ```javascript [playground]
- * pipe.sync([
- *   value => Promise.resolve(value),
- *   promise => promise.then(console.log)
- * ])('hey') // hey
- * ```
- */
-pipe.sync = pipeSync
+  return pipeline(...args)
+}
 
 module.exports = pipe