rubico 2.3.0 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rubico",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "[a]synchronous functional programming",
   "author": "Richard Tong",
   "license": "MIT",
@@ -16,41 +16,77 @@
     "x",
     "monad",
     "index.js",
+    "index.d.ts",
     "es.js",
+    "es.d.ts",
     "global.js",
+    "global.d.ts",
     "pipe.js",
+    "pipe.d.ts",
     "compose.js",
+    "compose.d.ts",
     "tap.js",
+    "tap.d.ts",
     "forEach.js",
+    "forEach.d.ts",
     "switchCase.js",
+    "switchCase.d.ts",
     "tryCatch.js",
+    "tryCatch.d.ts",
     "all.js",
+    "all.d.ts",
     "assign.js",
+    "assign.d.ts",
     "get.js",
+    "get.d.ts",
     "set.js",
+    "set.d.ts",
     "pick.js",
+    "pick.d.ts",
     "omit.js",
+    "omit.d.ts",
     "map.js",
+    "map.d.ts",
     "filter.js",
+    "filter.d.ts",
     "flatMap.js",
+    "flatMap.d.ts",
     "reduce.js",
+    "reduce.d.ts",
     "transform.js",
+    "transform.d.ts",
     "and.js",
+    "and.d.ts",
     "or.js",
+    "or.d.ts",
     "not.js",
+    "not.d.ts",
     "some.js",
+    "some.d.ts",
     "every.js",
+    "every.d.ts",
     "eq.js",
+    "eq.d.ts",
     "gt.js",
+    "gt.d.ts",
     "lt.js",
+    "lt.d.ts",
     "gte.js",
+    "gte.d.ts",
     "lte.js",
+    "lte.d.ts",
     "thunkify.js",
+    "thunkify.d.ts",
     "always.js",
+    "always.d.ts",
     "curry.js",
+    "curry.d.ts",
     "__.js",
+    "__.d.ts",
     "AggregateReducer.js",
-    "Transducer.js"
+    "AggregateReducer.d.ts",
+    "Transducer.js",
+    "Transducer.d.ts"
   ],
   "keywords": [
     "function-composition",
@@ -78,6 +114,7 @@
     "async": "^3.2.4",
     "bluebird": "^3.7.2",
     "codecov": "^3.7.1",
+    "del-cli": "^5.0.0",
     "eslint": "^8.4.1",
     "fantasy-land": "^4.1.0",
     "lodash": "^4.17.21",
@@ -93,7 +130,7 @@
     "test": "mocha test.js *.test.js */**.test.js",
     "test-coverage": "nyc mocha test.js x/*.test.js monad/*.test.js",
     "lint": "eslint .",
-    "build": "./build",
-    "dts": "tsc"
+    "build": "npm run dts && ./build",
+    "dts": "del *.d.ts _internal/*.d.ts x/*.d.ts && tsc"
   }
 }

package/pick.d.ts

@@ -0,0 +1,43 @@
+export = pick;
+/**
+ * @name pick
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * pick(object Object, keys Array<string>) -> result Object
+ *
+ * pick(keys Array<string>)(object Object) -> result Object
+ * ```
+ *
+ * @description
+ * 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({ goodbye: 1, world: 2 }, ['hello', 'world']),
+ * ) // { world: 2 }
+ * ```
+ *
+ * `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 }
+ * ])
+ * ```
+ */
+declare function pick(arg0: any, arg1: any): any;

package/pipe.d.ts

@@ -0,0 +1,49 @@
+export = pipe;
+/**
+ * @name pipe
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * pipe(funcs Array<function>)(...args) -> result Promise|any
+ *
+ * pipe(...args, funcs Array<function>) -> result Promise|any
+ * ```
+ *
+ * @description
+ * 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]
+ * const syncAdd123 = pipe([
+ *   number => number + 1,
+ *   number => number + 2,
+ *   number => number + 3,
+ * ])
+ *
+ * console.log(syncAdd123(5)) // 11
+ *
+ * const asyncAdd123 = pipe([
+ *   async number => number + 1,
+ *   async number => number + 2,
+ *   async number => number + 3,
+ * ])
+ *
+ * asyncAdd123(5).then(console.log) // 11
+ * ```
+ *
+ * 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, [
+ *   Array.of,
+ *   map(number => number * 3),
+ *   console.log, // [3, 6, 9]
+ * ])
+ * ```
+ *
+ * @execution series
+ *
+ * @transducing
+ *
+ * @since 1.6.0
+ */
+declare function pipe(...args: any[]): any;

package/reduce.d.ts

