rubico 2.3.0 → 2.3.1

package/transform.d.ts

@@ -0,0 +1,131 @@
+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(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
+ *
+ * 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

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

package/x/append.d.ts

@@ -0,0 +1,38 @@
+export = append;
+/**
+ * @name append
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * append(
+ *   item string|Array,
+ * )(value string|Array) -> string|array
+ * ```
+ *
+ * @description
+ * Append a string or an array.
+ *
+ * ```javascript [playground]
+ * import append from 'https://unpkg.com/rubico/dist/x/append.es.js'
+ *
+ * const myArray = ['orange', 'apple']
+ *
+ * {
+ *   const result = append(['ananas'])(myArray)
+ *   console.log(result) // ['orange', 'apple', 'ananas']
+ * }
+ *
+ * {
+ *   const result = append('ananas')(myArray)
+ *   console.log(result) // ['orange', 'apple', 'ananas']
+ * }
+ *
+ * {
+ *   const result = append('world')('hello ')
+ *   console.log(result) // 'hello world'
+ * }
+ * ```
+ *
+ * @since 1.7.3
+ */
+declare function append(item: any): (value: any) => string | any[];

package/x/callProp.d.ts

@@ -0,0 +1,20 @@
+export = callProp;
+/**
+ * @name callProp
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * callProp(property string, ...args)(object) -> object[property](...args)
+ * ```
+ *
+ * @description
+ * Calls a property on an object with arguments.
+ *
+ * ```javascript [playground]
+ * import callProp from 'https://unpkg.com/rubico/dist/x/callProp.es.js'
+ *
+ * const priceRoundedDown = callProp('toFixed', 2)(5.992)
+ * console.log('priceRoundedDown:', priceRoundedDown) // '5.99'
+ * ```
+ */
+declare function callProp(property: any, ...args: any[]): (object: any) => any;

package/x/defaultsDeep.d.ts

@@ -0,0 +1,42 @@
+export = defaultsDeep;
+/**
+ * @name defaultsDeep
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * var defaultCollection Array|Object,
+ *   value Array|Object
+ *
+ * defaultsDeep(defaultCollection)(value) -> Array|Object
+ * ```
+ *
+ * @description
+ * Deeply assign default values to an array or object by an array or object of possibly nested default values.
+ *
+ * ```javascript [playground]
+ * import defaultsDeep from 'https://unpkg.com/rubico/dist/x/defaultsDeep.es.js'
+ *
+ * const defaultUser = defaultsDeep({
+ *   name: 'placeholder',
+ *   images: [
+ *     { url: 'https://via.placeholder.com/150' },
+ *     { url: 'https://via.placeholder.com/150' },
+ *     { url: 'https://via.placeholder.com/150' },
+ *   ],
+ * })
+ *
+ * console.log(defaultUser({
+ *   name: 'George',
+ *   images: [{ url: 'https://via.placeholder.com/150/0000FF/808080%20?Text=Digital.com' }],
+ * }))
+ * // {
+ * //   name: 'George',
+ * //   images: [
+ * //    { url: 'https://via.placeholder.com/150/0000FF/808080%20?Text=Digital.com' },
+ * //    { url: 'https://via.placeholder.com/150' },
+ * //    { url: 'https://via.placeholder.com/150' },
+ * //   ],
+ * // }
+ * ```
+ */
+declare function defaultsDeep(defaultCollection: any): (value: any) => any;

package/x/differenceWith.d.ts

@@ -0,0 +1,25 @@
+export = differenceWith;
+/**
+ * @name differenceWith
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * differenceWith(
+ *   comparator (any, any)=>Promise|boolean,
+ *   allValues Array,
+ * )(values Array) -> someOrAllValues Array
+ * ```
+ *
+ * @description
+ * Create an array of all the values in an array that are not in another array as dictated by a comparator.
+ *
+ * ```javascript [playground]
+ * import differenceWith from 'https://unpkg.com/rubico/dist/x/differenceWith.es.js'
+ * import isDeepEqual from 'https://unpkg.com/rubico/dist/x/isDeepEqual.es.js'
+ *
+ * console.log(
+ *   differenceWith(isDeepEqual, [{ a: 1 }, { b: 2 }, { c: 3 }])([{ b: 2 }]),
+ * ) // [{ a: 1 }, { c: 3 }]
+ * ```
+ */
+declare function differenceWith(comparator: any, allValues: any): (values: any) => any;

package/x/filterOut.d.ts

@@ -0,0 +1,39 @@
+export = filterOut;
+/**
+ * @name filterOut
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * filterOut(
+ *   arrayPredicate (value any, index number, array Array)=>Promise|boolean
+ * )(array) -> rejectedArray Promise|Array
+ *
+ * filterOut(
+ *   objectPredicate (value any, key string, object Object)=>Promise|boolean
+ * )(object) -> rejectedObject Promise|Object
+ *
+ * filterOut(
+ *   setPredicate (value any, value, set Set)=>Promise|boolean
+ * )(set) -> rejectedSet Promise|Set
+ *
+ * filterOut(
+ *   mapPredicate (value any, key any, map Map)=>Promise|boolean
+ * )(map) -> rejectedMap Promise|Map
+ *
+ * filterOut(
+ *   predicate (value any)=>Promise|boolean
+ * )(generatorFunction GeneratorFunction) -> rejectingGeneratorFunction GeneratorFunction
+ *
+ * filterOut(
+ *   predicate (value any)=>Promise|boolean
+ * )(asyncGeneratorFunction AsyncGeneratorFunction) -> rejectingAsyncGeneratorFunction AsyncGeneratorFunction
+ *
+ * filterOut(
+ *   predicate (value any)=>Promise|boolean
+ * )(reducer Reducer) -> rejectingReducer Reducer
+ * ```
+ *
+ * @description
+ * The inverse of `filter`. Values that test true by the predicate are filtered out, or "rejected".
+ */
+declare function filterOut(predicate: any): any;

package/x/find.d.ts

@@ -0,0 +1,34 @@
+export = find;
+/**
+ * @name find
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * Foldable<T> = Iterable<T>|AsyncIterable<T>|{ reduce: (any, T)=>any }|Object<T>
+ *
+ * var T any,
+ *   predicate T=>Promise|boolean,
+ *   foldable Foldable<T>,
+ *   result Promise|T|undefined
+ *
+ * find(predicate)(foldable) -> result
+ * ```
+ *
+ * @description
+ * Get the first item in a foldable collection that matches a predicate.
+ *
+ * ```javascript [playground]
+ * import find from 'https://unpkg.com/rubico/dist/x/find.es.js'
+ *
+ * const users = [
+ *   { name: 'John', age: 16 },
+ *   { name: 'Jill', age: 32 },
+ *   { name: 'George', age: 51 },
+ * ]
+ *
+ * console.log(
+ *   find(user => user.age > 50)(users),
+ * ) // { name: 'George', age: 51 }
+ * ```
+ */
+declare function find(predicate: any): (value: any) => any;

package/x/findIndex.d.ts

@@ -0,0 +1,25 @@
+export = findIndex;
+/**
+ * @name findIndex
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * findIndex(predicate function)(array Array) -> index Promise|number
+ * ```
+ *
+ * @description
+ * Returns the index of the first element in an array that satisfies the predicate. Returns -1 if no element satisfies the predicate.
+ *
+ * ```javascript [playground]
+ * import findIndex from 'https://unpkg.com/rubico/dist/x/findIndex.es.js'
+ *
+ * const oddNumberIndex = findIndex(function isOdd(number) {
+ *   return number % 2 == 1
+ * })([2, 3, 5])
+ *
+ * console.log(oddNumberIndex) // 1
+ * ```
+ *
+ * @since 1.6.26
+ */
+declare function findIndex(predicate: any): (array: any) => any;

package/x/first.d.ts

@@ -0,0 +1,23 @@
+export = first;
+/**
+ * @name first
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * var value Array|string
+ *
+ * first(value) -> any
+ * ```
+ *
+ * @description
+ * Get the first item of a collection
+ *
+ * ```javascript [playground]
+ * import first from 'https://unpkg.com/rubico/dist/x/first.es.js'
+ *
+ * console.log(first([1, 2, 3])) // 1
+ * console.log(first('abc')) // 'a'
+ * console.log(first([])) // undefined
+ * ```
+ */
+declare function first(value: any): any;

package/x/flatten.d.ts

@@ -0,0 +1,57 @@
+export = flatten;
+/**
+ * @name flatten
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * Stream<T> = { read: ()=>T, write: T=>() }
+ * Monad<T> = Array<T>|String<T>|Set<T>
+ *   |TypedArray<T>|Stream<T>|Iterator<T>|AsyncIterator<T>
+ *   |{ chain: T=>Monad<T> }|{ flatMap: T=>Monad<T> }|Object<T>
+ * Reducer<T> = (any, T)=>Promise|any
+ * Foldable<T> = Iterable<T>|AsyncIterable<T>|{ reduce: Reducer<T>=>any }|Object<T>
+ *
+ * var T any,
+ *   monad Monad<Monad<T>|Foldable<T>|T>,
+ *   args ...any,
+ *   generatorFunction ...args=>Generator<Monad<T>|Foldable<T>|T>,
+ *   asyncGeneratorFunction ...args=>AsyncGenerator<Monad<T>|Foldable<T>|T>,
+ *   reducer Reducer<Monad<T>|Foldable<T>|T>
+ *
+ * flatten(monad) -> Monad<T>
+ *
+ * flatten(generatorFunction) -> ...args=>Generator<T>
+ *
+ * flatten(asyncGeneratorFunction) -> ...args=>AsyncGenerator<T>
+ *
+ * flatten(reducer) -> Reducer<T>
+ * ```
+ *
+ * @description
+ * Flatten a collection. Works in transducer position.
+ *
+ * ```javascript [playground]
+ * import flatten from 'https://unpkg.com/rubico/dist/x/flatten.es.js'
+ *
+ * flatten([
+ *   [1, 1],
+ *   new Set([2, 2]),
+ *   (function* () { yield 3; yield 3 })(),
+ *   (async function* () { yield 4; yield 4 })(),
+ *   { a: 5, b: 5 },
+ *   6,
+ *   Promise.resolve(7),
+ *   new Uint8Array([8]),
+ * ]).then(console.log)
+ * // [1, 1, 2, 3, 3, 5, 5, 6, 7, 8, 4, 4]
+ *
+ * const add = (a, b) => a + b
+ *
+ * console.log(
+ *   [[1], [2], [3], [4], [5]].reduce(flatten(add), 0),
+ * ) // 15
+ * ```
+ *
+ * @TODO flatten for each type
+ */
+declare function flatten(value: any): any;

package/x/groupBy.d.ts

@@ -0,0 +1,50 @@
+export = groupBy;
+/**
+ * @name groupBy
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * Reducer<T> = (any, T)=>Promise|any
+ * Foldable<T> = Iterable<T>|AsyncIterable<T>|{ reduce: Reducer<T>=>any }|Object<T>
+ *
+ * var property any,
+ *   resolver any=>Promise|any,
+ *   value Foldable
+ *
+ * groupBy(property)(value) -> groupedByProperty Map<any=>Array>
+ *
+ * groupBy(resolver)(value) -> groupedByResolver Promise|Map<any=>Array>
+ * ```
+ *
+ * @description
+ * Group a foldable collection into a Map of arrays by a property on each of its elements.
+ *
+ * ```javascript [playground]
+ * import groupBy from 'https://unpkg.com/rubico/dist/x/groupBy.es.js'
+ *
+ * console.log(
+ *   groupBy('age')([
+ *     { name: 'George', age: 22 },
+ *     { name: 'Jane', age: 22 },
+ *     { name: 'Henry', age: 23 },
+ *   ]),
+ * )
+ * // Map {
+ * //   22 => [{ name: 'George', age: 22 }, { name: 'Jane', age: 22 }],
+ * //   23 => [{ name: 'Henry', age: 23 }],
+ * // }
+ * ```
+ *
+ * Additionally, pass a resolver in property position to resolve a value for group membership for each item.
+ *
+ * ```javascript [playground]
+ * import groupBy from 'https://unpkg.com/rubico/dist/x/groupBy.es.js'
+ *
+ * console.log(
+ *   groupBy(
+ *     word => word.toLowerCase(),
+ *   )(['Hello', 'hello', 'Hey']),
+ * ) // Map { 'hello' => ['Hello', 'hello'], 'hey' => ['Hey'] }
+ * ```
+ */
+declare function groupBy(propertyOrResolver: any): any;

package/x/has.d.ts

@@ -0,0 +1,25 @@
+export = has;
+/**
+ * @name has
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * has(key any)(container Set|Map|{ has: function }|Object) -> Promise|boolean
+ * ```
+ *
+ * @description
+ * Check if a collection has a key.
+ *
+ * ```javascript [playground]
+ * import has from 'https://unpkg.com/rubico/dist/x/has.es.js'
+ *
+ * console.log(
+ *   has('a')({ a: 1, b: 2, c: 3 }),
+ * ) // true
+ *
+ * console.log(
+ *   has('a')({}),
+ * ) // false
+ * ```
+ */
+declare function has(key: any): (container: any) => any;

package/x/heapUsedInLoop.d.ts

@@ -0,0 +1,53 @@
+export = heapUsedInLoop;
+/**
+ * @name heapUsedInLoop
+ *
+ * @catchphrase
+ * max and avg heap used in loop
+ *
+ * @synopsis
+ * heapUsedInLoop(
+ *   desc string,
+ *   loopCount number,
+ *   func (loop number)=>any
+ * ) -> ()
+ *
+ * @description
+ * **heapUsedInLoop** is a memory usage measurement function. Supply `description`, `loopCount`, and a function `func` for that function to be run `loopCount` times, finally logging average and max heap used per loop in terms of megabytes MiB.
+ *
+ * ```javascript
+ * heapUsedInLoop('my-description', 1e5, function () {
+ *   return 1 + 1
+ * }) /*
+ * 0 5.88 MiB
+ * 1 5.92 MiB
+ * ...
+ * 99997 7.34 MiB
+ * 99998 7.34 MiB
+ * 99999 7.35 MiB
+ * my-description: 1e+5: {
+ *   "max": "7.15 MiB",
+ *   "avg": "5.50 MiB"
+ * }
+ * ```
+ *
+ * @node-only
+ */
+declare function heapUsedInLoop(desc: any, loopCount: any, func: any): void;
+declare namespace heapUsedInLoop {
+    function skip(): void;
+    /**
+     * @name heapUsedInLoop.async
+     *
+     * @synopsis
+     * heapUsedInLoop.async(
+     *   desc string,
+     *   loopCount number,
+     *   func (loop number)=>Promise|any
+     * ) -> ()
+     */
+    function async(desc: any, loopCount: any, func: any): Promise<void>;
+    namespace async {
+        function skip(): void;
+    }
+}

package/x/identity.d.ts

@@ -0,0 +1,21 @@
+export = identity;
+/**
+ * @name identity
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * identity(value any) -> value
+ * ```
+ *
+ * @description
+ * Pass a value and receive the same value back.
+ *
+ * ```javascript [playground]
+ * import identity from 'https://unpkg.com/rubico/dist/x/identity.es.js'
+ *
+ * console.log(
+ *   identity(1),
+ * ) // 1
+ * ```
+ */
+declare function identity(value: any): any;

package/x/includes.d.ts

@@ -0,0 +1,25 @@
+export = includes;
+/**
+ * @name includes
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * includes(value any)(container Array|String|Object) -> boolean
+ * ```
+ *
+ * @description
+ * Check if a collection includes another value by [SameValueZero](http://ecma-international.org/ecma-262/7.0/#sec-samevaluezero).
+ *
+ * ```javascript [playground]
+ * import includes from 'https://unpkg.com/rubico/dist/x/includes.es.js'
+ *
+ * console.log(
+ *   includes(5)([1, 2, 3, 4, 5])
+ * ) // true
+ *
+ * console.log(
+ *   includes(5)([1, 2, 3])
+ * ) // false
+ * ```
+ */
+declare function includes(value: any): (container: any) => any;