rubico 1.9.6 → 2.0.0

package/thunkify.js

@@ -1,16 +1,19 @@
+const areAnyValuesPromises = require('./_internal/areAnyValuesPromises')
+const promiseAll = require('./_internal/promiseAll')
+const curry2 = require('./_internal/curry2')
+const __ = require('./_internal/placeholder')
+const funcApply = require('./_internal/funcApply')
+
 /**
  * @name thunkify
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var func function,
- *   args ...any
- *
- * thunkify(func, ...args) -> thunk ()=>func(...args)
+ * thunkify(func function, ...args) -> thunk ()=>func(...args)
  * ```
  *
  * @description
- * Create a thunk from a function and any number of arguments. A thunk is a function that takes no arguments - the computation it represents has already been "thunk" with given function and arguments.
+ * Create a thunk function from another function and any number of arguments. The thunk function takes no arguments, and when called, executes the other function with the provided arguments. The other function is said to be "thunkified".
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -21,6 +24,9 @@
  * ```
  */
 const thunkify = (func, ...args) => function thunk() {
+  if (areAnyValuesPromises(args)) {
+    return promiseAll(args).then(curry2(funcApply, func, __))
+  }
   return func(...args)
 }
 

package/transform.js

@@ -3,36 +3,55 @@ const __ = require('./_internal/placeholder')
 const curry3 = require('./_internal/curry3')
 const genericTransform = require('./_internal/genericTransform')
 