@@ -0,0 +1,166 @@
+export = reduce;
+/**
+ * @name reduce
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Foldable = Array|Object|Map|Iterator|AsyncIterator
+ *
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ *   indexOrKey? number|string,
+ *   collection? Foldable,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Resolver = (collection Foldable)=>Promise|any
+ *
+ * reduce(
+ *   collection Foldable,
+ *   reducer Reducer,
+ *   initialValue? Resolver|any
+ * ) -> result Promise|any
+ *
+ * reduce(
+ *   reducer Reducer,
+ *   initialValue? Resolver|any
+ * )(collection Foldable) -> result Promise|any
+ * ```
+ *
+ * @description
+ * Transforms a collection based on a reducer function and optional initial value. In a reducing operation, the result is defined in the beginning as either the initial value if supplied or the first item of the collection. The reducing operation then iterates through the remaining items in the collection, executing the reducer at each iteration to return the result to be used in the next iteration. The final result is the result of the execution of the reducer at the last item of the iteration. `reduce` accepts the following collections:
+ *
+ *  * `Array`
+ *  * `Object`
+ *  * `Set`
+ *  * `Map`
+ *  * `Iterator`/`Generator`
+ *  * `AsyncIterator`/`AsyncGenerator`
+ *
+ * For arrays (type `Array`), `reduce` executes the reducer function for each item of the array in order, returning a new result at each execution to be used in the next execution. On each iteration, the reducer is passed the accumulator, the item of the iteration, the index of the item in the array, and a reference to the original array.
+ *
+ * ```javascript [playground]
+ * const max = (a, b) => a > b ? a : b
+ *
+ * console.log(
+ *   reduce([1, 3, 5, 4, 2], max)
+ * ) // 5
+ *
+ * console.log(
+ *   reduce(max)([1, 3, 5, 4, 2])
+ * ) // 5
+ * ```
+ *
+ * If an optional initial value is provided, the result starts as the provided initial value rather than the first item of the collection.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * console.log(reduce([1, 2, 3, 4, 5], add, 0)) // 15
+ * console.log(reduce(add, 0)([1, 2, 3, 4, 5])) // 15
+ * ```
+ *
+ * If the initialization parameter is a function, it is treated as a resolver and called with the arguments to resolve the initial value.
+ *
+ * ```javascript [playground]
+ * const concatSquares = (array, value) => array.concat(value ** 2)
+ *
+ * const contrivedInitializer = array => [`initial length ${array.length}`]
+ *
+ * const array = [1, 2, 3, 4, 5]
+ *
+ * console.log(reduce(concatSquares, contrivedInitializer)(array))
+ * // ['initial length 5', 1, 4, 9, 16, 25]
+ * console.log(reduce(array, concatSquares, contrivedInitializer))
+ * // ['initial length 5', 1, 4, 9, 16, 25]
+ * ```
+ *
+ * For objects (type `Object`), `reduce` executes the reducer function for each value of the object. On each iteration, the reducer is passed the accumulator, the object value, the key of the object value, and a reference to the original object.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+ *
+ * console.log(
+ *   reduce(obj, add)
+ * ) // 15
+ *
+ * console.log(
+ *   reduce(add)(obj)
+ * ) // 15
+ * ```
+ *
+ * For sets (type `Set`), `reduce` executes the reducer function for each item of the set. On each iteration, the reducer is passed the accumulator and item of the set.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * const set = new Set([1, 2, 3, 4, 5])
+ *
+ * console.log(
+ *   reduce(set, add)
+ * ) // 15
+ *
+ * console.log(
+ *   reduce(add)(set)
+ * ) // 15
+ * ```
+ *
+ * For maps (type `Map`), `reduce` executes the reducer function for each value of each entry of the map. On each iteration, the reducer is passed the accumulator, the map item, the key of the map item, and a reference to the original map.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * const m = new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4], ['e', 5]])
+ *
+ * console.log(
+ *   reduce(m, add)
+ * ) // 15
+ *
+ * console.log(
+ *   reduce(add)(m)
+ * ) // 15
+ * ```
+ *
+ * For iterators (type `Iterator`) and generators (type `Generator`), `reduce` executes the reducer function for each value of the iterator/generator. On each iteration, the reducer is passed the accumulator and the item of the iteration. The iterator/generator is consumed in the process.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * const generate12345 = function* () {
+ *   yield 1; yield 2; yield 3; yield 4; yield 5
+ * }
+ *
+ * console.log(
+ *   reduce(generate12345(), add)
+ * ) // 15
+ *
+ * console.log(
+ *   reduce(add)(generate12345())
+ * ) // 15
+ * ```
+ *
+ * For asyncIterators (type `AsyncIterator`) and asyncGenerators (type `AsyncGenerator`), `reduce` executes the reducer function for each value of the asyncIterator/asyncGenerator. On each iteration, the reducer is passed the accumulator and the item of the async iteration. The asyncIterator/asyncGenerator is consumed in the process.
+ *
+ * ```javascript [playground]
+ * const asyncAdd = async (a, b) => a + b
+ *
+ * const asyncGenerate12345 = async function* () {
+ *   yield 1; yield 2; yield 3; yield 4; yield 5
+ * }
+ *
+ * reduce(asyncGenerate12345(), asyncAdd).then(console.log) // 15
+ *
+ * reduce(asyncAdd)(asyncGenerate12345()).then(console.log) // 15
+ * ```
+ *
+ * @execution series
+ *
+ * @transducing
+ *
+ * @TODO readerReduce
+ *
+ * @TODO reduce.concurrent
+ */
+declare function reduce(...args: any[]): any;

