@augment-vir/common 29.3.0 → 30.0.1

package/dist/augments/function/debounce.js

@@ -0,0 +1,112 @@
+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 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;
+    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;
+        }
+        else if (!this.callback) {
+            return;
+        }
+        const now = Date.now();
+        if (this.nextCallTimestamp > now) {
+            return;
+        }
+        if (this.debounceStyle === DebounceStyle.FirstThenWait) {
+            void this.callback();
+        }
+        else {
+            setTimeout(() => {
+                /** Use whatever the latest latestCallback is. */
+                void this.callback?.();
+            }, this.debounceDuration.milliseconds);
+        }
+        this.nextCallTimestamp =
+            now + convertDuration(this.debounceDuration, DurationUnit.Milliseconds).milliseconds;
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Duration, DurationUnit } from '@date-vir/duration';
+/**
+ * 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<Duration<DurationUnit.Milliseconds>> : Duration<DurationUnit.Milliseconds>;

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

@@ -0,0 +1,39 @@
+import { ensureError } from '@augment-vir/core';
+/**
+ * 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();
+    const result = callback();
+    if (result instanceof Promise) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                await result;
+                const endTime = Date.now();
+                resolve({ milliseconds: endTime - startTime });
+            }
+            catch (caught) {
+                reject(ensureError(caught));
+            }
+        });
+    }
+    const endTime = Date.now();
+    return {
+        milliseconds: endTime - startTime,
+    };
+}

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/{types/augments → augments/function}/wrap-in-try.d.ts

@@ -1,14 +1,21 @@
-import { NoInputsFunction } from './function';
-import { PartialAndUndefined } from './object/object';
-export type WrapInTryOptions<FallbackValue> = PartialAndUndefined<{
+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;
 }>;

package/dist/augments/function/wrap-in-try.js

@@ -0,0 +1,98 @@
+import { check } from '@augment-vir/assert';
+import { ensureError, } from '@augment-vir/core';
+/**
+ * Calls the callback and returns its output. If the callback throws an error, it is handled in the
+ * following ways:
+ *
+ * - If a `handleError` function is provided in `options`, it is passed the thrown error. The output
+ *   of `handleError` is returned by `wrapInTry`.
+ * - If a `fallbackValue` is provided, it is returned by `wrapInTry`. The thrown error is ignored.
+ * - If no options are provided, the thrown error is returned by `wrapInTry`.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {wrapInTry} from '@augment-vir/common';
+ *
+ * // `result1` will be `'success'`.
+ * const result1 = wrapInTry(
+ *     () => {
+ *         return 'success';
+ *     },
+ *     {
+ *         fallbackValue: 'failure',
+ *     },
+ * );
+ * // `result2` will be `'failure'`.
+ * const result2 = wrapInTry(
+ *     () => {
+ *         throw new Error();
+ *         return 'success';
+ *     },
+ *     {
+ *         fallbackValue: 'failure',
+ *     },
+ * );
+ * // `result3` will be `'failure also'`.
+ * const result3 = wrapInTry(
+ *     () => {
+ *         throw new Error();
+ *         return 'success';
+ *     },
+ *     {
+ *         handleError() {
+ *             return 'failure also';
+ *         },
+ *     },
+ * );
+ * // `result4` will be `'failure also'`.
+ * const result4 = wrapInTry(
+ *     () => {
+ *         throw new Error();
+ *         return 'success';
+ *     },
+ *     {
+ *         handleError() {
+ *             return 'failure also';
+ *         },
+ *         fallbackValue: 'ignored',
+ *     },
+ * );
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function wrapInTry(callback, options = {}) {
+    try {
+        const value = callback();
+        if (value instanceof Promise) {
+            return value.catch((error) => {
+                if (options.handleError) {
+                    return options.handleError(error);
+                }
+                else if (check.hasKey(options, 'fallbackValue')) {
+                    return options.fallbackValue;
+                }
+                else {
+                    return ensureError(error);
+                }
+            });
+        }
+        else {
+            return value;
+        }
+    }
+    catch (error) {
+        if (options.handleError) {
+            return options.handleError(error);
+        }
+        else if (check.hasKey(options, 'fallbackValue')) {
+            return options.fallbackValue;
+        }
+        else {
+            return ensureError(error);
+        }
+    }
+}

package/dist/augments/json/append-json.d.ts

@@ -0,0 +1,5 @@
+import type { JsonCompatibleArray, JsonCompatibleObject, JsonCompatibleValue } from './json-compatible.js';
+import { JsonCompatiblePrimitive } from './json-compatible.js';
+export declare function appendJson(entry: JsonCompatibleArray | JsonCompatiblePrimitive, ...entries: ReadonlyArray<JsonCompatibleValue | undefined>): JsonCompatibleArray;
+export declare function appendJson(entry: JsonCompatibleObject, ...entries: ReadonlyArray<JsonCompatibleObject | JsonCompatibleArray | undefined>): JsonCompatibleObject;
+export declare function appendJson(...entries: ReadonlyArray<JsonCompatibleValue | undefined>): JsonCompatibleObject | JsonCompatibleArray;

package/dist/augments/json/append-json.js

@@ -0,0 +1,59 @@
+import { check } from '@augment-vir/assert';
+import { copyThroughJson } from './copy-through-json.js';
+/**
+ * Appends all provided JSON values together. `undefined` values will be ignored. The first value
+ * determines whether the output will be an object or an array. Any value appended to an array will
+ * work just fine, but primitives append to an object will likely behave unexpectedly. Arrays
+ * appended to arrays will be flattened (but only by one level).
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {appendJson} from '@augment-vir/common';
+ *
+ * // `result1` will be `{a: 'q', b: 'b'}`
+ * const result1 = appendJson({a: 'a'}, {b: 'b'}, {a: 'q'});
+ * // `result2` will be `[{a: 'a'}, {b: 'b'}, {a: 'q'}, 'r']`
+ * const result2 = appendJson([{a: 'a'}], {b: 'b'}, {a: 'q'}, 'r');
+ * // `result3` will be `['a', ['b', 'c'], 'd', 'e']`
+ * const result3 = appendJson(
+ *     ['a'],
+ *     [
+ *         [
+ *             'b',
+ *             'c',
+ *         ],
+ *     ],
+ *     ['d'],
+ *     'e',
+ * );
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function appendJson(...rawEntries) {
+    const entries = rawEntries.filter(check.isTruthy);
+    if (!check.isLengthAtLeast(entries, 1)) {
+        return {};
+    }
+    const firstEntry = copyThroughJson(entries[0]);
+    const combinedData = typeof firstEntry === 'object'
+        ? firstEntry
+        : [firstEntry];
+    entries.slice(1).forEach((entry) => {
+        if (check.isArray(combinedData)) {
+            if (check.isArray(entry)) {
+                combinedData.push(...entry);
+            }
+            else {
+                combinedData.push(entry);
+            }
+        }
+        else {
+            Object.assign(combinedData, entry);
+        }
+    });
+    return combinedData;
+}

package/dist/augments/json/copy-through-json.d.ts

@@ -0,0 +1,34 @@
+import { Jsonify, Writable } from 'type-fest';
+/**
+ * Deeply copy an object through JSON. This is the fastest deep copy, but the input must already be
+ * JSON serializable otherwise the copy will not match the original.
+ *
+ * @category JSON : Common
+ * @category Copy
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {copyThroughJson} from '@augment-vir/common';
+ *
+ * // `copy1` will be `{a: 'a', b: 'b'}`
+ * const copy1 = copyThroughJson({a: 'a', b: 'b'});
+ * // `copy2` will be `{map: {}, b: 'b'}`
+ * const copy2 = copyThroughJson({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function copyThroughJson<const T>(input: T): Writable<Jsonify<T>>;

package/dist/augments/json/copy-through-json.js

@@ -0,0 +1,42 @@
+/**
+ * Deeply copy an object through JSON. This is the fastest deep copy, but the input must already be
+ * JSON serializable otherwise the copy will not match the original.
+ *
+ * @category JSON : Common
+ * @category Copy
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {copyThroughJson} from '@augment-vir/common';
+ *
+ * // `copy1` will be `{a: 'a', b: 'b'}`
+ * const copy1 = copyThroughJson({a: 'a', b: 'b'});
+ * // `copy2` will be `{map: {}, b: 'b'}`
+ * const copy2 = copyThroughJson({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function copyThroughJson(input) {
+    try {
+        return JSON.parse(JSON.stringify(input));
+        /* node:coverage ignore next 4 */
+    }
+    catch (error) {
+        console.error(`Failed to JSON copy for`, input);
+        throw error;
+    }
+}

