rubico 2.3.0 → 2.3.2

package/AggregateReducer.d.ts

@@ -0,0 +1,10 @@
+export = AggregateReducer;
+/**
+ * @name AggregateReducer
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * AggregateReducer(reducers Array<reducer function>) -> aggregateReducer function
+ * ```
+ */
+declare function AggregateReducer(reducers: any): any;

package/README.md

@@ -250,3 +250,12 @@ rubico is [MIT Licensed](https://github.com/a-synchronous/rubico/blob/master/LIC
  * minimum Firefox version: 57
  * minimum Edge version: 79
  * minimum Safari version: 11.1
+
+# Awesome Resources
+[rubico simplifies asynchronous code](https://dev.to/richytong/rubico-a-synchrnous-functional-syntax-motivation-20hf)
+<br>
+[Practical Functional Programming in JavaScript - Error Handling](https://dev.to/richytong/practical-functional-programming-in-javascript-error-handling-8g5)
+<br>
+[Practical Functional Programming in JavaScript - Techniques for Composing Data](https://dev.to/richytong/practical-functional-programming-in-javascript-techniques-for-composing-data-c39)
+<br>
+[Practical Functional Programming in JavaScript - Side Effects and Purity](https://dev.to/richytong/practical-functional-programming-in-javascript-side-effects-and-purity-revised-420h)

package/Transducer.d.ts

@@ -0,0 +1,231 @@
+/**
+ * @name Transducer.map
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ *   indexOrKey? number|string,
+ *   collection? Foldable,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.map(mapperFunc function) -> mappingTransducer Transducer
+ * ```
+ *
+ * @description
+ * Creates a mapping transducer. Items in the final reducing operation are transformed by the mapper function. It is possible to use an asynchronous mapper, however the reducing operation must support asynchronous execution. This library provides such implementations as [reduce](/docs/reduce) and [transform](/docs/transform).
+ *
+ * ```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(
+ *   reduce([1, 2, 3, 4, 5], squareConcatReducer, [])
+ * ) // [1, 4, 9, 16, 25]
+ *
+ * // the same squareConcatReducer is consumable with vanilla JavaScript
+ * console.log(
+ *   [1, 2, 3, 4, 5].reduce(squareConcatReducer, [])
+ * ) // [1, 4, 9, 16, 25]
+ *
+ * // concat is implicit when transforming into arrays
+ * console.log(
+ *   transform([1, 2, 3, 4, 5], Transducer.map(square), [])
+ * ) // [1, 4, 9, 16, 25]
+ * ```
+ *
+ * Read more on transducers [here](/blog/transducers-crash-course-rubico-v2).
+ */
+export function map(mapper: any): (arg0: any) => any;
+/**
+ * @name Transducer.filter
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ *   indexOrKey? number|string,
+ *   collection? Foldable,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.filter(predicate function) -> filteringTransducer Transducer
+ * ```
+ *
+ * @description
+ * Creates a filtering transducer. A filtering reducer skips items of reducing operation if they test falsy by the predicate. It is possible to use an asynchronous predicate, however the reducing operation must support asynchronous execution. This library provides such implementations as [reduce](/docs/reduce) and [transform](/docs/transform).
+ *
+ * ```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]
+ * ```
+ */
+export function filter(predicate: any): (arg0: any) => any;
+/**
+ * @name Transducer.flatMap
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ *   indexOrKey? number|string,
+ *   collection? Foldable,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.flatMap(flatMapper) -> flatMappingTransducer Transducer
+ * ```
+ *
+ * @description
+ * Creates a flatMapping transducer. A flatMapping transducer applies the flatMapping function to each item of the reducing operation, concatenating the results of the flatMapper execution into the final result. It is possible to use an asynchronous flatMapper, however the reducing operation must support asynchronous execution. This library provides such implementations as [reduce](/docs/reduce) and [transform](/docs/transform).
+ *
+ * ```javascript [playground]
+ * const powers = number => [number, number ** 2, number ** 3]
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ *
+ * console.log(
+ *   transform(numbers, Transducer.flatMap(powers), [])
+ * ) // [1, 1, 1, 2, 4, 8, 3, 9, 27, 4, 16, 64, 5, 25, 125]
+ * ```
+ *
+ * Read more on transducers [here](/blog/transducers-crash-course-rubico-v2).
+ */
+export function flatMap(flatMapper: any): (arg0: any) => any;
+/**
+ * @name Transducer.forEach
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ *   indexOrKey? number|string,
+ *   collection? Foldable,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.forEach(func function) -> forEachTransducer Transducer
+ * ```
+ *
+ * @description
+ * Creates an effectful pasthrough transducer. The effectful passthrough transducer applies the effectful function to each item of the reducing operation, leaving the reducing operation unchanged. It is possible to use an asynchronous effectful function, however the reducing operation must support asynchronous execution. This library provides such implementations as [reduce](/docs/reduce) and [transform](/docs/transform).
+ *
+ * ```javascript [playground]
+ * const numbers = [1, 2, 3, 4, 5]
+ * transform(numbers, compose([
+ *   Transducer.map(number => number ** 2),
+ *   Transducer.forEach(console.log), // 1 4 9 16 25
+ * ]), null)
+ * ```
+ */
+export function forEach(func: any): (arg0: any) => any;
+/**
+ * @name Transducer.passthrough
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ *   indexOrKey? number|string,
+ *   collection? Foldable,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.passthrough(func function) -> passthroughTransducer Transducer
+ * ```
+ *
+ * @description
+ * Creates a pasthrough transducer. The passthrough transducer passes each item of the reducing operation through, leaving the reducing operation unchanged.
+ *
+ * ```javascript [playground]
+ * const createAsyncNumbers = async function* () {
+ *   let number = 0
+ *   while (number < 10) {
+ *     yield number
+ *     number += 1
+ *   }
+ * }
+ *
+ * transform(createAsyncNumbers(), Transducer.passthrough, [])
+ *   .then(console.log) // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ * ```
+ */
+export function passthrough(reducer: any): any;
+/**
+ * @name Transducer.tryCatch
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   item any,
+ *   indexOrKey? number|string,
+ *   collection? Foldable,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ *
+ * Transducer.tryCatch(
+ *   transducerTryer Transducer,
+ *   catcher (error Error, item any)=>Promise|any,
+ * ) -> tryCatchTransducer Transducer
+ * ```
+ *
+ * @description
+ * Creates an error handling transducer. The error handling transducer wraps a transducer and catches any errors thrown by the transducer with the catcher function. The catcher function is provided the error as well as the original item (before any processing by the transducer) for which the error was thrown. It is possible for either the transducer or the catcher to be asynchronous, however the reducing operation must support asynchronous execution. This library provides such implementations as [reduce](/docs/reduce) and [transform](/docs/transform).
+ *
+ * ```javascript [playground]
+ * const db = new Map()
+ * db.set('a', { id: 'a', name: 'George' })
+ * db.set('b', { id: 'b', name: 'Jane' })
+ * db.set('c', { id: 'c', name: 'Jill' })
+ * db.set('e', { id: 'e', name: 'Jim' })
+ *
+ * const userIds = ['a', 'b', 'c', 'd', 'e']
+ *
+ * transform(userIds, Transducer.tryCatch(compose([
+ *   Transducer.map(async userId => {
+ *     if (db.has(userId)) {
+ *       return db.get(userId)
+ *     }
+ *     throw new Error(`user ${userId} not found`)
+ *   }),
+ *
+ *   Transducer.forEach(user => {
+ *     console.log('Found', user.name)
+ *   })
+ * ]), (error, userId) => {
+ *   console.error(error)
+ *   console.log('userId in catcher:', userId)
+ *   // original userId for which the error was thrown is provided
+ * }), null)
+ * ```
+
+ */
+export function tryCatch(transducerTryer: any, catcher: any): (arg0: any) => any;

package/__.d.ts

@@ -0,0 +1,2 @@
+export = __;
+import __ = require("./_internal/placeholder");

package/_internal/EmptyMap.d.ts

@@ -0,0 +1,2 @@
+export = EmptyMap;
+declare function EmptyMap(): any;

package/_internal/arrayFind.d.ts

@@ -0,0 +1,15 @@
+export = arrayFind;
+/**
+ * @name arrayFind
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * var T any,
+ *   array Array<T>,
+ *   predicate T=>Promise|boolean,
+ *   result Promise|T|undefined
+ *
+ * arrayFind(array, predicate) -> result
+ * ```
+ */
+declare function arrayFind(array: any, predicate: any): any;

package/_internal/arrayMapSeries.js

@@ -13,7 +13,7 @@ const objectSet = require('./objectSet')
  * arrayMapSeriesAsync<
  *   T any,
  *   array Array<T>,
- *   mapper T=>Promise|any,
+ *   mapper (T,index)=>Promise|any,
  *   result Array,
  *   index number,
  * >(array, mapper, result Array, index) -> Promise|result
@@ -27,7 +27,7 @@ const arrayMapSeriesAsync = async function (
 ) {
   const arrayLength = array.length
   while (++index < arrayLength) {
-    const resultItem = mapper(array[index])
+    const resultItem = mapper(array[index], index)
     result[index] = isPromise(resultItem) ? await resultItem : resultItem
   }
   return result
@@ -41,7 +41,7 @@ const arrayMapSeriesAsync = async function (
  * arrayMapSeries<
  *   T any,
  *   array Array<T>,
- *   mapper T=>Promise|any,
+ *   mapper (T,index)=>Promise|any,
  * >(array, mapper) -> mappedInSeries Promise|Array
  * ```
  *
@@ -54,7 +54,7 @@ const arrayMapSeries = function (array, mapper) {
   let index = -1
 
   while (++index < arrayLength) {
-    const resultItem = mapper(array[index])
+    const resultItem = mapper(array[index], index)
     if (isPromise(resultItem)) {
       return resultItem.then(funcConcat(
         curry3(objectSet, result, index, __),

package/_internal/asyncIteratorFind.d.ts

@@ -0,0 +1,12 @@
+export = asyncIteratorFind;
+/**
+ * @name asyncIteratorFind
+ *
+ * @synopsis
+ * var T any,
+ *   asyncIterator AsyncIterator<T>,
+ *   predicate T=>Promise|boolean
+ *
+ * asyncIteratorFind(asyncIterator, predicate) -> Promise|T|undefined
+ */
+declare function asyncIteratorFind(asyncIterator: any, predicate: any): Promise<any>;

package/_internal/findAllFilePaths.js

@@ -1,5 +1,4 @@
 const fs = require('fs')
-const pathResolve = require('./pathResolve')
 
 // findAllFilePaths(path string) -> filePaths Promise<Array<string>>
 const findAllFilePaths = async function (path) {
@@ -10,10 +9,9 @@ const findAllFilePaths = async function (path) {
   const result = []
   for (const file of files) {
     if (file.isDirectory()) {
-      const filePaths = await findAllFilePaths(pathResolve(path, file.name))
-      result.push(...filePaths)
+      continue
     } else {
-      result.push(pathResolve(path, file.name))
+      result.push(`${file.path}/${file.name}`)
     }
   }
   return result

package/_internal/iteratorFind.d.ts

@@ -0,0 +1,12 @@
+export = iteratorFind;
+/**
+ * @name iteratorFind
+ *
+ * @synopsis
+ * var T any,
+ *   iterator Iterator<T>,
+ *   predicate T=>Promise|boolean
+ *
+ * iteratorFind(iterator, predicate) -> Promise|T|undefined
+ */
+declare function iteratorFind(iterator: any, predicate: any): any;

package/_internal/thunkify5.d.ts

@@ -0,0 +1,20 @@
+export = thunkify5;
+/**
+ * @name thunkify5
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * thunkify5<
+ *   arg0 any,
+ *   arg1 any,
+ *   arg2 any,
+ *   arg3 any,
+ *   arg4 any,
+ *   func (arg0, arg1, arg2, arg3, arg4)=>any,
+ * >(func, arg0, arg1, arg2, arg3, arg4) -> thunk ()=>func(arg0, arg1, arg2, arg3, arg4)
+ * ```
+ *
+ * @description
+ * Create a thunk from a function and five arguments.
+ */
+declare function thunkify5(func: any, arg0: any, arg1: any, arg2: any, arg3: any, arg4: any): () => any;

package/_internal/timeInLoop.d.ts

@@ -0,0 +1,25 @@
+export = timeInLoop;
+/**
+ * @name timeInLoop
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * timeInLoop(description string, loopCount number, fn function, options? {
+ *   silent?: boolean,
+ * }) -> undefined
+ * ```
+ *
+ * @description
+ * Logs the amount of time required for a function to run a certain number of times
+ *
+ * ```js
+ * timeInLoop('hello', 1e6, () => 'hello') // hello: 1e+6: 3.474ms
+ * ```
+ *
+ * Reference: https://gist.github.com/funfunction/91b5876a5f562e1e352aed0fcabc3858
+ */
+declare function timeInLoop(description: any, loopCount: any, fn: any, options?: {}): {
+    description: any;
+    loopCount: any;
+    duration: number;
+};

package/_internal/timeInLoopAsync.d.ts

@@ -0,0 +1,23 @@
+export = timeInLoopAsync;
+/**
+ * @name timeInLoopAsync
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * timeInLoop.async(description string, loopCount number, fn function, options? {
+ *   silent?: boolean,
+ * }) -> undefined
+ * ```
+ *
+ * @description
+ * Like timeInLoop, but every call is awaited
+ *
+ * ```js
+ * timeInLoop.async('async hello', 1e6, async () => 'hello') // async hello: 1e+6: 116.006ms
+ * ```
+ */
+declare function timeInLoopAsync(description: any, loopCount: any, fn: any, options?: {}): Promise<{
+    description: any;
+    loopCount: any;
+    duration: number;
+}>;

package/all.d.ts

@@ -0,0 +1,100 @@
+export = all;
+/**
+ * @name all
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * all(...args, funcsArray Array<function>) -> result Promise|Array
+ *
+ * all(funcsArray Array<function>)(...args) -> result Promise|Array
+ *
+ * all(...args, funcsObject Object<function>) -> result Promise|Object
+ *
+ * all(funcsObject Object<function>)(...args) -> result Promise|Object
+ * ```
+ *
+ * @description
+ * Function executor and composer. Accepts either an array of functions or an object of functions as the values. Calls each function of the provided array or object in parallel with the provided arguments. Returns either an array or object of the results of the function executions.
+ *
+ * ```javascript [playground]
+ * const createArrayOfGreetingsFor = all([
+ *   name => `Hi ${name}`,
+ *   name => `Hey ${name}`,
+ *   name => `Hello ${name}`,
+ * ])
+ *
+ * const arrayOfGreetingsForFred = createArrayOfGreetingsFor('Fred')
+ *
+ * console.log(arrayOfGreetingsForFred)
+ * // ['Hi Fred', 'Hey Fred', 'Hello Fred']
+ *
+ * const createObjectOfGreetingsFor = all({
+ *   hi: name => `Hi ${name}`,
+ *   hey: name => `Hey ${name}`,
+ *   hello: name => `Hello ${name}`,
+ * })
+ *
+ * const objectOfGreetingsForJane = createObjectOfGreetingsFor('Jane')
+ *
+ * console.log(objectOfGreetingsForJane)
+ * // { hi: 'Hi Jane', hey: 'Hey Jane', hello: 'Hello Jane' }
+ * ```
+ *
+ * `all` can simultaneously compose objects and handle promises.
+ *
+ * ```javascript [playground]
+ * const identity = value => value
+ *
+ * const userbase = new Map()
+ * userbase.set('1', { _id: 1, name: 'George' })
+ *
+ * const getUserByID = async id => userbase.get(id)
+ *
+ * const getAndLogUserById = pipe([
+ *   all({
+ *     id: identity,
+ *     user: getUserByID,
+ *   }),
+ *   tap(({ id, user }) => {
+ *     console.log(`Got user ${JSON.stringify(user)} by id ${id}`)
+ *   }),
+ * ])
+ *
+ * getAndLogUserById('1') // Got user {"_id":1,"name":"George"} by id 1
+ * ```
+ *
+ * @execution concurrent
+ */
+declare function all(...args: any[]): any;
+declare namespace all {
+    /**
+     * @name all.series
+     *
+     * @synopsis
+     * ```coffeescript [specscript]
+     * all.series(...args, funcsArray Array<function>) -> result Promise|Array
+     *
+     * all.series(funcsArray Array<function>)(...args) -> result Promise|Array
+     * ```
+     *
+     * @description
+     * `all` with serial execution.
+     *
+     * ```javascript [playground]
+     * const sleep = ms => () => new Promise(resolve => setTimeout(resolve, ms))
+     *
+     * all.series([
+     *   greeting => console.log(greeting + ' world'),
+     *   sleep(1000),
+     *   greeting => console.log(greeting + ' mom'),
+     *   sleep(1000),
+     *   greeting => console.log(greeting + ' goodbye'),
+     * ])('hello') // hello world
+     *             // hello mom
+     *             // hello goodbye
+     * ```
+     *
+     * @execution series
+     */
+    function series(...args: any[]): any;
+}

package/always.d.ts

@@ -0,0 +1,2 @@
+export = always;
+import always = require("./_internal/always");

package/and.d.ts

@@ -0,0 +1,45 @@
+export = and;
+/**
+ * @name and
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * and(values Array<boolean>) -> result boolean
+ *
+ * and(...args, predicatesOrValues Array<function|boolean>) -> Promise|boolean
+ *
+ * and(predicatesOrValues Array<function|boolean>)(...args) -> Promise|boolean
+ * ```
+ *
+ * @description
+ * Tests an array of boolean values, returning true if all boolean values are truthy.
+ *
+ * ```javascript [playground]
+ * const oneIsLessThanThree = 1 < 3
+ * const twoIsGreaterThanOne = 2 > 1
+ * const threeIsEqualToThree = 3 === 3
+ *
+ * console.log(
+ *   and([oneIsLessThanThree, twoIsGreaterThanOne, threeIsEqualToThree]),
+ * ) // true
+ * ```
+ *
+ * If any values in the array are synchronous or asynchronous predicate functions, `and` takes another argument to test concurrently against the predicate functions, returning true if all array values and resolved values from the predicates are truthy.
+ *
+ * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * const isPositive = number => number > 0
+ *
+ * const isLessThan3 = number => number < 3
+ *
+ * console.log(
+ *   and([isOdd, isPositive, isLessThan3])(1),
+ * ) // true
+ * ```
+ *
+ * @execution series
+ *
+ * @note ...args slows down here by an order of magnitude
+ */
+declare function and(...args: any[]): any;

package/assign.d.ts

@@ -0,0 +1,46 @@
+export = assign;
+/**
+ * @name assign
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * assign(object Object, resolvers Object<function>) -> result Promise|Object
+ *
+ * assign(resolvers Object<function>)(object Object) -> result Promise|Object
+ * ```
+ *
+ * @description
+ * Function executor and composer. Accepts an object of resolver functions and an argument object. Creates a result object from the argument object, evaluates each resolver with the argument object, and assigns to the result object the evaluations at the corresponding resolver keys.
+ *
+ * ```javascript [playground]
+ * const assignSquaredAndCubed = assign({
+ *   squared: ({ number }) => number ** 2,
+ *   cubed: ({ number }) => number ** 3,
+ * })
+ *
+ * console.log(assignSquaredAndCubed({ number: 2 }))
+ * // { number: 2, squared: 4, cubed: 8 }
+ *
+ * console.log(assignSquaredAndCubed({ number: 3 }))
+ * // { number: 3, squared: 9, cubed: 27 }
+ * ```
+ *
+ * Any of the resolvers may be asynchronous and return Promises.
+ *
+ * ```javascript [playground]
+ * const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+ *
+ * const asyncAssignTotal = assign({
+ *   async total({ numbers }) {
+ *     await sleep(500)
+ *     return numbers.reduce((a, b) => a + b)
+ *   },
+ * })
+ *
+ * asyncAssignTotal({ numbers: [1, 2, 3, 4, 5] }).then(console.log)
+ * // { numbers: [1, 2, 3, 4, 5], total: 15 }
+ * ```
+ *
+ * @execution concurrent
+ */
+declare function assign(arg0: any, arg1: any): any;

package/compose.d.ts

@@ -0,0 +1,25 @@
+export = compose;
+/**
+ * @name compose
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * compose(funcs Array<function>)(...args) -> result Promise|any
+ *
+ * compose(...args, funcs Array<function>) -> result Promise|any
+ * ```
+ *
+ * @description
+ * Creates a function composition from an array of functions, where each function passes its return value as a single argument to the previous function until all functions have executed. The last function is called with the arguments to the composition, while the result of a function composition is the return value of its first function. If any function of the composition is asynchronous, the result of the execution is a Promise. `compose` is effectively `pipe` in reverse.
+ *
+ * ```javascript [playground]
+ * const f = number => number * 2
+ *
+ * const g = number => number + 3
+ *
+ * console.log(
+ *   compose(5, [f, g]),
+ * ) // 16
+ * ```
+ */
+declare function compose(...args: any[]): any;