rubico 1.9.6 → 2.0.0

package/.eslintignore

@@ -0,0 +1,5 @@
+archive
+dist
+es.js
+index.js
+benchmarks

package/.eslintrc.js

@@ -192,7 +192,7 @@ module.exports = {
                 'allowForLoopAfterthoughts': true
             }
         ],
-        'no-process-env': 'error',
+        'no-process-env': 'off',
         'no-process-exit': 'error',
         'no-promise-executor-return': 'off',
         'no-proto': 'error',
@@ -209,7 +209,8 @@ module.exports = {
         'no-sequences': 'off',
         'no-shadow': 'off',
         'no-spaced-func': 'error',
-        'no-sync': 'error',
+        'no-sparse-arrays': 'off',
+        'no-sync': 'off',
         'no-tabs': 'error',
         'no-template-curly-in-string': 'error',
         'no-ternary': 'off',

package/.github/workflows/nodejs.yml

@@ -16,7 +16,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 15.x, 16.x, 17.x, 18.x]
+        node-version: [16.x, 18.x, 20.x]
 
     steps:
     - uses: actions/checkout@v2

package/AggregateReducer.js

@@ -0,0 +1,19 @@
+const reducerConcat = require('./_internal/reducerConcat')
+const identity = require('./_internal/identity')
+
+/**
+ * @name AggregateReducer
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * AggregateReducer(reducers Array<reducer function>) -> aggregateReducer function
+ * ```
+ */
+const AggregateReducer = function (reducers) {
+  if (reducers.length == 0) {
+    return identity
+  }
+  return reducers.reduce(reducerConcat, identity)
+}
+
+module.exports = AggregateReducer

package/AggregateReducer.test.js

@@ -0,0 +1,82 @@
+const assert = require('assert')
+const reduce = require('./reduce')
+const AggregateReducer = require('./AggregateReducer')
+
+describe('AggregateReducer', () => {
+  it('Combines reducers', async () => {
+    const reducerA = (state, action) => {
+      if (action.type == 'A') {
+        return { ...state, A: true }
+      }
+      return state
+    }
+    const reducerB = (state, action) => {
+      if (action.type == 'B') {
+        return { ...state, B: true }
+      }
+      return state
+    }
+    const reducerC = (state, action) => {
+      if (action.type == 'C') {
+        return { ...state, C: true }
+      }
+      return state
+    }
+
+    const combinedReducer = AggregateReducer([
+      reducerA,
+      reducerB,
+      reducerC,
+    ])
+
+    const stateA = [{ type: 'A' }].reduce(combinedReducer, {})
+    assert.deepEqual(stateA, { A: true })
+
+    const stateAB = [{ type: 'A' }, { type: 'B' }].reduce(combinedReducer, {})
+    assert.deepEqual(stateAB, { A: true, B: true })
+
+    const stateABC = [{ type: 'A' }, { type: 'B' }, { type: 'C' }].reduce(combinedReducer, {})
+    assert.deepEqual(stateABC, { A: true, B: true, C: true })
+  })
+
+  it('Combines async reducers', async () => {
+    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 combinedReducer = AggregateReducer([
+      reducerA,
+      reducerB,
+      reducerC,
+    ])
+
+    const stateA = await reduce([{ type: 'A' }], combinedReducer, {})
+    assert.deepEqual(stateA, { A: true })
+
+    const stateAB = await reduce([{ type: 'A' }, { type: 'B' }], combinedReducer, {})
+    assert.deepEqual(stateAB, { A: true, B: true })
+
+    const stateABC = await reduce([{ type: 'A' }, { type: 'B' }, { type: 'C' }], combinedReducer, {})
+    assert.deepEqual(stateABC, { A: true, B: true, C: true })
+  })
+
+  it('Identity', async () => {
+    const identity = AggregateReducer([])
+    assert.equal(1, identity(1))
+  })
+})

package/CHANGELOG.md