package/set.d.ts

@@ -0,0 +1,61 @@
+export = set;
+/**
+ * @name set
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * set(
+ *   object Promise|Object,
+ *   path string|Array<string|number>,
+ *   value function|any,
+ * ) -> result Promise|Object
+ *
+ * set(
+ *   path string|Array<string|number>,
+ *   value function|any,
+ * )(object Object) -> result Promise|Object
+ * ```
+ *
+ * @description
+ * Sets a property on a new object shallow cloned from the argument object given a path denoted by a string, number, or an array of string or numbers.
+ *
+ * `set` 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]
+ * console.log(set({ b: 2 }, 'a', 1)) // { a: 1, b: 2 }
+ *
+ * const nestedAC2 = { a: { c: 2 } }
+ *
+ * console.log(set(nestedAC2, 'a.b', 1)) // { a : { b: 1, c: 2 }}
+ *
+ * const nestedA0BC3 = { a: [{ b: { c: 3 } }] }
+ *
+ * console.log(set(nestedA0BC3, 'a[0].b.c', 4)) // { a: [{ b: { c: 4 } }] }
+ * ```
+ *
+ * The property value may be a function, in which case it is treated as a resolver and provided the argument object to resolve the value to set.
+ *
+ * ```javascript [playground]
+ * const myObj = { a: 1 }
+ *
+ * const myNewObj = set('b', obj => obj.a + 2)(myObj)
+ *
+ * console.log(myNewObj) // { a: 1, b: 3 }
+ * ```
+ *
+ * `set` supports a tacit API for composability.
+ *
+ * ```javascript [playground]
+ * pipe({ a: 1 }, [
+ *   set('b', 2),
+ *   console.log, // { a: 1, b: 2 }
+ * ])
+ * ```
+ *
+ * @since 1.7.0
+ */
+declare function set(arg0: any, arg1: any, arg2: any): any;

package/some.d.ts

@@ -0,0 +1,65 @@
+export = some;
+/**
+ * @name some
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * type Foldable = Array|Iterable|AsyncIterable|{ reduce: function }|Object
+ *
+ * some(collection Foldable, predicate function) -> Promise|boolean
+ *
+ * some(predicate function)(collection Foldable) -> Promise|boolean
+ * ```
+ *
+ * @description
+ * Test a predicate concurrently across all items of a collection, returning true if any executions return truthy.
+ *
+ * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * console.log(
+ *   some([1, 2, 3, 4, 5], isOdd),
+ * ) // true
+ * ```
+ *
+ * The collection can be any iterable, async iterable, or object values iterable collection. Below is an example of `some` accepting an async generator as the collection.
+ *
+ * ```javascript [playground]
+ * const toTodosUrl = id => 'https://jsonplaceholder.typicode.com/todos/' + id
+ *
+ * const fetchedToJson = fetched => fetched.json()
+ *
+ * const fetchTodo = pipe([
+ *   toTodosUrl,
+ *   fetch,
+ *   fetchedToJson,
+ * ])
+ *
+ * const todoIDsGenerator = async function* () {
+ *   yield 1; yield 2; yield 3; yield 4; yield 5
+ * }
+ *
+ * const promise = some(todoIDsGenerator(), async id => {
+ *   const todo = await fetchTodo(id)
+ *   return todo.title.startsWith('fugiat')
+ * })
+ *
+ * promise.then(console.log) // true
+ * ```
+ *
+ * `some` supports a tacit API for composability.
+ *
+ * ```javascript [playground]
+ * pipe([1, 2, 3], [
+ *   some(number => number < 5),
+ *   console.log, // true
+ * ])
+ * ```
+ *
+ * @execution concurrent
+ *
+ * @muxing
+ *
+ * @related or
+ */
+declare function some(...args: any[]): any;

package/switchCase.d.ts

