@augment-vir/common 29.3.0 → 30.0.1

package/dist/augments/object/object-filter.js

@@ -0,0 +1,27 @@
+import { getObjectTypedEntries, typedObjectFromEntries } from './object-entries.js';
+/**
+ * Filters an object. Like
+ * [`[].filter`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)
+ * but for objects.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {filterObject} from '@augment-vir';
+ *
+ * filterObject({a: 1, b: 2, c: 3}, (key, value) => {
+ *     return value >= 2;
+ * });
+ * // output is `{b: 2, c: 3}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function filterObject(inputObject, callback) {
+    const filteredEntries = getObjectTypedEntries(inputObject).filter(([key, value,]) => {
+        return callback(key, value, inputObject);
+    });
+    return typedObjectFromEntries(filteredEntries);
+}

package/dist/augments/object/object-keys.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Same as the TypeScript built-in type `Omit` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {omitObjectKeys} from '@augment-vir/common';
+ *
+ * omitObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function omitObjectKeys<const ObjectGeneric, const KeyGeneric extends keyof ObjectGeneric>(inputObject: Readonly<ObjectGeneric>, omitTheseKeys: ReadonlyArray<KeyGeneric>): Omit<ObjectGeneric, KeyGeneric>;
+/**
+ * Same as the TypeScript built-in type `Pick` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {pickObjectKeys} from '@augment-vir/common';
+ *
+ * pickObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{a: 'a'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function pickObjectKeys<const ObjectGeneric, const KeyGeneric extends keyof ObjectGeneric>(inputObject: Readonly<ObjectGeneric>, pickTheseKeys: ReadonlyArray<KeyGeneric>): Pick<ObjectGeneric, KeyGeneric>;

package/dist/augments/object/object-keys.js

@@ -0,0 +1,43 @@
+import { filterObject } from './object-filter.js';
+/**
+ * Same as the TypeScript built-in type `Omit` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {omitObjectKeys} from '@augment-vir/common';
+ *
+ * omitObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function omitObjectKeys(inputObject, omitTheseKeys) {
+    return filterObject(inputObject, (currentKey) => {
+        return !omitTheseKeys.includes(currentKey);
+    });
+}
+/**
+ * Same as the TypeScript built-in type `Pick` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {pickObjectKeys} from '@augment-vir/common';
+ *
+ * pickObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{a: 'a'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function pickObjectKeys(inputObject, pickTheseKeys) {
+    return filterObject(inputObject, (currentKey) => {
+        return pickTheseKeys.includes(currentKey);
+    });
+}

package/dist/augments/object/object-values.d.ts

@@ -0,0 +1,11 @@
+import { CompleteRequire } from '@augment-vir/core';
+/**
+ * Gets an object's values. This is the same as
+ * [`Object.values`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/values)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function getObjectTypedValues<ObjectGeneric>(input: ObjectGeneric): CompleteRequire<ObjectGeneric>[keyof CompleteRequire<ObjectGeneric>][];

package/dist/augments/object/object-values.js

@@ -0,0 +1,13 @@
+import { getObjectTypedKeys } from '@augment-vir/core';
+/**
+ * Gets an object's values. This is the same as
+ * [`Object.values`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/values)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function getObjectTypedValues(input) {
+    return getObjectTypedKeys(input).map((key) => input[key]);
+}

package/dist/augments/path/esm-path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates the equivalent of CJS's
+ * [`__dirname`](https://nodejs.org/docs/latest/api/globals.html#__dirname) and
+ * [`__filename`](https://nodejs.org/docs/latest/api/globals.html#__filename) for ESM modules.
+ *
+ * This is the equivalent of
+ * [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) and
+ * [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) added to Node.js
+ * v20.11.0 but is compatible with older versions of Node.js as well as browsers.
+ *
+ * @category Path : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {getEsmPath} from '@augment-vir/common';
+ *
+ * const {filePath, dirPath} = getEsmPath(import.meta);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function getEsmPath(importMeta: ImportMeta): {
+    filePath: string;
+    dirPath: string;
+};

package/dist/augments/path/esm-path.js

@@ -0,0 +1,31 @@
+import { removeSuffix } from '../string/suffix.js';
+/**
+ * Creates the equivalent of CJS's
+ * [`__dirname`](https://nodejs.org/docs/latest/api/globals.html#__dirname) and
+ * [`__filename`](https://nodejs.org/docs/latest/api/globals.html#__filename) for ESM modules.
+ *
+ * This is the equivalent of
+ * [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) and
+ * [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) added to Node.js
+ * v20.11.0 but is compatible with older versions of Node.js as well as browsers.
+ *
+ * @category Path : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {getEsmPath} from '@augment-vir/common';
+ *
+ * const {filePath, dirPath} = getEsmPath(import.meta);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function getEsmPath(importMeta) {
+    const filePath = new URL('', importMeta.url).pathname;
+    const dirPath = removeSuffix({ value: new URL('.', importMeta.url).pathname, suffix: '/' });
+    return {
+        filePath,
+        dirPath,
+    };
+}

package/dist/augments/prisma/prisma-models.d.ts

@@ -0,0 +1,143 @@
+import type { AnyFunction, AnyObject } from '@augment-vir/core';
+/**
+ * Extracts all model names from a generated `Prisma` object.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {Prisma} from '@prisma/client';
+ * import type {ModelNameFromPrismaTypeMap} from '@augment-vir/common';
+ *
+ * function doThing(modelName: ModelNameFromPrismaTypeMap<Prisma.TypeMap>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type ModelNameFromPrismaTypeMap<PrismaTypeMap extends BasePrismaTypeMap> = PrismaTypeMap['meta']['modelProps'];
+/**
+ * Extracts all model names from a generated `PrismaClient`.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import type {ModelNameFromPrismaClient} from '@augment-vir/common';
+ *
+ * function doThing(modelName: ModelNameFromPrismaClient<PrismaClient>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type ModelNameFromPrismaClient<PrismaClient extends AnyObject> = keyof {
+    [Model in Extract<keyof PrismaClient, string> as PrismaClient[Model] extends {
+        findFirst: AnyFunction;
+    } ? Model : never]: boolean;
+};
+/**
+ * Extracts the creation data for a model from the given `PrismaClient` type.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import type {ModelCreationEntry} from '@augment-vir/common';
+ *
+ * function doThing(entry: ModelCreationEntry<PrismaClient, 'User'>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaModelCreationEntry<PrismaClient extends AnyObject, Model extends ModelNameFromPrismaClient<PrismaClient>> = NonNullable<Parameters<PrismaClient[Model]['create']>[0]> extends {
+    data?: infer Data;
+} ? NonNullable<Data> : `ERROR: failed to infer creation entry for model '${Model}'`;
+/**
+ * A base type for `Prisma.TypeMap` because Prisma doesn't give us one. This currently only includes
+ * the properties that are used within `@augment-vir/common`.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type BasePrismaTypeMap = {
+    meta: {
+        modelProps: string;
+    };
+    model: Record<string, {
+        payload: BasePrismaPayload;
+    }>;
+};
+/**
+ * A base type for Prisma model payloads because Prisma doesn't give us one. This currently only
+ * includes the properties that are used within this package.
+ *
+ * Note: this omits the `composites` property because I don't have any examples of what those
+ * actually are.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type BasePrismaPayload = {
+    name: string;
+    objects: Record<string, BasePrismaPayload | BasePrismaPayload[] | null>;
+    scalars: AnyObject;
+};
+/**
+ * A full model entry with all relations from the given Prisma type map and model name.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {Prisma} from '@prisma/client';
+ * import type {FullPrismaModel} from '@augment-vir/common';
+ *
+ * function doThing(fullModel: FullModel<Prisma.TypeMap, 'User'>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type FullPrismaModel<PrismaTypeMap extends BasePrismaTypeMap, Model extends ModelNameFromPrismaTypeMap<PrismaTypeMap>> = ExpandPrismaTypeMapPayload<PrismaTypeMap['model'][Model]['payload']>;
+/**
+ * A base model entry with only its immediate properties from the given Prisma type map and model
+ * name.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {Prisma} from '@prisma/client';
+ * import type {BasePrismaModel} from '@augment-vir/common';
+ *
+ * function doThing(fullModel: BaseModel<Prisma.TypeMap, 'User'>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type BasePrismaModel<PrismaTypeMap extends BasePrismaTypeMap, Model extends ModelNameFromPrismaTypeMap<PrismaTypeMap>> = PrismaTypeMap['model'][Model]['payload']['scalars'];
+/**
+ * Expand a Prisma payload into its scalars and recursive relations.
+ *
+ * @category Prisma : Common : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type ExpandPrismaTypeMapPayload<Payload extends BasePrismaPayload> = Payload['scalars'] & {
+    [Key in keyof Payload['objects']]: ExpandPotentialArrayPrismaTypeMapPayload<NonNullable<Payload['objects'][Key]>> | (null extends Payload['objects'][Key] ? null : never);
+};
+/**
+ * Expand a payload that might be inside of an array, keeping it inside of an array if it is.
+ *
+ * @category Prisma : Common : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type ExpandPotentialArrayPrismaTypeMapPayload<PayloadWrapper extends BasePrismaPayload | BasePrismaPayload[]> = PayloadWrapper extends (infer ActualPayload extends BasePrismaPayload)[] ? ExpandPrismaTypeMapPayload<ActualPayload>[] : PayloadWrapper extends BasePrismaPayload ? ExpandPrismaTypeMapPayload<PayloadWrapper> : never;

package/dist/augments/prisma/prisma-models.js

@@ -0,0 +1 @@
+export {};

package/dist/augments/promise/timed-promise.d.ts

@@ -0,0 +1,22 @@
+import { AnyDuration } from '@date-vir/duration';
+/**
+ * An error thrown by {@link wrapPromiseInTimeout} when the timeout is reached.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare class PromiseTimeoutError extends Error {
+    readonly duration: AnyDuration;
+    readonly name = "PromiseTimeoutError";
+    constructor(duration: AnyDuration, failureMessage?: string | undefined);
+}
+/**
+ * Wraps an already-created Promise in a timeout, causing a rejection if the original Promise isn't
+ * resolved by then.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function wrapPromiseInTimeout<T>(duration: Readonly<AnyDuration>, originalPromise: PromiseLike<T>, failureMessage?: string | undefined): Promise<T>;

package/dist/augments/promise/timed-promise.js

@@ -0,0 +1,51 @@
+import { check } from '@augment-vir/assert';
+import { ensureError } from '@augment-vir/core';
+import { convertDuration, DurationUnit } from '@date-vir/duration';
+/**
+ * An error thrown by {@link wrapPromiseInTimeout} when the timeout is reached.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export class PromiseTimeoutError extends Error {
+    duration;
+    name = 'PromiseTimeoutError';
+    constructor(duration, failureMessage) {
+        super([
+            failureMessage,
+            `Promised timed out after ${convertDuration(duration, DurationUnit.Milliseconds).milliseconds} ms.`,
+        ]
+            .filter(check.isTruthy)
+            .join(': '));
+        this.duration = duration;
+    }
+}
+/**
+ * Wraps an already-created Promise in a timeout, causing a rejection if the original Promise isn't
+ * resolved by then.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function wrapPromiseInTimeout(duration, originalPromise, failureMessage) {
+    const milliseconds = convertDuration(duration, DurationUnit.Milliseconds).milliseconds;
+    return new Promise(async (resolve, reject) => {
+        const timeoutId = milliseconds === Infinity
+            ? undefined
+            : setTimeout(() => {
+                reject(new PromiseTimeoutError(duration, failureMessage));
+            }, milliseconds);
+        try {
+            const result = await originalPromise;
+            resolve(result);
+        }
+        catch (error) {
+            reject(ensureError(error));
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    });
+}

package/dist/augments/random/random-boolean.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ *
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {randomBoolean} from '@augment-vir/common';
+ *
+ * randomBoolean(50); // 50% chance to return true
+ * randomBoolean(0); // always false, 0% chance of being true
+ * randomBoolean(100); // always true, 100% chance of being true
+ * randomBoolean(59.67); // 59% chance of being true
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function randomBoolean(percentLikelyToBeTrue?: number): boolean;

package/dist/augments/random/random-boolean.js

@@ -0,0 +1,32 @@
+import { clamp } from '../number/clamp.js';
+import { randomInteger } from './random-integer.js';
+/**
+ * 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.
+ *
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {randomBoolean} from '@augment-vir/common';
+ *
+ * randomBoolean(50); // 50% chance to return true
+ * randomBoolean(0); // always false, 0% chance of being true
+ * randomBoolean(100); // always true, 100% chance of being true
+ * randomBoolean(59.67); // 59% chance of being true
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function randomBoolean(percentLikelyToBeTrue = 50) {
+    return (randomInteger({ min: 0, max: 99 }) <
+        clamp(Math.floor(percentLikelyToBeTrue), {
+            min: 0,
+            max: 100,
+        }));
+}

package/dist/augments/random/random-integer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Creates a random integer (no decimal points are included) between the given min and max values
+ * (inclusive).
+ *
+ * This function uses cryptographically secure randomness.
+ *
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function randomInteger({ min: rawMin, max: rawMax }: {
+    min: number;
+    max: number;
+}): number;

package/dist/augments/random/random-integer.js

@@ -0,0 +1,34 @@
+import { ensureMinMax } from '../number/min-max.js';
+/**
+ * Creates a random integer (no decimal points are included) between the given min and max values
+ * (inclusive).
+ *
+ * This function uses cryptographically secure randomness.
+ *
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function randomInteger({ min: rawMin, max: rawMax }) {
+    const { min, max } = ensureMinMax({ min: Math.floor(rawMin), max: Math.floor(rawMax) });
+    const range = max - min + 1;
+    const bitsNeeded = Math.ceil(Math.log2(range));
+    const neededBytes = Math.ceil(bitsNeeded / 8);
+    /**
+     * Testing on my system maxes out at 65,536 (Node) or 65,537 (Safari / Chrome / Firefox) bytes.
+     * I don't know why, and that may be system dependent, I don't know.
+     */
+    if (neededBytes > 65_000) {
+        throw new RangeError(`Cannot create a random integer so large. ({min: ${min}, max: ${max}})`);
+    }
+    const cutoff = Math.floor(256 ** neededBytes / range) * range;
+    const currentBytes = new Uint8Array(neededBytes);
+    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);
+}

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

