@augment-vir/common 30.0.0 → 30.0.2

package/dist/augments/array/remove-duplicates.js

@@ -1,7 +1,66 @@
-export function removeDuplicates(originalArray, calculateUniqueIdCallback) {
+/**
+ * Removes duplicates from an array. Optionally provide a callback for calculating a unique id for
+ * entries.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @example No callback
+ *
+ * ```ts
+ * import {removeDuplicates} from '@augment-vir/common';
+ *
+ * const result = removeDuplicates([
+ *     1,
+ *     1,
+ *     1,
+ *     1,
+ *     1,
+ *     2,
+ *     4,
+ * ]);
+ * // result is `[1, 2, 4]`
+ *
+ * const exampleEntry = {id: 5};
+ *
+ * const result2 = removeDuplicates([
+ *     {id: 1},
+ *     // this entry will not get filtered out because it's a new object reference
+ *     {id: 1},
+ *     exampleEntry,
+ *     // this `exampleEntry` will get filtered out because it's the same reference as the one above
+ *     exampleEntry,
+ *     {id: 4},
+ * ]);
+ * // result2 is `[{id: 1}, {id: 1}, exampleEntry, {id: 4}]`
+ * ```
+ *
+ * @example With callback
+ *
+ * ```ts
+ * import {removeDuplicates} from '@augment-vir/common';
+ *
+ * const exampleEntry = {id: 5};
+ *
+ * const result2 = removeDuplicates(
+ *     [
+ *         {id: 1},
+ *         {id: 1},
+ *         exampleEntry,
+ *         exampleEntry,
+ *         {id: 4},
+ *     ],
+ *     (entry) => entry.id,
+ * );
+ * // result2 is `[{id: 1}, exampleEntry, {id: 4}]`
+ * ```
+ *
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function removeDuplicates(originalArray, calculateUniqueId = (entry) => entry) {
     const grouped = new Map();
     return originalArray.filter((entry) => {
-        const uniqueId = calculateUniqueIdCallback(entry);
+        const uniqueId = calculateUniqueId(entry);
         if (grouped.get(uniqueId)) {
             return false;
         }

package/dist/augments/array/repeat-array.d.ts

@@ -1 +1,23 @@
+/**
+ * Repeats an array. Constructs a new array with the entries from the original repeated the given
+ * number of times.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {repeatArray} from '@augment-vir/common';
+ *
+ * const result = repeatArray(3, [
+ *     'a',
+ *     'b',
+ *     'c',
+ * ]);
+ * // result is `['a', 'b', 'c', 'a', 'b', 'c', 'a', 'b', 'c']`
+ * ```
+ *
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function repeatArray<T>(repeatCount: number, array: T[]): T[];

package/dist/augments/array/repeat-array.js

@@ -1,3 +1,25 @@
+/**
+ * Repeats an array. Constructs a new array with the entries from the original repeated the given
+ * number of times.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {repeatArray} from '@augment-vir/common';
+ *
+ * const result = repeatArray(3, [
+ *     'a',
+ *     'b',
+ *     'c',
+ * ]);
+ * // result is `['a', 'b', 'c', 'a', 'b', 'c', 'a', 'b', 'c']`
+ * ```
+ *
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function repeatArray(repeatCount, array) {
     return Array.from({ length: repeatCount }, () => [...array]).flat();
 }

package/dist/augments/array/shuffle-array.d.ts

@@ -1,2 +1,9 @@
-/** Creates a new array which is a shuffled version of the input array. */
+/**
+ * Shuffles the positions of an array's entries (without mutating the array).
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function shuffleArray<ArrayElementType>(input: ReadonlyArray<ArrayElementType>): Array<ArrayElementType>;

package/dist/augments/array/shuffle-array.js

@@ -1,5 +1,12 @@
 import { randomString } from '../random/random-string.js';
-/** Creates a new array which is a shuffled version of the input array. */
+/**
+ * Shuffles the positions of an array's entries (without mutating the array).
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function shuffleArray(input) {
     return input
         .map((value) => {

package/dist/augments/array/string-array.d.ts

@@ -1 +1,9 @@
+/**
+ * Trims all entries in an array.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function trimArrayStrings(input: ReadonlyArray<string>): string[];

package/dist/augments/array/string-array.js

@@ -1,3 +1,11 @@
+/**
+ * Trims all entries in an array.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function trimArrayStrings(input) {
     return input.map((line) => line.trim()).filter((line) => line !== '');
 }

package/dist/augments/enum/enum-value-check.d.ts

@@ -1,2 +1,32 @@
 import type { EnumBaseType } from '@augment-vir/core';
+/**
+ * Filters the input array to all valid values from the given enum.
+ *
+ * @category Array
+ * @category Enum
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * enum MyEnum {
+ *     A = 'a',
+ *     B = 'b',
+ * }
+ *
+ * const result = filterToEnumValues(
+ *     [
+ *         1,
+ *         2,
+ *         3,
+ *         'a',
+ *         'b',
+ *         MyEnum.A,
+ *     ],
+ *     MyEnum,
+ * ); // result is `[MyEnum.A, MyEnum.B, MyEnum.A]`
+ * ```
+ *
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function filterToEnumValues<const T extends EnumBaseType>(inputs: ReadonlyArray<unknown>, checkEnum: T): T[keyof T][];

package/dist/augments/enum/enum-value-check.js

@@ -1,4 +1,34 @@
 import { check } from '@augment-vir/assert';
+/**
+ * Filters the input array to all valid values from the given enum.
+ *
+ * @category Array
+ * @category Enum
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * enum MyEnum {
+ *     A = 'a',
+ *     B = 'b',
+ * }
+ *
+ * const result = filterToEnumValues(
+ *     [
+ *         1,
+ *         2,
+ *         3,
+ *         'a',
+ *         'b',
+ *         MyEnum.A,
+ *     ],
+ *     MyEnum,
+ * ); // result is `[MyEnum.A, MyEnum.B, MyEnum.A]`
+ * ```
+ *
+ * @returns A new array (does not mutate).
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function filterToEnumValues(inputs, checkEnum) {
     return inputs.filter((input) => check.isEnumValue(input, checkEnum));
 }

package/dist/augments/error/combine-errors.d.ts

@@ -1,3 +1,24 @@
-import { type AtLeastTuple } from '@augment-vir/core';
-export declare function combineErrors(errors: AtLeastTuple<Error, 1>): Error;
-export declare function combineErrors(errors: ReadonlyArray<Error | undefined>): Error | undefined;
+/**
+ * Combines an array of errors into a single array.
+ *
+ * - If no errors are in the given array, a new Error with an empty message is returned.
+ * - If only one error is in the given array, it is directly returned without modification.
+ *
+ * @category Array
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {combineErrors} from '@augment-vir/common';
+ *
+ * const result1 = combineErrors([
+ *     new Error('message 1'),
+ *     new Error('message 2'),
+ * ]); // result1 is a single error with the message 'message 1\nmessage 2'
+ * ```
+ *
+ * @returns A single error.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function combineErrors(errors: ReadonlyArray<Error>): Error;

package/dist/augments/error/combine-errors.js

@@ -1,11 +1,33 @@
 import { check } from '@augment-vir/assert';
 import { extractErrorMessage } from '@augment-vir/core';
-export function combineErrors(rawErrors) {
-    const errors = rawErrors.filter((error) => error);
+/**
+ * Combines an array of errors into a single array.
+ *
+ * - If no errors are in the given array, a new Error with an empty message is returned.
+ * - If only one error is in the given array, it is directly returned without modification.
+ *
+ * @category Array
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {combineErrors} from '@augment-vir/common';
+ *
+ * const result1 = combineErrors([
+ *     new Error('message 1'),
+ *     new Error('message 2'),
+ * ]); // result1 is a single error with the message 'message 1\nmessage 2'
+ * ```
+ *
+ * @returns A single error.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function combineErrors(errors) {
     if (!check.isLengthAtLeast(errors, 1)) {
-        return undefined;
+        return new Error();
     }
-    if (errors.length === 1) {
+    else if (errors.length === 1) {
         return errors[0];
     }
     return new Error(errors.map((error) => extractErrorMessage(error).trim()).join('\n'));

package/dist/augments/function/call-asynchronously.d.ts

@@ -2,5 +2,24 @@ import { MaybePromise } from '@augment-vir/core';
 /**
  * Call a function asynchronously without interrupting current synchronous execution, even if the
  * function was originally synchronous.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {callAsynchronously} from '@augment-vir/common';
+ *
+ * console.info('1');
+ * const later = callAsynchronously(() => {
+ *     console.info('3');
+ * });
+ * console.info('2');
+ * await later;
+ *
+ * // logs 1,2,3 in numeric order
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function callAsynchronously<T>(callback: () => MaybePromise<T>): Promise<T>;

package/dist/augments/function/call-asynchronously.js

@@ -1,6 +1,25 @@
 /**
  * Call a function asynchronously without interrupting current synchronous execution, even if the
  * function was originally synchronous.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {callAsynchronously} from '@augment-vir/common';
+ *
+ * console.info('1');
+ * const later = callAsynchronously(() => {
+ *     console.info('3');
+ * });
+ * console.info('2');
+ * await later;
+ *
+ * // logs 1,2,3 in numeric order
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export async function callAsynchronously(callback) {
     return await Promise.resolve().then(() => callback());

package/dist/augments/function/call-with-retries.d.ts

@@ -1,4 +1,24 @@
-import { MaybePromise } from '@augment-vir/core';
-export declare function callWithRetries<const T>(maxRetries: number, callback: () => Promise<T>): Promise<T>;
+/**
+ * Calls `callback` until it doesn't throw an error or throws an error when `maxRetries` is reached.
+ * Similar to the `waitUntil` guard from '@augment-vir/assert' but doesn't check the callback's
+ * output.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {callWithRetries} from '@augment-vir/common';
+ *
+ * const result = callWithRetries(5, () => {
+ *     if (Math.random() < 0.5) {
+ *         return 'done';
+ *     } else {
+ *         throw new Error();
+ *     }
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function callWithRetries<const T>(maxRetries: number, callback: () => T): T;
-export declare function callWithRetries<const T>(maxRetries: number, callback: () => MaybePromise<T>): MaybePromise<T>;

package/dist/augments/function/call-with-retries.js

@@ -1,4 +1,27 @@
 import { ensureErrorAndPrependMessage } from '@augment-vir/core';
+/**
+ * Calls `callback` until it doesn't throw an error or throws an error when `maxRetries` is reached.
+ * Similar to the `waitUntil` guard from '@augment-vir/assert' but doesn't check the callback's
+ * output.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {callWithRetries} from '@augment-vir/common';
+ *
+ * const result = callWithRetries(5, () => {
+ *     if (Math.random() < 0.5) {
+ *         return 'done';
+ *     } else {
+ *         throw new Error();
+ *     }
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function callWithRetries(maxRetries, callback) {
     try {
         const result = callback();

package/dist/augments/function/debounce.d.ts

@@ -1,22 +1,89 @@
 import { MaybePromise } from '@augment-vir/core';
 import { AnyDuration } from '@date-vir/duration';
+/**
+ * Different types of debouncing for the {@link Debounce} class.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare enum DebounceStyle {
     /**
-     * Fires on the first call, then waits the given amount of milliseconds until a subsequent call
-     * can be made.
+     * Fires on the first call, then waits the given amount of milliseconds until another call is
+     * allowed through.
+     *
+     * `.execute()` calls with a 25ms debounce time looks like this:
+     *
+     * | 1st `.execute()` | 2nd `.execute()` | 3rd `.execute()` | 4th `.execute()` |
+     * | ---------------- | ---------------- | ---------------- | ---------------- |
+     * | 0ms              | 10ms             | 20ms             | 30ms             |
+     * | fired!           |                  |                  | fired!           |
      */
     FirstThenWait = "first-then-wait",
     /**
      * Waits the given amount of milliseconds after the first call and then fires the latest
      * assigned callback.
+     *
+     * `.execute()` calls with a 25ms debounce time looks like this:
+     *
+     * | 1st `.execute()` | 2nd `.execute()` | 3rd `.execute()` | -      | 4th `.execute()` | ...    |
+     * | ---------------- | ---------------- | ---------------- | ------ | ---------------- | ------ |
+     * | 0ms              | 10ms             | 20ms             | 25ms   | 30ms             | 50ms   |
+     * |                  |                  |                  | fired! |                  | fired! |
      */
     AfterWait = "after-wait"
 }
