@rimbu/common 0.8.2 → 0.9.2

package/dist/types/reducer.d.ts

@@ -41,59 +41,72 @@ export declare namespace Reducer {
         stateToResult(state: S): O;
         /**
          * Returns a `Reducer` instance that only passes values to the reducer that satisy the given `pred` predicate.
-         * @param pred - a function that returns true if the value should be passed to the reducer based on the following inputs:
-         * - value: the current input value
-         * - index: the current input index
+         * @param pred - a function that returns true if the value should be passed to the reducer based on the following inputs:<br/>
+         * - value: the current input value<br/>
+         * - index: the current input index<br/>
          * - halt: function that, when called, ensures no more new values are passed to the reducer
          * @example
+         * ```ts
          * Reducer.sum.filterInput(v => v > 10)
          * // this reducer will only sum values larger than 10
+         * ```
          */
         filterInput(pred: (value: I, index: number, halt: () => void) => boolean): Reducer<I, O>;
         /**
          * Returns a `Reducer` instance that converts its input values using given `mapFun` before passing them to the reducer.
-         * @param mapFun - a function that returns a new value to pass to the reducer based on the following inputs:
-         * - value: the current input value
+         * @param mapFun - a function that returns a new value to pass to the reducer based on the following inputs:<br/>
+         * - value: the current input value<br/>
          * - index: the current input index
          * @example
+         * ```ts
          * Reducer.sum.mapInput(v => v * 2)
          * // this reducer will double all input values before summing them
+         * ```
          */
         mapInput<I2>(mapFun: (value: I2, index: number) => I): Reducer<I2, O>;
         /**
          * Returns a `Reducer` instance that converts or filters its input values using given `collectFun` before passing them to the reducer.
-         * @param collectFun - a function receiving
-         * * `value`: the next value
-         * * `index`: the value index
-         * * `skip`: a token that, when returned, will not add a value to the resulting collection
-         * * `halt`: a function that, when called, ensures no next elements are passed
+         * @param collectFun - a function receiving<br/>
+         * - `value`: the next value<br/>
+         * - `index`: the value index<br/>
+         * - `skip`: a token that, when returned, will not add a value to the resulting collection<br/>
+         * - `halt`: a function that, when called, ensures no next elements are passed
          * @example
+         * ```ts
          * Reducer.sum.collectInput((v, _, skip) => v <= 10 ? skip : v * 2)
          * // this reducer will double all input values larger thant 10 before summing them,
          * // and will skip all values smaller than 10
+         * ```
          */
         collectInput<I2>(collectFun: CollectFun<I2, I>): Reducer<I2, O>;
         /**
          * Returns a `Reducer` instance that converts its output values using given `mapFun`.
          * @param mapFun - a function that takes the current output value and converts it to a new output value
+         * @example
+         * ```ts
          * Reducer.sum.mapOutput(String)
          * // this reducer will convert all its results to string before returning them
+         * ```
          */
         mapOutput<O2>(mapFun: (value: O) => O2): Reducer<I, O2>;
         /**
          * Returns a `Reducer` instance that takes at most the given `amount` of input elements, and will ignore subsequent elements.
          * @param amount - the amount of elements to accept
          * @example
+         * ```ts
          * Stream.range({ end: 10 }).reduce(Reducer.sum.takeInput(2))
          * // => 1
+         * ```
          */
         takeInput(amount: number): Reducer<I, O>;
         /**
          * Returns a `Reducer` instance that skips the first given `amount` of input elements, and will process subsequent elements.
          * @param amount - the amount of elements to skip
          * @example
+         * ```ts
          * Stream.range({ end: 10 }).reduce(Reducer.sum.dropInput(9))
          * // => 19
+         * ```
          */
         dropInput(amount: number): Reducer<I, O>;
         /**
@@ -101,8 +114,10 @@ export declare namespace Reducer {
          * @param from - (default: 0) the index at which to start processing elements
          * @param amount - (optional) the amount of elements to process, if not given, processes all elements from the `from` index
          * @example
+         * ```ts
          * Stream.range({ end: 10 }).reduce(Reducer.sum.sliceInput(1, 2))
          * // => 3
+         * ```
          */
         sliceInput(from?: number, amount?: number): Reducer<I, O>;
     }
