@augment-vir/common 30.0.0 → 30.0.1

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();

package/dist/augments/function/if-truthy.d.ts

@@ -0,0 +1,28 @@
+import { type Falsy, type Truthy } from '@augment-vir/assert';
+/**
+ * Checks an input for truthiness then calls the respective callback, returning the callback's
+ * output.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {ifTruthy} from '@augment-vir/common';
+ *
+ * const result1 = ifTruthy(
+ *     true,
+ *     () => 1,
+ *     () => 2,
+ * ); // result1 is `1`
+ * const result2 = ifTruthy(
+ *     false,
+ *     () => 1,
+ *     () => 2,
+ * ); // result2 is `2`
+ * ```
+ *
+ * @returns The called callback's output.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function ifTruthy<const InputType, IfTruthyType, IfFalsyType>(checkThis: InputType, ifTruthyCallback: (truthyInput: Truthy<InputType>) => IfTruthyType, ifFalsyCallback: (truthyInput: Falsy<InputType>) => IfFalsyType): IfTruthyType | IfFalsyType;

package/dist/augments/function/if-truthy.js

@@ -0,0 +1,35 @@
+import { check } from '@augment-vir/assert';
+/**
+ * Checks an input for truthiness then calls the respective callback, returning the callback's
+ * output.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {ifTruthy} from '@augment-vir/common';
+ *
+ * const result1 = ifTruthy(
+ *     true,
+ *     () => 1,
+ *     () => 2,
+ * ); // result1 is `1`
+ * const result2 = ifTruthy(
+ *     false,
+ *     () => 1,
+ *     () => 2,
+ * ); // result2 is `2`
+ * ```
+ *
+ * @returns The called callback's output.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function ifTruthy(checkThis, ifTruthyCallback, ifFalsyCallback) {
+    if (check.isTruthy(checkThis)) {
+        return ifTruthyCallback(checkThis);
+    }
+    else {
+        return ifFalsyCallback(checkThis);
+    }
+}

package/dist/augments/function/wrap-in-try.d.ts

@@ -1,13 +1,21 @@
 import { type NoInputsFunction, type PartialWithUndefined } from '@augment-vir/core';
+/**
+ * Options for {@link wrapInTry}.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type WrapInTryOptions<FallbackValue> = PartialWithUndefined<{
     /**
-     * A callback that is passed the error. The output of this callback is returned by `wrapInTry`.
-     * This takes precedence over the other two options.
+     * Call this function if the callback passed to {@link wrapInTry} throws an error. The thrown
+     * error is passed to this function. If a `fallbackValue` option is also provided, it will be
+     * ignored.
      */
     handleError: (error: unknown) => FallbackValue;
     /**
-     * Fallback to this value if the callback passed to `wrapInTry` throws an error. Takes
-     * precedence over `returnError`.
+     * Fallback to this value if the callback passed to {@link wrapInTry} throws an error. This will
+     * be ignored if a `handleError` option is also set.
      */
     fallbackValue: FallbackValue;
 }>;