+/**
+ * Enable debouncing of callbacks, with various styles of debounce supported in {@link DebounceStyle}
+ * (see its docs for debounce style details). A callback can be provided on construction or to the
+ * `.execute()` method.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {Debounce} from '@augment-vir/common';
+ *
+ * const debounce = new Debounce(
+ *     DebounceStyle.FirstThenWait,
+ *     {
+ *         milliseconds: 500,
+ *     },
+ *     // callback can optionally be provided on construction
+ *     () => {
+ *         console.log('called');
+ *     },
+ * );
+ *
+ * debounce.execute();
+ * // providing a callback in `.execute()` permanently overrides the callback provided in construction.
+ * debounce.execute(() => {});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare class Debounce {
+    /** Debounce style. See {@link DebounceStyle} for more details. */
     debounceStyle: DebounceStyle;
+    /** Duration between debounces. */
     debounceDuration: AnyDuration;
+    /**
+     * Set the callback to be triggered on `.execute()`. If this is not set, the callback to be
+     * called can be passed in `.execute()` instead.
+     */
+    callback?: (() => MaybePromise<void>) | undefined;
     nextCallTimestamp: number;
-    callback: (() => MaybePromise<void>) | undefined;
-    constructor(debounceStyle: DebounceStyle, debounceDuration: AnyDuration, callback?: typeof this.callback | undefined);
+    constructor(
+    /** Debounce style. See {@link DebounceStyle} for more details. */
+    debounceStyle: DebounceStyle, 
+    /** Duration between debounces. */
+    debounceDuration: AnyDuration, 
+    /**
+     * Set the callback to be triggered on `.execute()`. If this is not set, the callback to be
+     * called can be passed in `.execute()` instead.
+     */
+    callback?: (() => MaybePromise<void>) | undefined);
+    /** Call the callback, if one has been set yet, if the current debounce timer is up. */
     execute(callback?: typeof this.callback | undefined): void;
 }