@@ -0,0 +1,76 @@
+export = switchCase;
+/**
+ * @name switchCase
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * switchCase(conditionalValues Array<boolean|any>) -> Promise|any
+ *
+ * switchCase(
+ *   ...args,
+ *   conditionalFuncsOrValues Array<function|boolean|any>
+ * ) -> Promise|any
+ *
+ * switchCase(
+ *   conditionalFuncsOrValues Array<function|boolean|any>
+ * )(...args) -> Promise|any
+ * ```
+ *
+ * @description
+ * Functional equivalent to the [Conditional (ternary) operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator). Accepts an array of conditional functions that specifies cases as pairings of `predicate` and `resolver` functions with the exception of the last, default resolver. All functions are provided with the same arguments and executed in series. The result of a `switchCase` operation is either the result of the execution the last default resolver, or the result of the execution of the first resolver where the associated predicate tested true.
+ *
+ * ```javascript [playground]
+ * const fruitIsYellow = fruit => fruit.color == 'yellow'
+ *
+ * console.log(
+ *   switchCase({ name: 'plantain', color: 'yellow' }, [
+ *     fruitIsYellow,
+ *     fruit => fruit.name + ' is possibly a banana',
+ *     fruit => fruit.name + ' is probably not a banana',
+ *   ])
+ * ) // plantain is possibly a banana
+ * ```
+ *
+ * For composability `switchCase` supports a tacit API.
+ *
+ * ```javascript [playground]
+ * const fruitIsYellow = fruit => fruit.color == 'yellow'
+ *
+ * const fruitsGuesser = switchCase([
+ *   fruitIsYellow,
+ *   fruit => fruit.name + ' is possibly a banana',
+ *   fruit => fruit.name + ' is probably not a banana',
+ * ])
+ *
+ * console.log(fruitsGuesser({ name: 'plantain', color: 'yellow' }))
+ * // plantain is possibly a banana
+ *
+ * console.log(fruitsGuesser({ name: 'apple', color: 'red' }))
+ * // apple is probably not a banana
+ * ```
+ *
+ * Any function can be replaced with a nonfunction (object or primitive) value to be used directly in the operation.
+ *
+ * ```javascript [playground]
+ * switchCase([
+ *   async function asyncIdentity(value) {
+ *     return value
+ *   },
+ *   'something',
+ *   'default',
+ * ])(false).then(console.log) // default
+ * ```
+ *
+ * If every item in the conditional array is a nonfunction value, `switchCase` executes eagerly.
+ *
+ * ```javascript [playground]
+ * const age = 26
+ *
+ * const myDrink = switchCase([age >= 21, 'Beer', 'Juice'])
+ *
+ * console.log(myDrink) // Beer
+ * ```
+ *
+ * @execution series
+ */
+declare function switchCase(...args: any[]): any;

package/tap.d.ts

@@ -0,0 +1,53 @@
+export = tap;
+/**
+ * @name tap
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * tap(...args, func function) -> Promise|args[0]
+ * tap(func function)(...args) -> Promise|args[0]
+ * ```
+ *
+ * @description
+ * Call a function with any number of arguments, returning the first argument. Promises created by the tapper are resolved before returning the value.
+ *
+ * ```javascript [playground]
+ * const pipeline = pipe([
+ *   tap(value => console.log(value)),
+ *   tap(value => console.log(value + 'bar')),
+ *   tap(value => console.log(value + 'barbaz')),
+ * ])
+ *
+ * pipeline('foo') // 'foo'
+ *                 // 'foobar'
+ *                 // 'foobarbaz'
+ * ```
+ */
+declare function tap(...args: any[]): any;
+declare namespace tap {
+    /**
+     * @name tap.if
+     *
+     * @synopsis
+     * ```coffeescript [specscript]
+     * tap.if(predicate function, func function)(...args) -> Promise|args[0]
+     * ```
+     *
+     * @description
+     * A version of `tap` that accepts a predicate function (a function that returns a boolean value) before the function to execute. Only executes the function if the predicate function tests true for the same arguments provided to the execution function.
+     *
+     * ```javascript [playground]
+     * const isOdd = number => number % 2 == 1
+     *
+     * const logIfOdd = tap.if(
+     *   isOdd,
+     *   number => console.log(number, 'is an odd number')
+     * )
+     *
+     * logIfOdd(2)
+     * logIfOdd(3) // 3 is an odd number
+     * ```
+     */
+    function _if(predicate: any, func: any): (...args: any[]) => any;
+    export { _if as if };
+}

package/thunkify.d.ts

@@ -0,0 +1,21 @@
+export = thunkify;
+/**
+ * @name thunkify
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * thunkify(func function, ...args) -> thunk ()=>func(...args)
+ * ```
+ *
+ * @description
+ * 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
+ *
+ * const thunkAdd12 = thunkify(add, 1, 2)
+ *
+ * console.log(thunkAdd12()) // 3
+ * ```
+ */
+declare function thunkify(func: any, ...args: any[]): () => any;