@@ -128,16 +143,17 @@ export declare namespace Reducer {
     /**
      * Returns a `Reducer` with the given options:
      * @param init - the initial state value
-     * @param next - returns the next state value based on the given inputs:
-     * - current: the current state
-     * - next: the current input value
-     * - index: the input index value
+     * @param next - returns the next state value based on the given inputs:<br/>
+     * - current: the current state<br/>
+     * - next: the current input value<br/>
+     * - index: the input index value<br/>
      * - halt: function that, when called, ensures no more elements are passed to the reducer
      * @param stateToResult - a function that converts the current state to an output value
      * @typeparam I - the input value type
      * @typeparam O - the output value type
      * @typeparam S - the internal state type
      * @example
+     * ```ts
      * const evenNumberOfOnes = Reducer
      *   .create(
      *     true,
@@ -146,18 +162,21 @@ export declare namespace Reducer {
      * const result = Stream.of(1, 2, 3, 2, 1)).reduce(evenNumberOfOnes)
      * console.log+(result)
      * // => 'even'
+     * ```
      */
     function create<I, O = I, S = O>(init: Reducer.Init<S>, next: (current: S, next: I, index: number, halt: () => void) => S, stateToResult: (state: S) => O): Reducer<I, O>;
     /**
      * Returns a `Reducer` of which the input, state, and output types are the same.
      * @param init - the initial state value
-     * @param next - returns the next state value based on the given inputs:
-     * - current: the current state
-     * - next: the current input value
-     * - index: the input index value
+     * @param next - returns the next state value based on the given inputs:<br/>
+     * - current: the current state<br/>
+     * - next: the current input value<br/>
+     * - index: the input index value<br/>
      * - halt: function that, when called, ensures no more elements are passed to the reducer
      * @param stateToResult - (optional) a function that converts the current state to an output value
      * @typeparam T - the overall value type
+     * @example
+     * ```ts
      * const sum = Reducer
      *   .createMono(
      *     0,
@@ -166,19 +185,22 @@ export declare namespace Reducer {
      * const result = Stream.of(1, 2, 3, 2, 1)).reduce(sum)
      * console.log+(result)
      * // => 9
+     * ```
      */
     function createMono<T>(init: Reducer.Init<T>, next: (current: T, next: T, index: number, halt: () => void) => T, stateToResult?: (state: T) => T): Reducer<T>;
     /**
      * Returns a `Reducer` of which the state and output types are the same.
      * @param init - the initial state value
-     * @param next - returns the next state value based on the given inputs:
-     * - current: the current state
-     * - next: the current input value
-     * - index: the input index value
+     * @param next - returns the next state value based on the given inputs:<br/>
+     * - current: the current state<br/>
+     * - next: the current input value<br/>
+     * - index: the input index value<br/>
      * - halt: function that, when called, ensures no more elements are passed to the reducer
      * @param stateToResult - (optional) a function that converts the current state to an output value
      * @typeparam I - the input value type
      * @typeparam O - the output value type
+     * @example
+     * ```ts
      * const boolToString = Reducer
      *   .createOutput(
      *     '',
@@ -187,27 +209,34 @@ export declare namespace Reducer {
      * const result = Stream.of(true, false, true)).reduce(boolToString)
      * console.log+(result)
      * // => 'TFT'
+     * ```
      */
     function createOutput<I, O = I>(init: Reducer.Init<O>, next: (current: O, next: I, index: number, halt: () => void) => O, stateToResult?: (state: O) => O): Reducer<I, O>;
     /**
      * A `Reducer` that sums all given numeric input values.
      * @example
+     * ```ts
      * console.log(Stream.range({ amount: 5 }).reduce(Reducer.sum))
      * // => 10
+     * ```
      */
     const sum: Reducer<number, number>;
     /**
      * A `Reducer` that calculates the product of all given numeric input values.
      * @example
+     * ```ts
      * console.log(Stream.range({ start: 1, amount: 5 }).reduce(product))
      * // => 120
+     * ```
      */
     const product: Reducer<number, number>;
     /**
      * A `Reducer` that calculates the average of all given numberic input values.
      * @example
+     * ```ts
      * console.log(Stream.range({ amount: 5 }).reduce(Reducer.average));
      * // => 2
+     * ```
      */
     const average: Reducer<number, number>;
     /**
@@ -215,9 +244,11 @@ export declare namespace Reducer {
      * @param compFun - a comparison function for two input values, returning 0 when equal, positive when greater, negetive when smaller
      * @param otherwise - (default: undefineds) a fallback value when there were no input values given
      * @example
+     * ```ts
      * const stream = Stream.of('abc', 'a', 'abcde', 'ab')
      * console.log(stream.minBy((s1, s2) => s1.length - s2.length))
      * // 'a'
+     * ```
      */
     const minBy: {
         <T>(compFun: (v1: T, v2: T) => number): Reducer<T, T | undefined>;
@@ -227,8 +258,10 @@ export declare namespace Reducer {
      * Returns a `Reducer` that remembers the minimum value of the numberic inputs.
      * @param otherwise - (default: undefined) a fallback value when there were no input values given
      * @example
+     * ```ts
      * console.log(Stream.of(5, 3, 7, 4).reduce(Reducer.min()))
      * // => 3
+     * ```
      */
     const min: {
         (): Reducer<number, number | undefined>;
@@ -239,9 +272,11 @@ export declare namespace Reducer {
      * @param compFun - a comparison function for two input values, returning 0 when equal, positive when greater, negetive when smaller
      * @param otherwise - (default: undefined) a fallback value when there were no input values given
      * @example
+     * ```ts
      * const stream = Stream.of('abc', 'a', 'abcde', 'ab')
      * console.log(stream.maxBy((s1, s2) => s1.length - s2.length))
      * // 'abcde'
+     * ```
      */
     const maxBy: {
         <T>(compFun: (v1: T, v2: T) => number): Reducer<T, T | undefined>;
@@ -251,22 +286,26 @@ export declare namespace Reducer {
      * Returns a `Reducer` that remembers the maximum value of the numberic inputs.
      * @param otherwise - (default: undefined) a fallback value when there were no input values given
      * @example
+     * ```ts
      * console.log(Stream.of(5, 3, 7, 4).reduce(Reducer.max()))
      * // => 7
+     * ```
      */
     const max: {
         (): Reducer<number, number | undefined>;
         <O>(otherwise: OptLazy<O>): Reducer<number, number | O>;
     };
     /**
-     * Returns a `Reducer` that joins the given input values into a string using the given options.
-     * @options - an object containing:
-     * - sep: (optional) a seperator string value between values in the output
-     * - start: (optional) a start string to prepend to the output
-     * - end: (optional) an end string to append to the output
+     * Returns a `yaReducer` that joins the given input values into a string using the given options.
+     * @param options - an object containing:<br/>
+     * - sep: (optional) a seperator string value between values in the output<br/>
+     * - start: (optional) a start string to prepend to the output<br/>
+     * - end: (optional) an end string to append to the output<br/>
      * @example
+     * ```ts
      * console.log(Stream.of(1, 2, 3).reduce(Reducer.join({ sep: '-' })))
      * // => '1-2-3'
+     * ```
      */
     function join<T>({ sep, start, end, valueToString, }?: {
         sep?: string | undefined;
@@ -276,15 +315,17 @@ export declare namespace Reducer {
     }): Reducer<T, string>;
     /**
      * Returns a `Reducer` that remembers the amount of input items provided.
-     * @param pred - (optional) a predicate that returns false if the item should not be counted given:
-     * - value: the current input value
+     * @param pred - (optional) a predicate that returns false if the item should not be counted given:<br/>
+     * - value: the current input value<br/>
      * - index: the input value index
      * @example
+     * ```ts
      * const stream = Stream.range({ amount: 10 })
      * console.log(stream.reduce(Reducer.count()))
      * // => 10
      * console.log(stream.reduce(Reducer.count(v => v < 5)))
      * // => 5
+     * ```
      */
     const count: {
         (): Reducer<any, number>;
@@ -297,8 +338,10 @@ export declare namespace Reducer {
      * @typeparam T - the input value type
      * @typeparam O - the fallback value type
      * @example
+     * ```ts
      * console.log(Stream.range({ amount: 10 }).reduce(Reducer.firstWhere(v => v > 5)))
      * // => 6
+     * ```
      */
     const firstWhere: {
         <T>(pred: (value: T, index: number) => boolean): Reducer<T, T | undefined>;
@@ -310,8 +353,10 @@ export declare namespace Reducer {
      * @typeparam T - the input value type
      * @typeparam O - the fallback value type
      * @example
+     * ```ts
      * console.log(Stream.range{ amount: 10 }).reduce(Reducer.first())
      * // => 0
+     * ```
      */
     const first: {
         <T>(): Reducer<T, T | undefined>;
@@ -324,8 +369,10 @@ export declare namespace Reducer {
      * @typeparam T - the input value type
      * @typeparam O - the fallback value type
      * @example
+     * ```ts
      * console.log(Stream.range({ amount: 10 }).reduce(Reducer.lastWhere(v => v > 5)))
      * // => 9
+     * ```
      */
     const lastWhere: {
         <T>(pred: (value: T, index: number) => boolean): Reducer<T, T | undefined>;
@@ -337,8 +384,10 @@ export declare namespace Reducer {
      * @typeparam T - the input value type
      * @typeparam O - the fallback value type
      * @example
+     * ```ts
      * console.log(Stream.range{ amount: 10 }).reduce(Reducer.first())
      * // => 0
+     * ```
      */
     const last: {
         <T>(): Reducer<T, T | undefined>;
@@ -348,16 +397,20 @@ export declare namespace Reducer {
      * Returns a `Reducer` that ouputs false as long as no input value satisfies given `pred`, true otherwise.
      * @param pred - a function taking an input value and its index, and returning true if the value satisfies the predicate
      * @example
+     * ```ts
      * console.log(Stream.range{ amount: 10 }).reduce(Reducer.some(v => v > 5))
      * // => true
+     * ```
      */
     function some<T>(pred: (value: T, index: number) => boolean): Reducer<T, boolean>;
     /**
      * Returns a `Reducer` that ouputs true as long as all input values satisfy the given `pred`, false otherwise.
      * @param pred - a function taking an input value and its index, and returning true if the value satisfies the predicate
      * @example
+     * ```ts
      * console.log(Stream.range{ amount: 10 }).reduce(Reducer.every(v => v < 5))
      * // => false
+     * ```
      */
     function every<T>(pred: (value: T, index: number) => boolean): Reducer<T, boolean>;
     /**
@@ -365,68 +418,86 @@ export declare namespace Reducer {
      * @param elem - the element to search for
      * @param eq - (optional) a comparison function that returns true if te two given input values are considered equal
      * @example
+     * ```ts
      * console.log(Stream.range({ amount: 10 }).reduce(Reducer.contains(5)))
      * // => true
+     * ```
      */
     function contains<T>(elem: T, eq?: Eq<T>): Reducer<T, boolean>;
     /**
      * Returns a `Reducer` that takes boolean values and outputs true if all input values are true, and false otherwise.
      * @example
+     * ```ts
      * console.log(Stream.of(true, false, true)).reduce(Reducer.and))
      * // => false
+     * ```
      */
     const and: Reducer<boolean, boolean>;
     /**
      * Returns a `Reducer` that takes boolean values and outputs true if one or more input values are true, and false otherwise.
      * @example
+     * ```ts
      * console.log(Stream.of(true, false, true)).reduce(Reducer.or))
      * // => true
+     * ```
      */
     const or: Reducer<boolean, boolean>;
     /**
      * Returns a `Reducer` that outputs true if no input values are received, false otherwise.
      * @example
+     * ```ts
      * console.log(Stream.of(1, 2, 3).reduce(Reducer.isEmpty))
      * // => false
+     * ```
      */
     const isEmpty: Reducer<any, boolean>;
     /**
      * Returns a `Reducer` that outputs true if one or more input values are received, false otherwise.
      * @example
+     * ```ts
      * console.log(Stream.of(1, 2, 3).reduce(Reducer.nonEmpty))
      * // => true
+     * ```
      */
     const nonEmpty: Reducer<any, boolean>;
     /**
      * Returns a `Reducer` that collects received input values in an array, and returns a copy of that array as an output value when requested.
      * @example
+     * ```ts
      * console.log(Stream.of(1, 2, 3).reduce(Reducer.toArray()))
      * // => [1, 2, 3]
+     * ```
      */
     function toArray<T>(): Reducer<T, T[]>;
     /**
      * Returns a `Reducer` that collects received input tuples into a mutable JS Map, and returns
      * a copy of that map when output is requested.
      * @example
+     * ```ts
      * console.log(Stream.of([1, 'a'], [2, 'b']).reduce(Reducer.toJSMap()))
      * // Map { 1 => 'a', 2 => 'b' }
+     * ```
      */
     function toJSMap<K, V>(): Reducer<[K, V], Map<K, V>>;
     /**
      * Returns a `Reducer` that collects received input values into a mutable JS Set, and returns
      * a copy of that map when output is requested.
      * @example
+     * ```ts
      * console.log(Stream.of(1, 2, 3).reduce(Reducer.toJSSet()))
      * // Set {1, 2, 3}
+     * ```
      */
     function toJSSet<T>(): Reducer<T, Set<T>>;
     /**
      * Returns a `Reducer` that combines multiple input `reducers` by providing input values to all of them and collecting the outputs in an array.
      * @param reducers - 2 or more reducers to combine
      * @example
+     * ```ts
      * const red = Reducer.combine(Reducer.sum, Reducer.average)
      * console.log(Stream.range({amount: 9 }).reduce(red))
      * // => [36, 4]
+     * ```
      */
     function combine<T, R extends readonly [unknown, unknown, ...unknown[]]>(...reducers: {
         [K in keyof R]: Reducer<T, R[K]>;

package/dist/types/types.d.ts

@@ -20,10 +20,6 @@ export declare type ArrayNonEmpty<T> = [T, ...T[]];
  * Accepts all strings with at least one character.
  */
 export declare type StringNonEmpty<T> = T extends string ? '' extends T ? never : T : never;
-/**
- * A stronger version of `Omit`, which only accepts keys that are in type T.
- */
-export declare type OmitStrong<T, K extends keyof T> = Omit<T, K>;
 /**
  * Utility type to convert some object to a JSON serializable format.
  * @typeparam V - the `value` type

package/dist/types/update.d.ts

@@ -5,12 +5,14 @@ export declare type Update<T> = T | ((value: T) => T);
 /**
  * Returns the result of given `update` parameter, where it can either directly give a new value,
  * or it is a function receiving the given `value`, and returns a new value.
- * @param value - the current vale
+ * @param value - the current value
  * @param update - an `Update` value, either a new value or a function receiving the old value
  * and returning a new one.
  * @example
+ * ```ts
  * Update(1, 2)          // => 2
  * Update(1, () => 10)   // => 10
  * Update(1, v => v + 1) // => 2
+ * ```
  */
 export declare function Update<T>(value: T, update: Update<T>): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimbu/common",
-  "version": "0.8.2",
+  "version": "0.9.2",
   "description": "Common types and objects used in many other Rimbu packages",
   "keywords": [
     "common",
@@ -38,12 +38,13 @@
   ],
   "scripts": {
     "build": "yarn clean && yarn bundle",
-    "build:deno": "rimraf deno_dist ../../deno_dist/common && denoify && cp ../../config/mod_ts_template deno_dist/mod.ts && mv deno_dist ../../deno_dist/common",
+    "build:deno": "rimraf deno_dist ../../deno_dist/common && denoify && mv deno_dist ../../deno_dist/common",
     "bundle": "yarn bundle:main && yarn bundle:module && yarn bundle:types",
     "bundle:main": "tsc --p tsconfig.main.json",
     "bundle:module": "tsc --p tsconfig.module.json",
     "bundle:types": "tsc --p tsconfig.types.json",
     "clean": "rimraf dist",
+    "extract-api": "api-extractor run --local --verbose",
     "format": "yarn format:base --write",
     "format:base": "prettier \"{!CHANGELOG.md}|**/**/*.{ts,tsx,js,json,md}\"",
     "format:check": "yarn format:base --check",
@@ -56,10 +57,11 @@
     "access": "public"
   },
   "denoify": {
+    "index": "src/index.ts",
     "replacer": "../../config/denoify-rimbu-replacer.js"
   },
   "dependencies": {
-    "tslib": "^2.3.1"
+    "tslib": "^2.4.0"
   },
-  "gitHead": "1594b907f4dbbd994a52f0e2e94ffd9217420ff5"
+  "gitHead": "33dd7ca935f19f513586834a2ce1b1f886352ae7"
 }

package/src/async-optlazy.ts

@@ -17,11 +17,13 @@ export namespace AsyncOptLazy {
    * Returns the value or promised value contained in an `AsyncOptLazy` instance of type T.
    * @param optLazy - the `AsyncOptLazy` value of type T
    * @example
+   * ```ts
    * AsyncOptLazy.toMaybePromise(1)              // => 1
    * AsyncOptLazy.toMaybePromise(() => 1)        // => 1
    * AsyncOptLazy.toMaybePromise(() => () => 1)  // => () => 1
    * AsyncOptLazy.toMaybePromise(async () => 1)  // => Promise(1)
    * AsyncOptLazy.toMaybePromise(Promise.resolve(1))  // => Promise(1)
+   * ```
    */
   export function toMaybePromise<T>(optLazy: AsyncOptLazy<T>): MaybePromise<T> {
     if (optLazy instanceof Function) return optLazy();
@@ -32,11 +34,13 @@ export namespace AsyncOptLazy {
    * Returns the value contained in an `AsyncOptLazy` instance of type T as a promise.
    * @param optLazy - the `AsyncOptLazy` value of type T
    * @example
+   * ```ts
    * AsyncOptLazy.toPromise(1)              // => Promise(1)
    * AsyncOptLazy.toPromise(() => 1)        // => Promise(1)
    * AsyncOptLazy.toPromise(() => () => 1)  // => Promise(() => 1)
    * AsyncOptLazy.toPromise(async () => 1)  // => Promise(1)
    * AsyncOptLazy.toPromise(Promise.resolve(1))  // => Promise(1)
+   * ```
    */
   export async function toPromise<T>(optLazy: AsyncOptLazy<T>): Promise<T> {
     if (optLazy instanceof Function) return optLazy();