package/dist/augments/function/debounce.js

@@ -1,29 +1,91 @@
 import { convertDuration, DurationUnit } from '@date-vir/duration';
+/**
+ * Different types of debouncing for the {@link Debounce} class.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export var DebounceStyle;
 (function (DebounceStyle) {
     /**
-     * Fires on the first call, then waits the given amount of milliseconds until a subsequent call
-     * can be made.
+     * Fires on the first call, then waits the given amount of milliseconds until another call is
+     * allowed through.
+     *
+     * `.execute()` calls with a 25ms debounce time looks like this:
+     *
+     * | 1st `.execute()` | 2nd `.execute()` | 3rd `.execute()` | 4th `.execute()` |
+     * | ---------------- | ---------------- | ---------------- | ---------------- |
+     * | 0ms              | 10ms             | 20ms             | 30ms             |
+     * | fired!           |                  |                  | fired!           |
      */
     DebounceStyle["FirstThenWait"] = "first-then-wait";
     /**
      * Waits the given amount of milliseconds after the first call and then fires the latest
      * assigned callback.
+     *
+     * `.execute()` calls with a 25ms debounce time looks like this:
+     *
+     * | 1st `.execute()` | 2nd `.execute()` | 3rd `.execute()` | -      | 4th `.execute()` | ...    |
+     * | ---------------- | ---------------- | ---------------- | ------ | ---------------- | ------ |
+     * | 0ms              | 10ms             | 20ms             | 25ms   | 30ms             | 50ms   |
+     * |                  |                  |                  | fired! |                  | fired! |
      */
     DebounceStyle["AfterWait"] = "after-wait";
 })(DebounceStyle || (DebounceStyle = {}));
