@augment-vir/common 29.2.0 → 30.0.0

package/dist/esm/augments/object/selection-set.js

@@ -1,52 +0,0 @@
-import { isPrimitive } from 'run-time-assertions';
-import { isLengthAtLeast } from '../tuple';
-import { omitObjectKeys } from './filter-object';
-import { mapObjectValues } from './map-object';
-import { isObject } from './object';
-function shouldPreserve(input) {
-    return isPrimitive(input) || input instanceof RegExp || input instanceof Promise;
-}
-export function selectFrom(originalObject, selectionSet) {
-    if (Array.isArray(originalObject)) {
-        return originalObject.map((originalEntry) => selectFrom(originalEntry, selectionSet));
-    }
-    const keysToRemove = [];
-    return omitObjectKeys(mapObjectValues(originalObject, (key, value) => {
-        const selection = selectionSet[key];
-        if (selection === true) {
-            return value;
-        }
-        else if (!selection) {
-            keysToRemove.push(key);
-            return undefined;
-        }
-        else if (shouldPreserve(value)) {
-            return value;
-        }
-        else {
-            return selectFrom(value, selection);
-        }
-    }), keysToRemove);
-}
-export function selectCollapsedFrom(originalObject, selectionSet) {
-    const selected = selectFrom(originalObject, selectionSet);
-    return collapseObject(selected, selectionSet);
-}
-function collapseObject(input, selectionSet) {
-    if (shouldPreserve(input)) {
-        return input;
-    }
-    const keys = Object.keys(input);
-    if (Array.isArray(input)) {
-        return input.map((innerInput) => collapseObject(innerInput, selectionSet));
-    }
-    else if (isLengthAtLeast(keys, 2)) {
-        return input;
-    }
-    else if (isLengthAtLeast(keys, 1) && isObject(selectionSet)) {
-        return collapseObject(input[keys[0]], selectionSet[keys[0]]);
-    }
-    else {
-        return input;
-    }
-}

package/dist/esm/augments/object/typed-has-property.js

@@ -1,25 +0,0 @@
-const hasPropertyAttempts = [
-    (object, key) => {
-        return key in object;
-    },
-    (object, key) => {
-        /** This handles cases where the input object can't use `in` directly, like string literals */
-        return key in object.constructor.prototype;
-    },
-];
-export function typedHasProperty(inputObject, inputKey) {
-    if (!inputObject) {
-        return false;
-    }
-    return hasPropertyAttempts.some((attemptCallback) => {
-        try {
-            return attemptCallback(inputObject, inputKey);
-        }
-        catch (error) {
-            return false;
-        }
-    });
-}
-export function typedHasProperties(inputObject, inputKeys) {
-    return inputObject && inputKeys.every((key) => typedHasProperty(inputObject, key));
-}

package/dist/esm/augments/promise/deferred-promise.js

@@ -1,28 +0,0 @@
-export function createDeferredPromiseWrapper() {
-    let resolve;
-    let reject;
-    let settled = false;
-    const promise = new Promise((resolveCallback, rejectCallback) => {
-        resolve = (value) => {
-            settled = true;
-            return resolveCallback(value);
-        };
-        reject = (reason) => {
-            settled = true;
-            rejectCallback(reason);
-        };
-    });
-    // no way to test this edge case
-    // istanbul ignore next
-    if (!resolve || !reject) {
-        throw new Error(`Reject and resolve callbacks were not set by the promise constructor for ${createDeferredPromiseWrapper.name}.`);
-    }
-    return {
-        promise,
-        resolve,
-        reject,
-        isSettled() {
-            return settled;
-        },
-    };
-}

package/dist/esm/augments/promise/promise.js