@@ -0,0 +1,18 @@
+/**
+ * All letters allowed in {@link randomString}.
+ *
+ * @category Random : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const allowedRandomStringLetters: ReadonlyArray<string>;
+/**
+ * Creates a random string (including letters and numbers) of a given length.
+ *
+ * This function uses cryptographically secure randomness.
+ *
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function randomString(generatedStringLength?: number): string;

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

@@ -0,0 +1,67 @@
+import { randomInteger } from './random-integer.js';
+/**
+ * All letters allowed in {@link randomString}.
+ *
+ * @category Random : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const allowedRandomStringLetters = [
+    '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.
+ *
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function randomString(generatedStringLength = 16) {
+    let stringBuilder = '';
+    for (let i = 0; i < generatedStringLength; i++) {
+        const index = randomInteger({
+            min: 0,
+            max: allowedRandomStringLetters.length - 1,
+        });
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        stringBuilder += allowedRandomStringLetters[index];
+    }
+    return stringBuilder;
+}

package/dist/augments/regexp/match.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Performs
+ * [`''.match`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/match)
+ * but falls back to an empty array if no match was found.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function safeMatch(input: string, regExp: RegExp): string[];

package/dist/augments/regexp/match.js

@@ -0,0 +1,13 @@
+/**
+ * Performs
+ * [`''.match`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/match)
+ * but falls back to an empty array if no match was found.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function safeMatch(input, regExp) {
+    const match = input.match(regExp);
+    return match ?? [];
+}