+// _transform(collection any, transducer function, initialValue function|any) -> Promise
+const _transform = function (collection, transducer, initialValue) {
+  if (typeof initialValue == 'function') {
+    const actualInitialValue = initialValue(collection)
+    return isPromise(actualInitialValue)
+      ? actualInitialValue.then(curry3(genericTransform, collection, transducer, __))
+      : genericTransform(collection, transducer, actualInitialValue)
+  }
+  return isPromise(initialValue)
+    ? initialValue.then(curry3(genericTransform, collection, transducer, __))
+    : genericTransform(collection, transducer, initialValue)
+}
+
 /**
  * @name transform
  *
  * @synopsis
  * ```coffeescript [specscript]
- * Reducer<T> = (any, T)=>Promise|any
- * Semigroup<T> = Array<T>|String<T>|Set<T>|TypedArray<T>
- *   |{ concat: Reducer<T> }|{ write: Reducer<T> }|Object<T>
- * Foldable<T> = Iterable<T>|AsyncIterable<T>|{ reduce: Reducer<T>=>any }|Object<T>
- *
- * var T any,
- *   args ...any,
- *   transducer Reducer=>Reducer,
- *   init (...args=>Promise|Semigroup<T>)|Semigroup<T>,
- *   foldable Foldable<T>,
- *   generatorFunction ...args=>Generator<T>,
- *   asyncGeneratorFunction ...args=>AsyncGenerator<T>,
- *   reducers ...Reducer<T>
+ * type Reducer = (result any, item any)=>(result any)
+ * type Transducer = Reducer=>Reducer
+ * type Transformable = Array|String|Set|TypedArray|{ concat: function }|{ write: function }|Object
+ * type Foldable = Iterable|AsyncIterable|Object<value any>
  *
- * transform(transducer, init?)(foldable) -> Promise|Semigroup
+ * initialValue Transformable|((foldable Foldable)=>Promise|Transformable)
  *
- * transform(transducer, init?)(generatorFunction) -> ...args=>Promise|Semigroup
- *
- * transform(transducer, init?)(asyncGeneratorFunction) -> ...args=>Promise|Semigroup
+ * transform(
+ *   foldable Foldable,
+ *   transducer Transducer,
+ *   initialValue? Transformable|(Foldable=>Promise|Transformable),
+ * ) -> result Promise|Transformable
  *
- * transform(transducer, init?)(...reducers) -> ...args=>Promise|Semigroup
+ * transform(
+ *   transducer Transducer,
+ *   initialValue? Transformable|(Foldable=>Promise|Transformable),
+ * )(foldable Foldable) -> result Promise|Transformable
  * ```
  *
  * @description
- * Reduce a value by transducer and concatenation, returning a semigroup of transduced items. The initial value may be a function, in which case it is treated as a resolver.
+ * Transforms a transformable collection into any other transformable collection. The type of transformation depends on the collection provided by the initial value. If the initial is a function it is used as a resolver for the provided collection. `transform` accepts transformable collections, or collections that support a concatenation operation:
+ *
+ *  * `Array`; concatenation defined by `result.concat(values)`
+ *  * `string`; concatenation defined by `result + values`
+ *  * `Set`; concatenation defined by `result.add(...values)`
+ *  * `TypedArray`; concatenation defined by `result.set(prevResult); result.set(values, offset)`
+ *  * `{ concat: function }`; concatenation defined by `result.concat(values)`
+ *  * `{ write: function }`; concatenation defined by `result.write(item)`
+ *  * `Object`; concatenation defined by `({ ...result, ...values })`
+ *
+ * `transform` can transform any of the above collections into any of the other above collections.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -44,29 +63,28 @@ const genericTransform = require('./_internal/genericTransform')
  *   map(square),
  * ])
  *
+ * // transform arrays into arrays
  * console.log(
- *   transform(squaredOdds, () => [])([1, 2, 3, 4, 5]),
+ *   transform(squaredOdds, [])([1, 2, 3, 4, 5])
  * ) // [1, 9, 25]
  *
+ * // transform arrays into strings
  * console.log(
- *   transform(squaredOdds, '')([1, 2, 3, 4, 5]),
+ *   transform(squaredOdds, '')([1, 2, 3, 4, 5])
  * ) // '1925'
  *
+ * // transform arrays into sets
+ * console.log(
+ *   transform(squaredOdds, new Set())([1, 2, 3, 4, 5])
+ * ) // Set (3) { 1, 9, 25 }
+ *
+ * // transform arrays into typed arrays
  * console.log(
- *   transform(squaredOdds, () => new Uint8Array())([1, 2, 3, 4, 5]),
+ *   transform(squaredOdds, new Uint8Array())([1, 2, 3, 4, 5]),
  * ) // Uint8Array(3) [ 1, 9, 25 ]
  * ```
  *
- * A `Semigroup` is any type with some notion of concatenation. This could possibly manifest in a `.concat` method.
- *  * `Array` - `result.concat(values)`
- *  * `string` - `result + values`
- *  * `Set` - `result.add(...values)`
- *  * `TypedArray` - `result.set(prevResult); result.set(values, offset)`
- *  * `{ concat: function }` - `result.concat(values)`
- *  * `{ write: function }` - essentially `item.pipe(result)` or `result.write(item)`
- *  * `Object` - `({ ...result, ...values })`
- *
- * Here is a simple `Semigroup` as an object that implements `.concat`.
+ * `transform` arrays into objects that implement `.concat`.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -86,7 +104,7 @@ const genericTransform = require('./_internal/genericTransform')
  * // 25
  * ```
  *
- * Here is a transformation of an async generator to a Node.js writable stream, `process.stdout`.
+ * `transform` an async generator into `process.stdout`, a Node.js writable stream that implements `.write`.
  *
  * ```javascript [node]
  * // this example is duplicated in rubico/examples/transformStreamRandomInts.js
@@ -110,62 +128,20 @@ const genericTransform = require('./_internal/genericTransform')
  * )(streamRandomInts()) // 9216576529289484980147613249169774446246768649...
  * ```
  *
- * `transform`, like `reduce`, supports reducer combination. This variant of state management automatically assigns (`Object.assign`) pipeline objects into the aggregate state object.
- *
- * ```javascript [playground]
- * const reducerA = async (state, action) => {
- *   if (action.type == 'A') return { ...state, A: true }
- *   return state
- * }
- *
- * const reducerB = async (state, action) => {
- *   if (action.type == 'B') return { ...state, B: true }
- *   return state
- * }
- *
- * const reducerC = async (state, action) => {
- *   if (action.type == 'C') return { ...state, C: true }
- *   return state
- * }
- *
- * const logAction = function (action) {
- *   console.log('action', action)
- *   return action
- * }
- *
- * const reducingABC = transform(
- *   map(logAction), // transducer logger middleware
- *   () => ({}), // initial state resolver
- * )(reducerA, reducerB, reducerC)
- *
- * const actions = [{ type: 'A' }, { type: 'B' }, { type: 'C' }]
- *
- * reducingABC(actions).then(
- *   state => console.log('state', state))
- * // action { type: 'A' }
- * // action { type: 'B' }
- * // action { type: 'C' }
- * // state { A: true, B: true, C: true }
- * ```
- *
  * @execution series
  *
  * @transducing
  *
  * TODO explore Semigroup = Iterator|AsyncIterator
  */