+/**
+ * Enable debouncing of callbacks, with various styles of debounce supported in {@link DebounceStyle}
+ * (see its docs for debounce style details). A callback can be provided on construction or to the
+ * `.execute()` method.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {Debounce} from '@augment-vir/common';
+ *
+ * const debounce = new Debounce(
+ *     DebounceStyle.FirstThenWait,
+ *     {
+ *         milliseconds: 500,
+ *     },
+ *     // callback can optionally be provided on construction
+ *     () => {
+ *         console.log('called');
+ *     },
+ * );
+ *
+ * debounce.execute();
+ * // providing a callback in `.execute()` permanently overrides the callback provided in construction.
+ * debounce.execute(() => {});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export class Debounce {
     debounceStyle;
     debounceDuration;
-    nextCallTimestamp = 0;
     callback;
-    constructor(debounceStyle, debounceDuration, callback) {
+    nextCallTimestamp = 0;
+    constructor(
+    /** Debounce style. See {@link DebounceStyle} for more details. */
+    debounceStyle, 
+    /** Duration between debounces. */
+    debounceDuration, 
+    /**
+     * Set the callback to be triggered on `.execute()`. If this is not set, the callback to be
+     * called can be passed in `.execute()` instead.
+     */
+    callback) {
         this.debounceStyle = debounceStyle;
         this.debounceDuration = debounceDuration;
+        this.callback = callback;
         if (callback) {
             this.callback = callback;
         }
     }