package/dist/augments/json/json-compatible.d.ts

@@ -0,0 +1,50 @@
+import { Jsonify, Primitive } from 'type-fest';
+/**
+ * These are similar in purpose, name, and structure to type-fest's JsonValue types but these are
+ * more permissive. The goal here is to allow any types that do not get serialized into just empty
+ * objects. (For example, JSON.stringify(new Map()) returns "{}", so we don't want to allow that
+ * type.)
+ */
+/**
+ * All primitives that are allowed in JSON.
+ *
+ * Note that while `undefined` is allowed here, it will be behave slightly differently than the
+ * others.
+ *
+ * - `JSON.stringify(undefined)` will output `undefined`, not a string.
+ * - `JSON.stringify({a: null, b: undefined})` will output `'{"a": null}'`, omitting the `b` key
+ *   entirely.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type JsonCompatiblePrimitive = Jsonify<Primitive> | undefined;
+/**
+ * An object that only contains JSON compatible values.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type JsonCompatibleObject = Partial<{
+    readonly [key: string | number]: JsonCompatibleValue | Readonly<JsonCompatibleValue>;
+}> | Partial<{
+    [key: string | number]: JsonCompatibleValue | Readonly<JsonCompatibleValue>;
+}>;
+/**
+ * An array that only contains JSON compatible values.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type JsonCompatibleArray = JsonCompatibleValue[] | ReadonlyArray<JsonCompatibleValue>;
+/**
+ * Any JSON compatible value.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type JsonCompatibleValue = JsonCompatiblePrimitive | JsonCompatibleObject | JsonCompatibleArray;

package/dist/augments/json/jsonify.d.ts

@@ -0,0 +1,31 @@
+import { Jsonify } from 'type-fest';
+/**
+ * Creates a JSON compatible version of the value given. Under the hood this is actually the same as
+ * {@link copyThroughJson}.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {jsonify} from '@augment-vir/common';
+ *
+ * // `result` is `{b: 'b'}`
+ * const result = jsonify({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function jsonify<T>(value: T): Jsonify<T>;

package/dist/augments/json/jsonify.js

@@ -0,0 +1,33 @@
+import JSON5 from 'json5';
+/**
+ * Creates a JSON compatible version of the value given. Under the hood this is actually the same as
+ * {@link copyThroughJson}.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {jsonify} from '@augment-vir/common';
+ *
+ * // `result` is `{b: 'b'}`
+ * const result = jsonify({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function jsonify(value) {
+    return JSON5.parse(JSON5.stringify(value));
+}