rubico 2.7.4 → 2.7.6

package/reduce.d.ts

@@ -1,166 +0,0 @@
-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 element of the collection. The reducing operation then iterates through the remaining elements 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 element 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 element 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 element of the iteration, the index of the element 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 element 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 element of the set. On each iteration, the reducer is passed the accumulator and element 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 element, the key of the map element, 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 element 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 element 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

@@ -1,61 +0,0 @@
-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 lazy 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

@@ -1,65 +0,0 @@
-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 elements 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 lazy 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

@@ -1,76 +0,0 @@
-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 lazy 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 element 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

@@ -1,53 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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;

package/transform.d.ts

@@ -1,131 +0,0 @@
-export = transform;
-/**
- * @name transform
- *
- * @synopsis
- * ```coffeescript [specscript]
- * type Foldable = Iterable|AsyncIterable|Object<value any>
- *
- * type Reducer = (
- *   accumulator any,
- *   value any,
- *   indexOrKey? number|string,
- *   collection? Foldable,
- * )=>(nextAccumulator Promise|any)
- *
- * type Transducer = Reducer=>Reducer
- *
- * type Transformable =
- *   Array|String|Set|TypedArray|{ concat: function }|{ write: function }|Object
- *
- * type TransformableResolver = (collection Foldable)=>Promise|Transformable
- *
- * transform(
- *   collection Foldable,
- *   transducer Transducer,
- *   initialValue? Transformable|TransformableResolver,
- * ) -> result Promise|Transformable
- *
- * transform(
- *   transducer Transducer,
- *   initialValue? Transformable|TransformableResolver,
- * )(collection Foldable) -> result Promise|Transformable
- * ```
- *
- * @description
- * 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(element)`
- *  * `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
- *
- * const isOdd = number => number % 2 == 1
- *
- * const squaredOdds = compose([
- *   Transducer.filter(isOdd),
- *   Transducer.map(square),
- * ])
- *
- * // transform arrays into arrays
- * console.log(
- *   transform(squaredOdds, [])([1, 2, 3, 4, 5])
- * ) // [1, 9, 25]
- *
- * // transform arrays into strings
- * console.log(
- *   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]),
- * ) // Uint8Array(3) [ 1, 9, 25 ]
- * ```
- *
- * `transform` arrays into objects that implement `.concat`.
- *
- * ```javascript [playground]
- * const square = number => number ** 2
- *
- * const Stdout = {
- *   concat(...args) {
- *     console.log(...args)
- *     return this
- *   },
- * }
- *
- * transform(Transducer.map(square), Stdout)([1, 2, 3, 4, 5])
- * // 1
- * // 4
- * // 9
- * // 16
- * // 25
- * ```
- *
- * `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
- *
- * const { pipe, map, transform } = require('rubico')
- *
- * const square = number => number ** 2
- *
- * const toString = value => value.toString()
- *
- * const randomInt = () => Math.ceil(Math.random() * 100)
- *
- * const streamRandomInts = async function* () {
- *   while (true) {
- *     yield randomInt()
- *   }
- * }
- *
- * transform(
- *   streamRandomInts(),
- *   Transducer.map(pipe([square, toString])),
- *   process.stdout,
- * ) // 9216576529289484980147613249169774446246768649...
- * ```
- *
- * @execution series
- *
- * @transducing
- *
- * TODO explore Semigroup = Iterator|AsyncIterator
- */
-declare function transform(...args: any[]): any;

package/tryCatch.d.ts

@@ -1,47 +0,0 @@
-export = tryCatch;
-/**
- * @name tryCatch
- *
- * @synopsis
- * ```coffeescript [specscript]
- * tryCatch(tryer function, catcher function)(...args) -> Promise|any
- *
- * tryCatch(...args, tryer function, catcher function) -> Promise|any
- * ```
- *
- * @description
- * 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 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
- *
- * ```
- *
- * `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
- *
- * tryCatch(1, 2, 3, function throwSum(...numbers) {
- *   const sum = numbers.reduce(add)
- *   throw new Error(`the sum is ${sum}`)
- * }, function logErrorMessage(error) {
- *   console.error(error.message) // the sum is 6
- * })
- * ```
- */
-declare function tryCatch(...args: any[]): any;