@@ -1,71 +0,0 @@
-import { typedHasProperty } from '../object/typed-has-property';
-export function isPromiseLike(input) {
-    if (typedHasProperty(input, 'then') && typeof input.then === 'function') {
-        return true;
-    }
-    else {
-        return false;
-    }
-}
-export class PromiseTimeoutError extends Error {
-    constructor(durationMs, message = `Promised timed out after ${durationMs} ms.`) {
-        super(message);
-        Object.defineProperty(this, "durationMs", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: durationMs
-        });
-        Object.defineProperty(this, "message", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: message
-        });
-        Object.defineProperty(this, "name", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: 'PromiseTimeoutError'
-        });
-    }
-}
-export function wrapPromiseInTimeout(durationMs, originalPromise) {
-    return new Promise(async (resolve, reject) => {
-        const timeoutId = durationMs === Infinity
-            ? undefined
-            : setTimeout(() => {
-                reject(new PromiseTimeoutError(durationMs));
-            }, durationMs);
-        try {
-            const result = await originalPromise;
-            resolve(result);
-        }
-        catch (error) {
-            reject(error);
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-    });
-}
-/**
- * Call a function asynchronously without interrupting current synchronous execution, even if the
- * function was originally synchronous.
- */
-export async function callAsynchronously(callback) {
-    return await Promise.resolve().then(() => callback());
-}
-export async function executeWithRetries(retryCount, callback) {
-    let currentRetry = 0;
-    while (currentRetry < retryCount) {
-        try {
-            const result = await callback();
-            return result;
-        }
-        catch (error) {
-            currentRetry++;
-        }
-    }
-    throw new Error('Retry max reached.');
-}

package/dist/esm/augments/promise/wait.js

@@ -1,60 +0,0 @@
-import { ensureErrorAndPrependMessage } from '../error';
-import { createDeferredPromiseWrapper } from './deferred-promise';
-export function wait(delayMs) {
-    const deferredPromiseWrapper = createDeferredPromiseWrapper();
-    if (delayMs !== Infinity) {
-        setTimeout(() => {
-            deferredPromiseWrapper.resolve();
-        }, delayMs <= 0 ? 0 : delayMs);
-    }
-    return deferredPromiseWrapper.promise;
-}
-export async function waitValue(delayMs, returnValue) {
-    return wait(delayMs).then(() => returnValue);
-}
-export const defaultWaitUntilDefinedOptions = {
-    interval: {
-        milliseconds: 100,
-    },
-    timeout: {
-        milliseconds: 10_000,
-    },
-};
-/**
- * Runs the predicate until it returns a truthy value, then returns that value. Use the options
- * input to modify the timeout and interval durations. Automatically catches errors and handles
- * async predicates.
- */
-export async function waitUntilTruthy(predicate, failureMessage, optionsInput = {}) {
-    const options = {
-        ...defaultWaitUntilDefinedOptions,
-        ...optionsInput,
-    };
-    let lastValue = undefined;
-    let lastError;
-    async function checkCondition() {
-        try {
-            lastValue = await predicate();
-        }
-        catch (error) {
-            lastValue = undefined;
-            lastError = error;
-        }
-    }
-    const startTime = Date.now();
-    while (!lastValue) {
-        await checkCondition();
-        await wait(options.interval.milliseconds);
-        if (Date.now() - startTime >= options.timeout.milliseconds) {
-            const message = failureMessage ? `${failureMessage}: ` : '';
-            const preMessage = `${message}Timeout of "${options.timeout.milliseconds}" exceeded waiting for value to be defined`;
-            if (lastError) {
-                throw ensureErrorAndPrependMessage(lastError, preMessage);
-            }
-            else {
-                throw new Error(preMessage);
-            }
-        }
-    }
-    return lastValue;
-}

package/dist/esm/augments/random.js

@@ -1,117 +0,0 @@
-import { clamp, ensureMinAndMax } from './common-number';
-function accessCrypto() {
-    if (globalThis.crypto) {
-        return globalThis.crypto;
-    }
-    else {
-        return require('crypto').webcrypto;
-    }
-}
-const crypto = accessCrypto();
-/**
- * Creates a random integer (decimal points are all cut off) between the given min and max
- * (inclusive).
- *
- * This function uses cryptographically secure randomness.
- */
-export function randomInteger({ min: rawMin, max: rawMax }) {
-    const { min, max } = ensureMinAndMax({ min: Math.floor(rawMin), max: Math.floor(rawMax) });
-    const range = max - min + 1;
-    const neededByteCount = Math.ceil(Math.log2(range) / 8);
-    const cutoff = Math.floor(256 ** neededByteCount / range) * range;
-    const currentBytes = new Uint8Array(neededByteCount);
-    let value;
-    do {
-        crypto.getRandomValues(currentBytes);
-        value = currentBytes.reduce((accum, byte, index) => {
-            return accum + byte * 256 ** index;
-        }, 0);
-    } while (value >= cutoff);
-    return min + (value % range);
-}
-/**
- * Returns true at rate of the percentLikelyToBeTrue input. Inputs should be whole numbers which
- * will be treated like percents. Anything outside of 0-100 inclusively will be clamped. An input 0
- * will always return true. An input of 100 will always return true. Decimals on the input will be
- * chopped off, use whole numbers.
- *
- * This function uses cryptographically secure randomness.
- *
- * @example
- *     randomBoolean(50); // 50% chance to return true
- *
- * @example
- *     randomBoolean(0); // always false, 0% chance of being true
- *
- * @example
- *     randomBoolean(100); // always true, 100% chance of being true
- *
- * @example
- *     randomBoolean(59.67; // 59% chance of being true
- */
-export function randomBoolean(percentLikelyToBeTrue = 50) {
-    return (randomInteger({ min: 0, max: 99 }) <
-        clamp({
-            value: Math.floor(percentLikelyToBeTrue),
-            min: 0,
-            max: 100,
-        }));
-}
-/** Creates a cryptographically secure uuid. */
-export function createUuid() {
-    return crypto.randomUUID();
-}
-const validStringCharacters = [
-    'a',
-    'b',
-    'c',
-    'd',
-    'e',
-    'f',
-    'g',
-    'h',
-    'i',
-    'j',
-    'k',
-    'l',
-    'm',
-    'n',
-    'o',
-    'p',
-    'q',
-    'r',
-    's',
-    't',
-    'u',
-    'v',
-    'w',
-    'x',
-    'y',
-    'z',
-    0,
-    1,
-    2,
-    3,
-    4,
-    5,
-    6,
-    7,
-    8,
-    9,
-];
-/**
- * Creates a random string (including letters and numbers) of a given length.
- *
- * This function uses cryptographically secure randomness.
- */
-export function randomString(inputLength = 16) {
-    let stringBuilder = '';
-    for (let i = 0; i < inputLength; i++) {
-        const index = randomInteger({
-            min: 0,
-            max: validStringCharacters.length - 1,
-        });
-        stringBuilder += validStringCharacters[index];
-    }
-    return stringBuilder;
-}

package/dist/esm/augments/regexp.js

@@ -1,14 +0,0 @@
-export function deDupeRegExFlags(flags) {
-    const deDuped = new Set(Array.from(flags.toLowerCase()));
-    return Array.from(deDuped).join('');
-}
-export function addRegExpFlags(originalRegExp, flags) {
-    return new RegExp(originalRegExp.source, deDupeRegExFlags([
-        originalRegExp.flags,
-        flags,
-    ].join('')));
-}
-export function safeMatch(input, regExp) {
-    const match = input.match(regExp);
-    return match ?? [];
-}

package/dist/esm/augments/string/suffixes.js

@@ -1,31 +0,0 @@
-import { toEnsuredNumber } from '../common-number';
-export const percentSuffix = '%';
-export const pxSuffix = 'px';
-export function addPx(input) {
-    return addSuffix({ value: input, suffix: pxSuffix });
-}
-export function removePx(input) {
-    return toEnsuredNumber(removeSuffix({ value: input, suffix: pxSuffix }));
-}
-export function addPercent(input) {
-    return addSuffix({ value: input, suffix: percentSuffix });
-}
-export function removePercent(input) {
-    return toEnsuredNumber(removeSuffix({ value: input, suffix: percentSuffix }));
-}
-export function addSuffix({ value, suffix, }) {
-    if (String(value).endsWith(suffix)) {
-        return String(value);
-    }
-    else {
-        return `${String(value)}${suffix}`;
-    }
-}
-export function removeSuffix({ value, suffix, }) {
-    if (value.endsWith(suffix)) {
-        return value.substring(0, value.length - suffix.length);
-    }
-    else {
-        return value;
-    }
-}

package/dist/esm/augments/string/uuid.js

@@ -1,4 +0,0 @@
-const uuidRegExp = /[\d\w]{8}-[\d\w]{4}-[\d\w]{4}-[\d\w]{4}-[\d\w]{12}/;
-export function isUuid(maybeUuid) {
-    return !!maybeUuid.match(uuidRegExp);
-}

package/dist/esm/augments/tuple.js

@@ -1,16 +0,0 @@
-export function isLengthAtLeast(array, length) {
-    try {
-        assertLengthAtLeast(array, length);
-        return true;
-    }
-    catch (error) {
-        return false;
-    }
-}
-export function assertLengthAtLeast(array, length, arrayName) {
-    if (array.length < length) {
-        throw new Error(arrayName
-            ? `'${arrayName}' is not at least '${length}' in length.`
-            : `Array is not at least '${length}' in length.`);
-    }
-}

package/dist/esm/augments/type.js

@@ -1,30 +0,0 @@
-export function makeWritable(input) {
-    return input;
-}
-export function makeReadonly(input) {
-    return input;
-}
-/**
- * This function returns another function that simply returns whatever input it's given. However, it
- * also checks that the input matches the original wrapNarrowTypeWithTypeCheck's generic, while
- * maintaining strict "const" like typing.
- *
- * Use like this: wrapNarrowTypeWithTypeCheck<EnforcedTypeHere>()(valueToEnforceTypeOn as const)
- *
- * Sometimes "as const" isn't required, usually it is for any object or array though.
- */
-export function wrapNarrowTypeWithTypeCheck() {
-    return (input) => {
-        return input;
-    };
-}
-/**
- * This is a type helper that ensures the given input matches the given generic type. The generic is
- * setup in such a way that if it is omitted (which is typically allowed in TypeScript, resulting in
- * the generic being inferred from the inputs), there will actually be a type error. This forces
- * each usage of this function to explicitly specify the generic, thus giving us type safety for the
- * input.
- */
-export function ensureType(input) {
-    return input;
-}

package/dist/esm/index.js

@@ -1,44 +0,0 @@
-export * from './augments/ansi';
-export * from './augments/array/array';
-export * from './augments/array/remove-duplicates';
-export * from './augments/async';
-export * from './augments/boolean';
-export * from './augments/common-number';
-export * from './augments/common-string';
-export * from './augments/debounce';
-export * from './augments/environment';
-export * from './augments/error';
-export * from './augments/esm-path';
-export * from './augments/function';
-export * from './augments/json';
-export * from './augments/json-compatible';
-export * from './augments/object/any-object';
-export * from './augments/object/enum';
-export * from './augments/object/filter-object';
-export * from './augments/object/get-or-set';
-export * from './augments/object/has-key';
-export * from './augments/object/jsonify';
-export * from './augments/object/key-count';
-export * from './augments/object/map-object';
-export * from './augments/object/merge-deep';
-export * from './augments/object/merge-property-arrays';
-export * from './augments/object/object';
-export * from './augments/object/object-entries';
-export * from './augments/object/pick-deep';
-export * from './augments/object/selection-set';
-export * from './augments/object/typed-has-property';
-export * from './augments/promise/deferred-promise';
-export * from './augments/promise/promise';
-export * from './augments/promise/wait';
-export * from './augments/random';
-export * from './augments/regexp';
-export * from './augments/string/prefixes';
-export * from './augments/string/suffixes';
-export * from './augments/string/uuid';
-export * from './augments/time';
-export * from './augments/truncate-number';
-export * from './augments/tuple';
-export * from './augments/type';
-export * from './augments/type-recursion';
-export * from './augments/union';
-export * from './augments/wrap-in-try';

package/dist/types/augments/ansi.d.ts

@@ -1 +0,0 @@
-export declare const ansiRegex: RegExp;

package/dist/types/augments/array/array.d.ts

@@ -1,26 +0,0 @@
-import { AtLeastTuple } from '../tuple';
-import { ArrayElement } from '../type';
-export declare function filterOutIndexes<T>(array: ReadonlyArray<T>, indexes: ReadonlyArray<number>): T[];
-export declare function flatten2dArray<T>(array2d: ReadonlyArray<ReadonlyArray<T>>): T[];
-export type AtLeastOneEntryArray<ArrayGeneric extends ReadonlyArray<any>> = AtLeastTuple<ArrayElement<ArrayGeneric>, 1>;
-export declare function trimArrayStrings(input: ReadonlyArray<string>): string[];
-export declare function typedArrayIncludes<T>(array: ReadonlyArray<T>, input: unknown): input is T;
-type MapCallbackType<ArrayType extends ReadonlyArray<any>, OutputType> = (value: ArrayElement<ArrayType>, index: number, array: ArrayType) => OutputType;
-/** Preserves tuple types. */
-export declare function typedMap<InputArrayGeneric extends ReadonlyArray<any>, OutputType>(arrayToMap: InputArrayGeneric, mapCallback: MapCallbackType<InputArrayGeneric, OutputType>): {
-    [Index in keyof InputArrayGeneric]: OutputType;
-};
-export declare function repeatArray<T>(repeatCount: number, array: T[]): T[];
-/**
- * Polyfill for `Object.groupBy`:
- * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy
- */
-export declare function groupArrayBy<ElementType, NewKey extends PropertyKey>(inputArray: ReadonlyArray<ElementType>, callback: (entry: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => NewKey): Partial<Record<NewKey, ElementType[]>>;
-/**
- * Like `groupArrayBy` but maps array entries to a single key. Meaning, the resulting object does
- * not have an array of elements (unless the original array itself contains arrays).
- */
-export declare function arrayToObject<ElementType, NewKey extends PropertyKey>(inputArray: ReadonlyArray<ElementType>, callback: (entry: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => NewKey): Partial<Record<NewKey, ElementType>>;
-export declare function filterMap<ElementType, MappedEntry, TypeGuarded extends MappedEntry>(inputArray: ReadonlyArray<ElementType>, mapCallback: (entry: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => MappedEntry, filterCallback: (mappedOutput: MappedEntry, originalEntry: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => mappedOutput is TypeGuarded): TypeGuarded[];
-export declare function filterMap<ElementType, MappedEntry>(inputArray: ReadonlyArray<ElementType>, mapCallback: (entry: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => MappedEntry, filterCallback: (mappedOutput: MappedEntry, originalEntry: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => boolean): MappedEntry[];
-export {};

package/dist/types/augments/async.d.ts

@@ -1,14 +0,0 @@
-/**
- * Acts like calling Array.prototype.forEach in that all elements are executed upon in order, and
- * each execution is blocking. Meaning, the callback won't be called on element 2 until the callback
- * has finished its call on element 1.
- */
-export declare function awaitedForEach<OriginalGeneric>(input: ReadonlyArray<OriginalGeneric>, callback: (arrayElement: OriginalGeneric, index: number, wholeArray: ReadonlyArray<OriginalGeneric>) => void | PromiseLike<void>): Promise<void>;
-export declare function awaitedBlockingMap<OriginalGeneric, MappedGeneric>(input: ReadonlyArray<OriginalGeneric>, callback: (arrayElement: OriginalGeneric, index: number, wholeArray: ReadonlyArray<OriginalGeneric>) => MappedGeneric | PromiseLike<MappedGeneric>): Promise<Awaited<MappedGeneric>[]>;
-export declare function awaitedFilter<OriginalGeneric>(arrayInput: ReadonlyArray<OriginalGeneric>, filterCallback: (arrayElement: OriginalGeneric, index: number, wholeArray: ReadonlyArray<OriginalGeneric>) => Promise<unknown>, options?: {
-    /**
-     * Each call to the filter callback is blocking, meaning the next one won't start until the
-     * current one finishes. By default this is false.
-     */
-    blocking?: boolean | undefined;
-}): Promise<OriginalGeneric[]>;

package/dist/types/augments/boolean.d.ts

@@ -1,6 +0,0 @@
-export type FalsyTypes = undefined | null | false | 0 | '' | -0 | 0n;
-export type Truthy<T> = Exclude<T, FalsyTypes>;
-export type Falsy<T> = Extract<T, FalsyTypes>;
-export declare function isTruthy<T>(input: T): input is Truthy<T>;
-export declare function isFalsy<T>(input: T): input is Falsy<T>;
-export declare function ifTruthy<const InputType, IfTruthyType, IfFalsyType>(checkThis: InputType, ifTruthyCallback: (truthyInput: Truthy<InputType>) => IfTruthyType, ifFalsyCallback: (truthyInput: Falsy<InputType>) => IfFalsyType): IfTruthyType | IfFalsyType;

package/dist/types/augments/common-number.d.ts

@@ -1,52 +0,0 @@
-export declare const NaNString: string;
-export declare function addCommasToNumber(input: number | string): string;
-export declare function doesRequireScientificNotation(input: number): boolean;
-/**
- * Given a min and max, ensures that they are in correct order. Meaning, min is less than max. If
- * that is not the case, the returned value is the given min and max values swapped.
- */
-export declare function ensureMinAndMax({ min, max }: {
-    min: number;
-    max: number;
-}): {
-    min: number;
-    max: number;
-};
-/**
- * Tries to convert the input into a number. Handles strings with commas. Note: this might return
- * `NaN`.
- */
-export declare function toNumber(input: unknown): number;
-/** @deprecated Use {@link toNumber} instead. */
-export declare const convertIntoNumber: typeof toNumber;
-/** Tries to convert the input into a number and throws an error if `NaN` is created. */
-export declare function toEnsuredNumber(input: unknown): number;
-/** Tries to convert the input into a number and returns `undefined` if `NaN` is created. */
-export declare function toMaybeNumber(input: unknown): number | undefined;
-/**
- * If the given value is outside the given min/max bounds, instead of clamping the number (as the
- * `clamp` function does), this function wraps the value around to the next bound.
- *
- * @example
- *     wrapNumber({min: 0, max: 100, value: 101}) == 0;
- */
-export declare function wrapNumber({ max, min, value }: {
-    value: number;
-    max: number;
-    min: number;
-}): number;
-export declare function round(inputs: {
-    number: number;
-    digits: number;
-}): number;
-/** Clamp's the given value to within the min and max bounds, inclusive. */
-export declare function clamp({ value, min, max }: {
-    value: number;
-    min: number;
-    max: number;
-}): number;
-/** Standard box dimensions. */
-export type Dimensions = {
-    width: number;
-    height: number;
-};