@augment-vir/common 29.3.0 → 30.0.1

package/dist/augments/array/remove-duplicates.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare function removeDuplicates<const Entry>(originalArray: ReadonlyArray<Entry>, calculateUniqueId?: (entry: Readonly<Entry>) => unknown): Entry[];

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

@@ -0,0 +1,72 @@
+/**
+ * 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 = calculateUniqueId(entry);
+        if (grouped.get(uniqueId)) {
+            return false;
+        }
+        else {
+            grouped.set(uniqueId, entry);
+            return true;
+        }
+    });
+}

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

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

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

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,17 @@
+import { randomString } from '../random/random-string.js';
+/**
+ * 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) => {
+        return { value, sort: randomString() };
+    })
+        .sort((a, b) => a.sort.localeCompare(b.sort))
+        .map(({ value }) => value);
+}

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

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

@@ -0,0 +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/core-exports.d.ts

@@ -0,0 +1 @@
+export * from '@augment-vir/core';

package/dist/augments/core-exports.js

@@ -0,0 +1 @@
+export * from '@augment-vir/core';

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

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

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

@@ -0,0 +1,24 @@
+/**
+ * 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

@@ -0,0 +1,34 @@
+import { check } from '@augment-vir/assert';
+import { extractErrorMessage } from '@augment-vir/core';
+/**
+ * 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 new Error();
+    }
+    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

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

@@ -0,0 +1,26 @@
+/**
+ * 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

@@ -0,0 +1,24 @@
+/**
+ * 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;

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

@@ -0,0 +1,50 @@
+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();
+        if (result instanceof Promise) {
+            return result.catch((error) => {
+                if (maxRetries <= 1) {
+                    throw ensureErrorAndPrependMessage(error, 'Retry max reached');
+                }
+                else {
+                    return callWithRetries(maxRetries - 1, callback);
+                }
+            });
+        }
+        else {
+            return result;
+        }
+    }
+    catch (error) {
+        if (maxRetries <= 1) {
+            throw ensureErrorAndPrependMessage(error, 'Retry max reached');
+        }
+        else {
+            return callWithRetries(maxRetries - 1, callback);
+        }
+    }
+}

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

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