@@ -1,4 +1,25 @@
-## v1.9.3 - latest
+## v2.0.0
+ * Refactor all transducer functionality into Transducer.js from `pipe`, `map`, `filter`, and `flatMap`
+ * Remove GeneratorFunction and AsyncGeneratorFunction functionality in `map`, `filter`, `flatMap`, and `reduce`
+ * Refactor reducer chaining functionality into AggregateReducer.js from `reduce`
+ * Remove Duplex stream handling from `flatMap`
+ * Remove binary handling from `flatMap`
+ * Promises as arguments for all core functions
+ * Eager API for all core functions
+ * Automate benchmarks
+ * Remove the .sync property functions
+ * Remove the .withIndex property functions
+ * Deprecate map.own
+ * `fork` renamed to `all`
+ * `all` renamed to `every`
+ * `any` renamed to `some`
+ * new `dist-test` only validates syntax with `require`
+ * migrate `forEach` into core API.
+ * refactor transducer functionality from `forEach` into `Transducer.forEach`
+ * async performance improvements
+ * `_internal/arrayExtend` stops treating strings like arrays so `transform` creates arrays of strings as expected
+
+## v1.9.3
  * property value passed to set may be a resolver - [#224](https://github.com/a-synchronous/rubico/pull/224)
  * rubico/x/isIn - counterpart to includes - [#228](https://github.com/a-synchronous/rubico/pull/228) - [lulldev](https://github.com/lulldev)
  * rubico/x/maxBy - finds the item that is the max by a property denoted by path - [#229](https://github.com/a-synchronous/rubico/pull/229)

package/Transducer.js

@@ -0,0 +1,162 @@
+const funcConcat = require('./_internal/funcConcat')
+const reducerMap = require('./_internal/reducerMap')
+const reducerFilter = require('./_internal/reducerFilter')
+const reducerFlatMap = require('./_internal/reducerFlatMap')
+const reducerForEach = require('./_internal/reducerForEach')
+const curry2 = require('./_internal/curry2')
+const __ = require('./_internal/placeholder')
+
+/**
+ * @name Transducer
+ *
+ * @description
+ * Temporary repository of transducer functionality throughout rubico v1
+ */
+const Transducer = {}
+
+/**
+ * @name Transducer.map
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (accumulator any, item any)=>(nextAccumulator Promise|any)
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.map(mapperFunc function) -> mappingTransducer Transducer
+ * ```
+ *
+ * @description
+ * Creates a mapping transducer with a provided reducer. A reducer is a variadic function that depicts a relationship between an accumulator and any number of arguments. A transducer is a function that accepts a reducer as an argument and returns another reducer.
+ *
+ * ```coffeescript [specscript]
+ * type Reducer = (accumulator any, item any)=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ * ```
+ *
+ * The transducer signature enables chaining functionality for reducers. `map` is core to this mechanism, and provides a way via transducers to transform the items of reducers.
+ *
+ * ```javascript [playground]
+ * const square = number => number ** 2
+ *
+ * const concat = (array, item) => array.concat(item)
+ *
+ * const mapSquare = Transducer.map(square)
+ * // mapSquare is a transducer
+ *
+ * const squareConcatReducer = mapSquare(concat)
+ * // now mapSquare is passed the reducer function concat; squareConcatReducer
+ * // is a reducer with chained functionality square and concat
+ *
+ * console.log(
+ *   [1, 2, 3, 4, 5].reduce(squareConcatReducer, []),
+ * ) // [1, 4, 9, 16, 25]
+ *
+ * console.log(
+ *   [1, 2, 3, 4, 5].reduce(squareConcatReducer, ''),
+ * ) // '1491625'
+ * ```
+ *
+ * Create reducers with chained functionality by using the `Transducer.map` eager API.
+ *
+ * ```javascript [playground]
+ * const square = number => number ** 2
+ *
+ * const concat = (array, item) => array.concat(item)
+ *
+ * const squareConcatReducer = Transducer.map(concat, square)
+ * // now mapSquare is passed the reducer function concat; squareConcatReducer
+ * // is a reducer with chained functionality square and concat
+ * ```
+ */
+Transducer.map = function transducerMap(mapper) {
+  return curry2(reducerMap, __, mapper)
+}
+
+/**
+ * @name Transducer.filter
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (accumulator any, item any)=>(nextAccumulator Promise|any)
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.filter(predicate function) -> filteringTransducer Transducer
+ * ```
+ *
+ * @description
+ * A reducer in filterable position creates a filtering reducer - one that skips items of the reducer's reducing operation if they test falsy by the predicate. It is possible to use an asynchronous predicate when filtering a reducer, however the implementation of `reduce` must support asynchronous operations. This library provides such an implementation as `reduce`.
+ *
+ * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * const concat = (array, item) => array.concat(item)
+ *
+ * const concatOddNumbers = filter(isOdd)(concat)
+ *
+ * console.log(
+ *   [1, 2, 3, 4, 5].reduce(concatOddNumbers, []),
+ * ) // [1, 3, 5]
+ * ```
+ */
+Transducer.filter = function transducerFilter(predicate) {
+  return curry2(reducerFilter, __, predicate)
+}
+
+/**
+ * @name Transducer.flatMap
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (accumulator any, item any)=>(nextAccumulator Promise|any)
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.flatMap(flatMapper) -> flatMappingTransducer Transducer
+ * ```
+ *
+ * @description
+ * Additionally, `flatMap` is a powerful option when working with transducers. A flatMapping transducer applies a flatMapper to each item of a reducer's reducing operation, calling each item of each execution with the reducer.
+ *
+ * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * const powers = number => [number, number ** 2, number ** 3]
+ *
+ * const oddPowers = pipe([
+ *   filter(isOdd),
+ *   flatMap(powers),
+ * ])
+ *
+ * const arrayConcat = (array, value) => array.concat(value)
+ *
+ * console.log(
+ *   reduce(oddPowers(arrayConcat), [])([1, 2, 3, 4, 5]),
+ * ) // [1, 1, 1, 3, 9, 27, 5, 25, 125]
+ * ```
+ *
+ * In the case above, each item of the array of numbers returned by `powers` is called with the reducer `arrayConcat` for flattening into the final result.
+ */
+Transducer.flatMap = function transducerFlatMap(flatMapper) {
+  return curry2(reducerFlatMap, __, flatMapper)
+}
+
+/**
+ * @name Transducer.forEach
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (accumulator any, item any)=>(nextAccumulator Promise|any)
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.forEach(func function) -> forEachTransducer Transducer
+ * ```
+ */
+Transducer.forEach = function transducerForEach(func) {
+  return curry2(reducerForEach, __, func)
+}
+
+Transducer.passthrough = function transducerPassthrough(reducer) {
+  return reducer
+}
+
+module.exports = Transducer

package/Transducer.test.js

@@ -0,0 +1,117 @@
+const assert = require('assert')
+const Transducer = require('./Transducer')
+const compose = require('./compose')
+const reduce = require('./reduce')
+const transform = require('./transform')
+
+describe('Transducer', () => {
+  const ade = assert.deepEqual
+  const ase = assert.strictEqual
+  const aok = assert.ok
+
+  describe('integration: transducers from Transducer.map, Transducer.filter, Transducer.flatMap', () => {
+    const concat = (y, xi) => y.concat(xi)
+    const add = (y, xi) => y + xi
+    const isOdd = number => number % 2 == 1
+
+    it('reduce with sync transduced reducers', async () => {
+      const squareOdds = compose([
+        Transducer.filter(isOdd),
+        Transducer.map(x => x ** 2),
+      ])
+      ade(
+        reduce(squareOdds(concat), [])([1, 2, 3, 4, 5]),
+        [1, 9, 25],
+      )
+      ade(
+        reduce(squareOdds((y, xi) => y.add(xi)), new Set())([1, 2, 3, 4, 5]),
+        new Set([1, 9, 25]),
+      )
+      const appendAlphas = compose([
+        Transducer.map(x => `${x}a`),
+        Transducer.map(x => `${x}b`),
+        Transducer.map(x => `${x}c`),
+      ])
+      ase(
+        reduce(appendAlphas(add), '')('123'),
+        '1abc2abc3abc',
+      )
+      ade(
+        reduce(appendAlphas(concat), [])('123'),
+        ['1abc', '2abc', '3abc'],
+      )
+    })
+
+    it('reduce with an async transduced reducer', async () => {
+      const hosWithHey = compose([
+        Transducer.filter(async x => x === 'ho'),
+        Transducer.map(x => Promise.resolve(`${x}hey`)),
+      ])
+      const hihos = { a: 'hi', b: 'ho', c: 'hi', d: 'ho', e: 'hi', f: 'ho' }
+      aok(reduce(hosWithHey(add), '')(hihos) instanceof Promise),
+      aok(reduce(hosWithHey(concat), [])(hihos) instanceof Promise),
+      ase(
+        await reduce(hosWithHey(add), '')(hihos),
+        'hoheyhoheyhohey',
+      )
+      ade(
+        await reduce(hosWithHey(concat), [])(hihos),
+        ['hohey', 'hohey', 'hohey'],
+      )
+    })
+
+    it('flatMapping transducer', async () => {
+      const createOddMultiplesSync = compose([
+        Transducer.filter(isOdd),
+        Transducer.flatMap(number => [number * 2, number * 3]),
+      ])
+
+      ase(
+        reduce([1, 2, 3], createOddMultiplesSync(add), 0),
+        2 + 3 + 6 + 9,
+      )
+      ade(
+        reduce([1, 2, 3], createOddMultiplesSync(concat), []),
+        [2, 3, 6, 9],
+      )
+
+      const createOddMultiplesAsync = compose([
+        Transducer.filter(isOdd),
+        Transducer.flatMap(async number => [number * 2, number * 3]),
+      ])
+
+      const p1 = reduce([1, 2, 3], createOddMultiplesAsync(add), 0)
+      aok(p1 instanceof Promise)
+      const p2 = reduce([1, 2, 3], createOddMultiplesAsync(concat), [])
+      aok(p2 instanceof Promise)
+      await p1.then(result => {
+        ase(result, 2 + 3 + 6 + 9)
+      })
+      await p2.then(result => {
+        ade(result, [2, 3, 6, 9])
+      })
+    })
+
+    it('forEach transducer', async () => {
+      let sum1 = 0
+      reduce([1, 2, 3, 4, 5], Transducer.forEach(number => {
+        sum1 += number
+      })(() => {}), null)
+      assert.equal(sum1, 15)
+
+      let sum2 = 0
+      await reduce([1, 2, 3, 4, 5], Transducer.forEach(async number => {
+        sum2 += number
+      })(() => {}), null)
+      assert.equal(sum2, 15)
+    })
+
+    it('passthrough transducer', async () => {
+      assert.deepEqual(
+        transform({ a: 1, b: 2, c: 3 }, Transducer.passthrough, []),
+        [1, 2, 3],
+      )
+    })
+  })
+
+})

package/_internal/ComparisonOperator.js

@@ -0,0 +1,68 @@
+const isPromise = require('./isPromise')
+const areAnyValuesPromises = require('./areAnyValuesPromises')
+const __ = require('./placeholder')
+const curry4 = require('./curry4')
+const curryArgs4 = require('./curryArgs4')
+const spread2 = require('./spread2')
+const promiseAll = require('./promiseAll')
+const leftResolverRightResolverCompare = require('./leftResolverRightResolverCompare')
+const leftResolverRightValueCompare = require('./leftResolverRightValueCompare')
+const leftValueRightResolverCompare = require('./leftValueRightResolverCompare')
+
+// ComparisonOperator(comparator function) -> operator function
+const ComparisonOperator = comparator => function operator(...args) {
+  const right = args.pop()
+  const left = args.pop()
+  const isLeftResolver = typeof left == 'function',
+    isRightResolver = typeof right == 'function'
+
+  if (isLeftResolver && isRightResolver) {
+    if (args.length == 0) {
+      return curryArgs4(
+        leftResolverRightResolverCompare, __, comparator, left, right,
+      )
+    }
+    if (areAnyValuesPromises(args)) {
+      return promiseAll(args).then(curry4(
+        leftResolverRightResolverCompare, __, comparator, left, right,
+      ))
+    }
+    return leftResolverRightResolverCompare(args, comparator, left, right)
+  }
+
+  if (isLeftResolver) {
+    if (args.length == 0) {
+      return curryArgs4(
+        leftResolverRightValueCompare, __, comparator, left, right,
+      )
+    }
+    if (areAnyValuesPromises(args)) {
+      return promiseAll(args).then(curry4(
+        leftResolverRightValueCompare, __, comparator, left, right,
+      ))
+    }
+    return leftResolverRightValueCompare(args, comparator, left, right)
+  }
+
+  if (isRightResolver) {
+    if (args.length == 0) {
+      return curryArgs4(
+        leftValueRightResolverCompare, __, comparator, left, right,
+      )
+    }
+    if (areAnyValuesPromises(args)) {
+      return promiseAll(args).then(curry4(
+        leftValueRightResolverCompare, __, comparator, left, right,
+      ))
+    }
+    return leftValueRightResolverCompare(args, comparator, left, right)
+  }
+
+  if (isPromise(left) || isPromise(right)) {
+    return promiseAll([left, right]).then(spread2(comparator))
+  }
+  return comparator(left, right)
+}
+
+
+module.exports = ComparisonOperator

package/_internal/File.js

@@ -0,0 +1,41 @@
+const fs = require('fs')
+
+/**
+ * @name File
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * new File(path string) -> File
+ * ```
+ */
+const File = function (path) {
+  this.path = path
+  this.writeStream = fs.createWriteStream(path)
+  return this
+}
+
+/**
+ * @name File.prototype.write
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * new File(...).write(str string) -> ()
+ * ```
+ */
+File.prototype.write = function (str) {
+  this.writeStream.write(str)
+}
+
+/**
+ * @name File.prototype.rm
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * new File(...).rm() -> Promise<>
+ * ```
+ */
+File.prototype.rm = async function () {
+  await fs.promises.rm(this.path)
+}
+
+module.exports = File

package/_internal/FlatMappingAsyncIterator.js

@@ -2,7 +2,7 @@ const isPromise = require('./isPromise')
 const genericReduce = require('./genericReduce')
 const symbolAsyncIterator = require('./symbolAsyncIterator')
 const arrayPush = require('./arrayPush')
-const curryArgs3 = require('./curryArgs3')
+const curry3 = require('./curry3')
 const __ = require('./placeholder')
 const promiseRace = require('./promiseRace')
 const sleep = require('./sleep')
@@ -55,12 +55,12 @@ const FlatMappingAsyncIterator = function (asyncIterator, flatMapper) {
           } else {
             const monad = flatMapper(value)
             if (isPromise(monad)) {
-              const bufferLoading = monad.then(
-              curryArgs3(genericReduce, __, arrayPush, buffer))
+              const bufferLoading =
+                monad.then(curry3(genericReduce, __, arrayPush, buffer))
               const promise = bufferLoading.then(() => promises.delete(promise))
               promises.add(promise)
             } else {
-              const bufferLoading = genericReduce([monad], arrayPush, buffer)
+              const bufferLoading = genericReduce(monad, arrayPush, buffer)
               if (isPromise(bufferLoading)) {
                 const promise = bufferLoading.then(() => promises.delete(promise))
                 promises.add(promise)

package/_internal/FlatMappingIterator.js

@@ -31,7 +31,7 @@ const FlatMappingIterator = function (iterator, flatMapper) {
         return iteration
       }
       const monadAsArray = genericReduce(
-        [flatMapper(iteration.value)],
+        flatMapper(iteration.value),
         arrayPush,
         []) // this will always have at least one item
       if (monadAsArray.length > 1) {