-const transform = function (transducer, init) {
-  if (typeof init == 'function') {
-    return function transforming(...args) {
-      const result = init(...args)
-      return isPromise(result)
-        ? result.then(curry3(genericTransform, args, transducer, __))
-        : genericTransform(args, transducer, result)
-    }
+const transform = function (...args) {
+  if (typeof args[0] == 'function') {
+    return curry3(_transform, __, args[0], args[1])
   }
-  return function transforming(...args) {
-    return genericTransform(args, transducer, init)
+  if (isPromise(args[0])) {
+    return args[0].then(curry3(_transform, __, args[1], args[2]))
   }
+  return _transform(args[0], args[1], args[2])
 }
 
 module.exports = transform

package/tryCatch.js

@@ -1,39 +1,55 @@
 const isPromise = require('./_internal/isPromise')
+const promiseAll = require('./_internal/promiseAll')
 const __ = require('./_internal/placeholder')
 const curry3 = require('./_internal/curry3')
 const catcherApply = require('./_internal/catcherApply')
+const areAnyValuesPromises = require('./_internal/areAnyValuesPromises')
+
+// _tryCatch(tryer function, catcher function, args Array) -> Promise
+const _tryCatch = function (tryer, catcher, args) {
+  try {
+    const result = tryer(...args)
+    return isPromise(result)
+      ? result.catch(curry3(catcherApply, catcher, __, args))
+      : result
+  } catch (error) {
+    return catcher(error, ...args)
+  }
+}
 
 /**
  * @name tryCatch
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var args ...any,
- *   tryer ...args=>Promise|any,
- *   catcher (error Error, ...args)=>Promise|any
+ * tryCatch(tryer function, catcher function)(...args) -> Promise|any
  *
- * tryCatch(tryer, catcher)(...args) -> Promise|any
+ * tryCatch(...args, tryer function, catcher function) -> Promise|any
  * ```
  *
  * @description
- * Try a `tryer`, catch with `catcher`. On error or rejected promise, call the `catcher` with the error followed by any arguments to the tryer.
+ * Handles errors with a `tryer` and a `catcher` function. Calls the `tryer` function with the provided arguments and catches any errors thrown by the `tryer` function with the `catcher` function. If the `tryer` function is asynchronous and returns a rejected promise, the `catcher` function will execute with the value of the rejected promise. The `catcher` function is called with the error and all arguments supplied to the `tryer` function.
  *
  * ```javascript [playground]
- * const errorThrower = tryCatch(
- *   message => {
- *     throw new Error(message)
- *   },
- *   (error, message) => {
- *     console.log(error)
- *     return `${message} from catcher`
- *   },
- * )
+ * const throwsIfOdd = number => {
+ *   if (number % 2 == 1) {
+ *     throw new Error(`${number} is odd`)
+ *   }
+ *   console.log('did not throw for', number)
+ * }
+ *
+ * const errorHandler = tryCatch(throwsIfOdd, (error, number) => {
+ *   console.log('caught error from number', number)
+ *   console.log(error)
+ * })
+ *
+ * errorHandler(2) // did not throw for 2
+ * errorHandler(3) // caught error from number 3
+ *                 // Error: 3 is odd
  *
- * console.log(errorThrower('hello')) // Error: hello
- *                                    // hello from catcher
  * ```
  *
- * `tryCatch` behaves eagerly when passed any amount of arguments before the tryer and catcher.
+ * `tryCatch` behaves eagerly (executes immediately with a single call and not with multiple calls like a higher order function) when passed any amount of nonfunction (primitive or object) arguments before the `tryer` and `catcher` functions.
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -51,27 +67,17 @@ const tryCatch = function (...args) {
   if (args.length > 2) {
     const catcher = args.pop(),
       tryer = args.pop()
-    try {
-      const result = tryer(...args)
-      return isPromise(result)
-        ? result.catch(curry3(catcherApply, catcher, __, args))
-        : result
-    } catch (error) {
-      return catcher(error, ...args)
+    if (areAnyValuesPromises(args)) {
+      return promiseAll(args)
+        .then(curry3(_tryCatch, tryer, catcher, __))
     }
+    return _tryCatch(tryer, catcher, args)
   }
 
   const tryer = args[0],
     catcher = args[1]
   return function tryCatcher(...args) {
-    try {
-      const result = tryer(...args)
-      return isPromise(result)
-        ? result.catch(curry3(catcherApply, catcher, __, args))
-        : result
-    } catch (error) {
-      return catcher(error, ...args)
-    }
+    return _tryCatch(tryer, catcher, args)
   }
 }
 

package/x/differenceWith.js

@@ -6,7 +6,7 @@ const thunkify5 = require('../_internal/thunkify5')
 const thunkConditional = require('../_internal/thunkConditional')
 const isPromise = require('../_internal/isPromise')
 const isArray = require('../_internal/isArray')
-const arrayAny = require('../_internal/arrayAny')
+const arraySome = require('../_internal/arraySome')
 const arrayPush = require('../_internal/arrayPush')
 const funcConcatSync = require('../_internal/funcConcatSync')
 const noop = require('../_internal/noop')
@@ -33,7 +33,7 @@ const differenceWithArrayAsync = async function (
   const allValuesLength = allValues.length
   while (++index < allValuesLength) {
     const item = allValues[index]
-    let doesItemExistByComparator = arrayAny(array, curry2(comparator, item, __))
+    let doesItemExistByComparator = arraySome(array, curry2(comparator, item, __))
     if (isPromise(doesItemExistByComparator)) {
       doesItemExistByComparator = await doesItemExistByComparator
     }
@@ -62,7 +62,7 @@ const differenceWithArray = function (comparator, allValues, array) {
   let index = -1
   while (++index < allValuesLength) {
     const item = allValues[index],
-      doesItemExistByComparator = arrayAny(array, curry2(comparator, item, __))
+      doesItemExistByComparator = arraySome(array, curry2(comparator, item, __))
     if (isPromise(doesItemExistByComparator)) {
       return doesItemExistByComparator.then(funcConcatSync(
         curry3(thunkConditional, __, noop, thunkify2(arrayPush, result, item)),

package/x/filterOut.test.js

@@ -40,13 +40,13 @@ describe('filterOut', () => {
 
   it('creates a rejecting generator function when passed a generator', () => {
     const rejectOdds = filterOut(number => number % 2 == 1)
-    const oddsRejectingGeneratorFunc = rejectOdds(function* (array) {
+    const oddsRejectingGenerator = rejectOdds((function* (array) {
       for (const value of array) {
         yield value
       }
-    })
+    })([1, 2, 3, 4, 5]))
     const evensArray = []
-    for (const number of oddsRejectingGeneratorFunc([1, 2, 3, 4, 5])) {
+    for (const number of oddsRejectingGenerator) {
       evensArray.push(number)
     }
     assert.deepEqual(evensArray, [2, 4])
@@ -54,13 +54,13 @@ describe('filterOut', () => {
 
   it('creates a rejecting generator function when passed an async generator', async () => {
     const asyncRejectOdds = filterOut(async number => number % 2 == 1)
-    const oddsRejectingGeneratorFunc = asyncRejectOdds(async function* (array) {
+    const oddsRejectingGenerator = asyncRejectOdds((async function* (array) {
       for (const value of array) {
         yield value
       }
-    })
+    })([1, 2, 3, 4, 5]))
     const evensArray = []
-    for await (const number of oddsRejectingGeneratorFunc([1, 2, 3, 4, 5])) {
+    for await (const number of oddsRejectingGenerator) {
       evensArray.push(number)
     }
     assert.deepEqual(evensArray, [2, 4])

package/x/flatten.js

@@ -74,7 +74,7 @@ const flatten = function (value) {
   if (value.constructor == Object) {
     return objectFlatten(value)
   }
-  return flatMap(identity)(value)
+  return flatMap(value, identity)
 }
 
 module.exports = flatten

package/x/flatten.test.js

@@ -34,12 +34,4 @@ describe('flatten', () => {
   it('flatten(undefined)', async () => {
     assert.strictEqual(flatten(undefined), undefined)
   })
-  it('flatteningReducer', async () => {
-    const add = (a, b) => a + b
-    const flatteningAdd = flatten(add)
-    assert.strictEqual(
-      [[1], [2], [3], [4], [5]].reduce(flatteningAdd, 0),
-      15,
-    )
-  })
 })

package/x/index.js

@@ -7,7 +7,6 @@ const find = require('./find')
 const findIndex = require('./findIndex')
 const first = require('./first')
 const flatten = require('./flatten')
-const forEach = require('./forEach')
 const groupBy = require('./groupBy')
 const has = require('./has')
 const identity = require('./identity')
@@ -43,7 +42,6 @@ const rubicoX = {
   findIndex,
   first,
   flatten,
-  forEach,
   groupBy,
   has,
   identity,

package/x/pluck.js

@@ -7,28 +7,19 @@ const get = require('../get')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * Functor<T> = Array<T>|Object<T>|Iterator<T>|AsyncIterator<T>|{ map: T=>any }
- * Reducer<T> = (any, T)=>Promise|any
+ * pluck(path string)(array Array) -> result Array
  *
- * var T any,
- *   mapper T=>Promise|any,
- *   functor Functor<T>
- *   args ...any,
- *   generatorFunction ...args=>Generator<T>,
- *   asyncGeneratorFunction ...args=>AsyncGenerator<T>,
- *   reducer Reducer<T>
- *
- * pluck(functor) -> Promise|Functor
- *
- * pluck(generatorFunction) -> ...args=>Generator
- *
- * pluck(asyncGeneratorFunction) -> ...args=>AsyncGenerator
- *
- * pluck(reducer) -> Reducer
+ * pluck(array Array, path string) -> result Array
  * ```
  *
  * @description
- * Apply a getter denoted by path across all items of a collection, creating a new collection of plucked values. Also works in transducer position.
+ * Creates an array of picked properties denoted by a path from another array.
+ *
+ * `pluck` 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]
  * import pluck from 'https://unpkg.com/rubico/dist/x/pluck.es.js'
@@ -39,18 +30,18 @@ const get = require('../get')
  *   { name: 'Jim', age: 22 },
  * ]
  *
- * const usernames = pluck('name')(users)
+ * const usernames = pluck(users, 'name')
  *
  * console.log(usernames) // ['George', 'Jane', 'Jim']
- *
- * const add = (a, b) => a + b
- *
- * console.log(
- *   'total age:',
- *   users.reduce(pluck('age')(add), 0),
- * ) // total age: 96
  * ```
  */
-const pluck = funcConcat(get, map)
+const pluck = function (...args) {
+  const path = args.pop()
+  const getter = get(path)
+  if (args.length == 0) {
+    return map(getter)
+  }
+  return map(args[0], getter)
+}
 
 module.exports = pluck

package/x/pluck.test.js

@@ -5,17 +5,13 @@ const createAbc = v => ({ a: { b: { c: v } } })
 
 describe('pluck', () => {
   it('creates a new collection by getting a path from every item of an old collection', async () => {
+    const nested = [1, 2, 3].map(createAbc)
     assert.deepEqual(
-      pluck('a.b.c')([1, 2, 3].map(createAbc)),
+      pluck('a.b.c')(nested),
       [1, 2, 3],
     )
-  })
-  it('works in transducer position', async () => {
     assert.deepEqual(
-      [1, 2, 3].map(createAbc).reduce(
-        pluck('a.b.c')((a, b) => a.concat([b])),
-        [],
-      ),
+      pluck(nested, 'a.b.c'),
       [1, 2, 3],
     )
   })

package/x/timeInLoop.js

@@ -1,23 +1,22 @@
+const _timeInLoop = require('../_internal/timeInLoop')
+const timeInLoopAsync = require('../_internal/timeInLoopAsync')
+
 /**
  * @name timeInLoop
  *
  * @synopsis
  * timeInLoop(desc string, loopCount number, fn function) -> undefined
  *
- * @catchphrase
- * How long does a function take to run this many loops
+ * @description
+ * Logs the amount of time required for a function to run a certain number of times
+ *
+ * ```coffeescript [specscript]
+ * timeInLoop('hello', 1e6, () => 'hello') // hello: 1e+6: 3.474ms
+ * ```
  *
- * @example
- * timeInLoop('yo', 1e6, () => 'yo') // yo: 1e+6: 3.474ms
+ * Reference: https://gist.github.com/funfunction/91b5876a5f562e1e352aed0fcabc3858
  */
-const timeInLoop = (desc, loopCount, fn) => {
-  const d = `${desc}: ${loopCount.toExponential()}`
-  console.time(d)
-  for (let i = 0; i < loopCount; i++) {
-    fn()
-  }
-  console.timeEnd(d)
-}
+const timeInLoop = _timeInLoop
 
 /**
  * @name timeInLoop.async
@@ -25,21 +24,13 @@ const timeInLoop = (desc, loopCount, fn) => {
  * @synopsis
  * timeInLoop.async(desc string, loopCount number, fn function) -> undefined
  *
- * @catchphrase
+ * @description
  * Like timeInLoop, but every call is awaited
  *
- * @example
- * timeInLoop.async('asyncYo', 1e6, async () => 'yo') // asyncYo: 1e+6: 116.006ms
+ * ```coffeescript [specscript]
+ * timeInLoop.async('async hello', 1e6, async () => 'hello') // async hello: 1e+6: 116.006ms
+ * ```
  */
-timeInLoop.async = async (desc, loopCount, fn) => {
-  const d = `${desc}: ${loopCount.toExponential()}`
-  console.time(d)
-  for (let i = 0; i < loopCount; i++) {
-    await fn()
-  }
-  console.timeEnd(d)
-}
+timeInLoop.async = timeInLoopAsync
 
 module.exports = timeInLoop
-
-// thanks: https://gist.github.com/funfunction/91b5876a5f562e1e352aed0fcabc3858

package/x/timeInLoop.test.js

@@ -3,14 +3,18 @@ const timeInLoop = require('./timeInLoop')
 
 describe('timeInLoop', () => {
   it('timeInLoop(desc string, loopCount number, fn function) -> y undefined', async () => {
-    const y = timeInLoop('hey', 1e5, () => 'hey')
-    assert.strictEqual(y, undefined)
+    const result = timeInLoop('hey', 1e5, () => 'hey')
+    assert.equal(result.description, 'hey')
+    assert.equal(result.loopCount, 1e5)
+    assert.equal(typeof result.duration, 'number')
   })
 
   it('timeInLoop.async(desc string, loopCount number, fn function) -> y undefined', async () => {
     const p = timeInLoop.async('asyncHey', 1e5, async () => 'asyncHey')
     assert(p instanceof Promise)
-    const y = await p
-    assert.strictEqual(y, undefined)
+    const result = await p
+    assert.equal(result.description, 'asyncHey')
+    assert.equal(result.loopCount, 1e5)
+    assert.equal(typeof result.duration, 'number')
   })
 })