+    /** Call the callback, if one has been set yet, if the current debounce timer is up. */
     execute(callback) {
         if (callback) {
             this.callback = callback;

package/dist/augments/function/execution-duration.d.ts

@@ -1,8 +1,20 @@
 import { Duration, DurationUnit } from '@date-vir/duration';
-export type ExecutionDuration = Duration<DurationUnit.Milliseconds>;
 /**
- * Measures how long (in milliseconds) the given callback takes to run to completion. Automatically
- * switches to async mode and awaits callbacks if they return a promise (otherwise this function is
- * purely synchronous).
+ * Measures how long (in milliseconds) the given callback takes to run to completion. By default
+ * this is synchronous, but it will automatically switch to async and await the callback if it
+ * returns a promise.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {measureExecutionDuration} from '@augment-vir/common';
+ *
+ * const duration1 = measureExecutionDuration(() => {});
+ * const duration2 = await measureExecutionDuration(async () => {});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export declare function measureExecutionDuration<T>(callback: () => T): T extends Promise<any> ? Promise<ExecutionDuration> : ExecutionDuration;
+export declare function measureExecutionDuration<T>(callback: () => T): T extends Promise<any> ? Promise<Duration<DurationUnit.Milliseconds>> : Duration<DurationUnit.Milliseconds>;

package/dist/augments/function/execution-duration.js

@@ -1,8 +1,21 @@
 import { ensureError } from '@augment-vir/core';
 /**
- * Measures how long (in milliseconds) the given callback takes to run to completion. Automatically
- * switches to async mode and awaits callbacks if they return a promise (otherwise this function is
- * purely synchronous).
+ * Measures how long (in milliseconds) the given callback takes to run to completion. By default
+ * this is synchronous, but it will automatically switch to async and await the callback if it
+ * returns a promise.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {measureExecutionDuration} from '@augment-vir/common';
+ *
+ * const duration1 = measureExecutionDuration(() => {});
+ * const duration2 = await measureExecutionDuration(async () => {});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function measureExecutionDuration(callback) {
     const startTime = Date.now();