@augment-vir/common 4.0.0

package/README.md

@@ -0,0 +1,5 @@
+# @augment-vir/common
+
+`augment-vir` is a collection of small helper functions that I constantly use across all my JavaScript and TypeScript repos. I call these functions `augments`. These are things commonly placed within a "util", or "helpers", etc. directory; they don't really have anything in common with each other except that they have almost no dependencies.
+
+This `common` package is for environment-agnostic augments. Everything in here will work in Node.js or the browser with identical results.

package/dist/augments/ansi.d.ts

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

package/dist/augments/ansi.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ansiRegex = void 0;
+// cspell:disable
+/*
+Copied from
+https://github.com/chalk/ansi-regex/blob/1b337add136eb520764634a328e2f6354398eee5/index.js
+because the published ansi-regex package exports this in a manner that Jest can't handle and the
+latest version of the package that doesn't do that has a security vulnerability. The package has
+the following license from
+https://github.com/chalk/ansi-regex/blob/1b337add136eb520764634a328e2f6354398eee5/license
+
+MIT License
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+// cspell:enable
+const patterns = [
+    '[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)',
+    '(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]))',
+];
+exports.ansiRegex = new RegExp(patterns.join('|'), 'g');

package/dist/augments/array.d.ts

@@ -0,0 +1,20 @@
+import { AtLeastTuple } from './tuple';
+import { ArrayElement } from './type';
+export declare function filterOutIndexes<T>(array: Readonly<T[]>, indexes: Readonly<number[]>): T[];
+export declare function flatten2dArray<T>(array2d: T[][]): T[];
+export declare type AtLeastOneEntryArray<ArrayGeneric extends ReadonlyArray<any>> = AtLeastTuple<ArrayElement<ArrayGeneric>, 1>;
+export declare function trimArrayStrings(input: string[]): string[];
+/**
+ * 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 isInTypedArray<T>(array: T[], input: any): input is T;
+declare 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 {};

package/dist/augments/array.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typedMap = exports.isInTypedArray = exports.awaitedBlockingMap = exports.awaitedForEach = exports.trimArrayStrings = exports.flatten2dArray = exports.filterOutIndexes = void 0;
+function filterOutIndexes(array, indexes) {
+    return array.filter((_, index) => !indexes.includes(index));
+}
+exports.filterOutIndexes = filterOutIndexes;
+function flatten2dArray(array2d) {
+    const flattened = array2d.reduce((accum, row) => accum.concat(row), []);
+    return flattened;
+}
+exports.flatten2dArray = flatten2dArray;
+function trimArrayStrings(input) {
+    return input.map((line) => line.trim()).filter((line) => line !== '');
+}
+exports.trimArrayStrings = trimArrayStrings;
+/**
+ * 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.
+ */
+async function awaitedForEach(input, callback) {
+    await awaitedBlockingMap(input, callback);
+}
+exports.awaitedForEach = awaitedForEach;
+async function awaitedBlockingMap(input, callback) {
+    const mappedValues = await input.reduce(async (accumPromise, currentElement, index, wholeArray) => {
+        const accum = await accumPromise;
+        const mappedValue = await callback(currentElement, index, wholeArray);
+        accum.push(mappedValue);
+        return accum;
+    }, Promise.resolve([]));
+    return mappedValues;
+}
+exports.awaitedBlockingMap = awaitedBlockingMap;
+function isInTypedArray(array, input) {
+    return array.includes(input);
+}
+exports.isInTypedArray = isInTypedArray;
+/** Preserves tuple types. */
+function typedMap(arrayToMap, mapCallback) {
+    return arrayToMap.map(mapCallback);
+}
+exports.typedMap = typedMap;

package/dist/augments/date.d.ts

@@ -0,0 +1,26 @@
+export declare const englishFullMonthNames: string[];
+export declare const englishShortMonthNames: string[];
+export declare class InvalidDateError extends Error {
+    readonly name = "InvalidDateError";
+}
+/**
+ * @param slashFormatString String that should be of format "MM/DD/YY", "MM/DD/YYYY". When the year
+ *   portion only contains 2 numbers ("MM/DD/YY") the century must be provided in the form of the
+ *   yearPrefix input.
+ * @param yearPrefix String or number that is used to prefix slash format strings that only contain
+ *   2 digits ("MM/DD/YY"). If the year is entirely missing form the given slash format string, the
+ *   year will default to year 00 of the given century. See test file for examples.
+ */
+export declare function createDateFromSlashFormat(slashFormatString: string, yearPrefix?: number | string): Date;
+/**
+ * @param commaFormatString Should be at string of the form "monthName dayNumber, fullYear" Example:
+ *   "May 19, 2005"
+ * @param ignoreInvalidMonth Set to true to ignore invalid months
+ */
+export declare function createDateFromNamedCommaFormat(commaFormatString: string, ignoreInvalidMonth?: boolean): Date;
+/**
+ * Converts an iso-formatted string to a UTC date object. The time is nulled out to all zeros.
+ *
+ * @param isoFormatString Should be a date in the format YYYY-MM-DD.
+ */
+export declare function createDateFromUtcIsoFormat(isoFormatString: string): Date;

package/dist/augments/date.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDateFromUtcIsoFormat = exports.createDateFromNamedCommaFormat = exports.createDateFromSlashFormat = exports.InvalidDateError = exports.englishShortMonthNames = exports.englishFullMonthNames = void 0;
+exports.englishFullMonthNames = [
+    'january',
+    'february',
+    'march',
+    'april',
+    'may',
+    'june',
+    'july',
+    'august',
+    'september',
+    'october',
+    'november',
+    'december',
+];
+exports.englishShortMonthNames = exports.englishFullMonthNames.map((longMonthName) => longMonthName.slice(0, 3));
+class InvalidDateError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'InvalidDateError';
+    }
+}
+exports.InvalidDateError = InvalidDateError;
+/**
+ * @param slashFormatString String that should be of format "MM/DD/YY", "MM/DD/YYYY". When the year
+ *   portion only contains 2 numbers ("MM/DD/YY") the century must be provided in the form of the
+ *   yearPrefix input.
+ * @param yearPrefix String or number that is used to prefix slash format strings that only contain
+ *   2 digits ("MM/DD/YY"). If the year is entirely missing form the given slash format string, the
+ *   year will default to year 00 of the given century. See test file for examples.
+ */
+function createDateFromSlashFormat(slashFormatString, yearPrefix = '') {
+    const [month, day, rawYearEnding = '',] = slashFormatString.split('/');
+    if (!month || !day) {
+        throw new Error(`Unable to extract month or day from "${slashFormatString}"`);
+    }
+    const yearEnding = rawYearEnding.length < 4 ? `${yearPrefix}${rawYearEnding.padStart(2, '0')}` : rawYearEnding;
+    const returnDate = createDateFromUtcIsoFormat(`${yearEnding.padStart(4, '0')}-${month.padStart(2, '0')}-${day.padStart(2, '0')}`);
+    return returnDate;
+}
+exports.createDateFromSlashFormat = createDateFromSlashFormat;
+/**
+ * @param commaFormatString Should be at string of the form "monthName dayNumber, fullYear" Example:
+ *   "May 19, 2005"
+ * @param ignoreInvalidMonth Set to true to ignore invalid months
+ */
+function createDateFromNamedCommaFormat(commaFormatString, ignoreInvalidMonth = false) {
+    const [monthName, dayNumber, fullYear,] = commaFormatString.replace(',', '').split(' ');
+    if (!monthName || !dayNumber || !fullYear) {
+        throw new InvalidDateError(`Invalid ${createDateFromNamedCommaFormat.name} input: ${commaFormatString}`);
+    }
+    const longMonthIndex = exports.englishFullMonthNames.indexOf(monthName.toLowerCase());
+    const shortMonthIndex = exports.englishShortMonthNames.indexOf(monthName.toLowerCase());
+    let monthIndex = longMonthIndex === -1 ? shortMonthIndex : longMonthIndex;
+    if (monthIndex === -1) {
+        if (ignoreInvalidMonth) {
+            monthIndex = 4;
+        }
+        else {
+            throw new InvalidDateError(`Month name ${monthName} was not found.`);
+        }
+    }
+    const returnDate = createDateFromUtcIsoFormat(`${fullYear.padStart(4, '0')}-${String(monthIndex + 1).padStart(2, '0')}-${dayNumber.padStart(2, '0')}`);
+    return returnDate;
+}
+exports.createDateFromNamedCommaFormat = createDateFromNamedCommaFormat;
+/**
+ * Converts an iso-formatted string to a UTC date object. The time is nulled out to all zeros.
+ *
+ * @param isoFormatString Should be a date in the format YYYY-MM-DD.
+ */
+function createDateFromUtcIsoFormat(isoFormatString) {
+    const utcDate = new Date(isoFormatString + 'T00:00:00.000Z');
+    if (isNaN(Number(utcDate))) {
+        throw new InvalidDateError(`Invalid utc date formed from input "${isoFormatString}"`);
+    }
+    return utcDate;
+}
+exports.createDateFromUtcIsoFormat = createDateFromUtcIsoFormat;

package/dist/augments/error.d.ts

@@ -0,0 +1,8 @@
+import { AtLeastTuple } from './tuple';
+export declare function combineErrors(errors: AtLeastTuple<Error, 1>): Error;
+export declare function combineErrors(errors: never[]): undefined;
+export declare function combineErrors(errors: Error[]): Error | undefined;
+export declare function combineErrors(errors?: undefined): undefined;
+export declare function combineErrorMessages(errors?: (Error | string | undefined)[] | undefined): string;
+export declare function extractErrorMessage(error: unknown): string;
+export declare function ensureError(input: unknown): Error;

package/dist/augments/error.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureError = exports.extractErrorMessage = exports.combineErrorMessages = exports.combineErrors = void 0;
+const function_1 = require("./function");
+function combineErrors(errors) {
+    if (!errors || errors.length === 0) {
+        return undefined;
+    }
+    const firstError = errors[0];
+    if (errors.length === 1 && firstError) {
+        return firstError;
+    }
+    return new Error(errors.map((error) => extractErrorMessage(error).trim()).join('\n'));
+}
+exports.combineErrors = combineErrors;
+function combineErrorMessages(errors) {
+    if (!errors) {
+        return '';
+    }
+    return errors.map(extractErrorMessage).filter(function_1.isTruthy).join('\n');
+}
+exports.combineErrorMessages = combineErrorMessages;
+function extractErrorMessage(error) {
+    if (!error) {
+        return '';
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    else {
+        return String(error);
+    }
+}
+exports.extractErrorMessage = extractErrorMessage;
+function ensureError(input) {
+    if (input instanceof Error) {
+        return input;
+    }
+    else {
+        return new Error(extractErrorMessage(input));
+    }
+}
+exports.ensureError = ensureError;

package/dist/augments/function.d.ts

@@ -0,0 +1 @@
+export declare function isTruthy<T>(input: T): input is NonNullable<T>;

package/dist/augments/function.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTruthy = void 0;
+function isTruthy(input) {
+    return !!input;
+}
+exports.isTruthy = isTruthy;

package/dist/augments/number.d.ts

@@ -0,0 +1,27 @@
+export declare function clamp(
+/**
+ * This uses a destructured object so that consumers cannot get confused as to which input is
+ * which (which would be easy to do since they're all of the same type).
+ */
+{ value, min, max, }: {
+    value: number;
+    min: number;
+    max: number;
+}): number;
+/**
+ * This truncates a number such that is will never use commas and will at a max have 6 characters
+ * including suffix and decimal point.
+ *
+ * Default suffixes are:
+ *
+ *     '', // no suffix, numbers below 1000
+ *     'k', // thousand
+ *     'M', // million
+ *     'B', // billion
+ *     'T', // trillion
+ *     'P', // peta-, quadrillion
+ *     'E', // exa- quintillion
+ *     'Z', // zetta- sextillion
+ *     'Y', // yotta- septillion
+ */
+export declare function truncateNumber(originalValue: unknown, suffixes?: readonly string[]): string;

package/dist/augments/number.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncateNumber = exports.clamp = void 0;
+function clamp(
+/**
+ * This uses a destructured object so that consumers cannot get confused as to which input is
+ * which (which would be easy to do since they're all of the same type).
+ */
+{ value, min, max, }) {
+    return Math.max(Math.min(value, max), min);
+}
+exports.clamp = clamp;
+const defaultTruncationSuffixes = [
+    '',
+    'k',
+    'M',
+    'B',
+    'T',
+    'P',
+    'E',
+    'Z',
+    'Y', // yotta- septillion
+];
+function recursiveTruncation(value, recursionDepth = 0, decimalValues = '') {
+    var _a, _b;
+    if (value.includes('e+')) {
+        throw new Error(`Number is too large, it cannot be truncated: ${value}`);
+    }
+    else if (value.includes('e-')) {
+        throw new Error(`Number is too small, it cannot be truncated: ${value}`);
+    }
+    const split = value.split('.');
+    decimalValues = (_a = split[1]) !== null && _a !== void 0 ? _a : decimalValues;
+    const amount = (_b = split[0]) !== null && _b !== void 0 ? _b : '';
+    if (amount.length > 3) {
+        decimalValues = amount.slice(-3);
+        return recursiveTruncation(amount.slice(0, -3), recursionDepth + 1, decimalValues);
+    }
+    return {
+        value: amount,
+        decimalValues,
+        recursionDepth,
+    };
+}
+const maxDecimals = 4;
+/**
+ * This truncates a number such that is will never use commas and will at a max have 6 characters
+ * including suffix and decimal point.
+ *
+ * Default suffixes are:
+ *
+ *     '', // no suffix, numbers below 1000
+ *     'k', // thousand
+ *     'M', // million
+ *     'B', // billion
+ *     'T', // trillion
+ *     'P', // peta-, quadrillion
+ *     'E', // exa- quintillion
+ *     'Z', // zetta- sextillion
+ *     'Y', // yotta- septillion
+ */
+function truncateNumber(originalValue, suffixes = defaultTruncationSuffixes) {
+    try {
+        const value = typeof originalValue === 'number' ? originalValue : Number(originalValue);
+        if (isNaN(value)) {
+            throw new Error(`${originalValue} could not be converted into a number.`);
+        }
+        const results = recursiveTruncation(String(value));
+        const suffix = suffixes[results.recursionDepth];
+        if (suffix === undefined) {
+            throw new Error(`Number is too large, could not truncate: ${value}`);
+        }
+        const decimalPlaces = maxDecimals - (results.value.length - 1) - suffix.length;
+        const decimalValues = results.decimalValues.replace(/0+$/, '').slice(0, decimalPlaces);
+        const withDecimal = decimalValues.length ? `.${decimalValues}` : '';
+        return `${results.value}${withDecimal}${suffix}`;
+    }
+    catch (error) {
+        console.error(error);
+        return String(originalValue);
+    }
+}
+exports.truncateNumber = truncateNumber;

package/dist/augments/object.d.ts

@@ -0,0 +1,62 @@
+import { AtLeastOneEntryArray } from './array';
+import { NoInfer, RequiredBy, UnPromise } from './type';
+export declare function getEnumTypedKeys<T extends object>(input: T): (keyof T)[];
+export declare function getEnumTypedValues<T extends object>(input: T): T[keyof T][];
+export declare function isEnumValue<T extends object>(input: unknown, checkEnum: T): input is T[keyof T];
+export declare function isKeyof<ObjectGeneric>(key: PropertyKey, object: ObjectGeneric): key is keyof object;
+export declare function filterToEnumValues<T extends object>(inputs: unknown[], checkEnum: T, caseInsensitive?: boolean): T[keyof T][];
+export declare function getObjectTypedKeys<ObjectGeneric extends unknown>(input: ObjectGeneric): ReadonlyArray<keyof ObjectGeneric>;
+export declare function getObjectTypedValues<ObjectGeneric extends unknown>(input: ObjectGeneric): ObjectGeneric[keyof ObjectGeneric][];
+declare type ExtractValue<KeyGeneric extends PropertyKey, ParentGeneric> = KeyGeneric extends keyof ParentGeneric ? RequiredBy<ParentGeneric, KeyGeneric>[KeyGeneric] : KeyGeneric extends keyof Extract<ParentGeneric, Record<KeyGeneric, any>> ? RequiredBy<Extract<ParentGeneric, Record<KeyGeneric, any>>, KeyGeneric>[KeyGeneric] : never;
+declare type CombinedParentValue<KeyGeneric extends PropertyKey, ParentGeneric> = ExtractValue<KeyGeneric, ParentGeneric> extends never ? unknown : ExtractValue<KeyGeneric, ParentGeneric>;
+declare type CombineTypeWithKey<KeyGeneric extends PropertyKey, ParentGeneric> = ParentGeneric & Record<KeyGeneric, CombinedParentValue<KeyGeneric, ParentGeneric>>;
+export declare function typedHasProperty<KeyGeneric extends PropertyKey, ParentGeneric>(inputObject: ParentGeneric, inputKey: KeyGeneric): inputObject is CombineTypeWithKey<KeyGeneric, ParentGeneric>;
+export declare function typedHasProperties<KeyGeneric extends PropertyKey, ParentGeneric>(inputObject: ParentGeneric, inputKeys: KeyGeneric[]): inputObject is CombineTypeWithKey<KeyGeneric, ParentGeneric>;
+export declare function isObject(input: any): input is NonNullable<object>;
+export declare function getEntriesSortedByKey(input: object): [string, unknown][];
+export declare function areJsonEqual(a: object, b: object): boolean;
+export declare type InnerMappedValues<EntireInputGeneric extends object, MappedValueGeneric> = {
+    [MappedProp in keyof EntireInputGeneric]: MappedValueGeneric;
+};
+export declare type MappedValues<EntireInputGeneric extends object, MappedValueGeneric> = MappedValueGeneric extends PromiseLike<unknown> ? Promise<InnerMappedValues<EntireInputGeneric, UnPromise<MappedValueGeneric>>> : InnerMappedValues<EntireInputGeneric, UnPromise<MappedValueGeneric>>;
+/**
+ * Creates a new object with the same properties as the input object, but with values set to the
+ * result of mapCallback for each property.
+ */
+export declare function mapObjectValues<EntireInputGeneric extends object, MappedValueGeneric>(inputObject: EntireInputGeneric, mapCallback: (inputKey: keyof EntireInputGeneric, keyValue: EntireInputGeneric[typeof inputKey], fullObject: EntireInputGeneric) => MappedValueGeneric): MappedValues<EntireInputGeneric, MappedValueGeneric>;
+export declare function filterObject<ObjectGeneric extends object>(inputObject: ObjectGeneric, callback: (key: keyof ObjectGeneric, value: ObjectValueType<ObjectGeneric>, fullObject: ObjectGeneric) => boolean): Partial<ObjectGeneric>;
+/** The input here must be serializable otherwise JSON parsing errors will be thrown */
+export declare function copyThroughJson<T>(input: T): T;
+export declare type ObjectValueType<T extends object> = T[keyof T];
+/**
+ * Checks that the first input, testThisOne, matches the object shape of the second input,
+ * compareToThisOne. Does not compare exact values of properties, only types.
+ *
+ * To allow the test input, the first input, to have additional keys that the compare input, the
+ * second input, does not have, pass in a third argument set to true.
+ *
+ * This function REQUIRES a generic to be assigned to it: it cannot infer it from the inputs.
+ *
+ * The compare input, the second input, is required to have at least one entry in every array value
+ * that exists. If more array values are present, they will be considered other possible types for
+ * entries in that array.
+ */
+export declare function matchesObjectShape<MatchThisGeneric extends object>(testThisOne: unknown, compareToThisOne: NoInfer<ObjectWithAtLeastSingleEntryArrays<MatchThisGeneric>>, allowExtraProps?: boolean, shouldLogWhy?: boolean): testThisOne is MatchThisGeneric;
+export declare type ObjectWithAtLeastSingleEntryArrays<BaseObject extends object> = {
+    [Prop in keyof BaseObject]: BaseObject[Prop] extends ReadonlyArray<any> ? AtLeastOneEntryArray<BaseObject[Prop]> : BaseObject[Prop] extends object ? ObjectWithAtLeastSingleEntryArrays<BaseObject[Prop]> : BaseObject[Prop];
+};
+/**
+ * Asserts that the first input, testThisOne, matches the object shape of the second input,
+ * compareToThisOne. Does not compare exact values of properties, only types.
+ *
+ * To allow the test input, the first input, to have additional keys that the compare input, the
+ * second input, does not have, pass in a third argument set to true.
+ *
+ * This function REQUIRES a generic to be assigned to it: it cannot infer it from the inputs.
+ *
+ * The compare input, the second input, is required to have at least one entry in every array value
+ * that exists. If more array values are present, they will be considered other possible types for
+ * entries in that array.
+ */
+export declare function assertMatchesObjectShape<MatchThisGeneric extends object = never>(testThisOne: unknown, compareToThisOne: NoInfer<ObjectWithAtLeastSingleEntryArrays<MatchThisGeneric>>, allowExtraProps?: boolean): asserts testThisOne is MatchThisGeneric;
+export {};

package/dist/augments/object.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertMatchesObjectShape = exports.matchesObjectShape = exports.copyThroughJson = exports.filterObject = exports.mapObjectValues = exports.areJsonEqual = exports.getEntriesSortedByKey = exports.isObject = exports.typedHasProperties = exports.typedHasProperty = exports.getObjectTypedValues = exports.getObjectTypedKeys = exports.filterToEnumValues = exports.isKeyof = exports.isEnumValue = exports.getEnumTypedValues = exports.getEnumTypedKeys = void 0;
+const error_1 = require("./error");
+const function_1 = require("./function");
+function getEnumTypedKeys(input) {
+    // enum keys are always strings
+    return getObjectTypedKeys(input).filter((key) => isNaN(Number(key)));
+}
+exports.getEnumTypedKeys = getEnumTypedKeys;
+function getEnumTypedValues(input) {
+    const keys = getEnumTypedKeys(input);
+    return keys.map((key) => input[key]);
+}
+exports.getEnumTypedValues = getEnumTypedValues;
+function isEnumValue(input, checkEnum) {
+    return getEnumTypedValues(checkEnum).includes(input);
+}
+exports.isEnumValue = isEnumValue;
+function isKeyof(key, object) {
+    return typedHasProperty(object, key);
+}
+exports.isKeyof = isKeyof;
+function filterToEnumValues(inputs, checkEnum, caseInsensitive = false) {
+    if (caseInsensitive) {
+        return inputs.reduce((accum, currentInput) => {
+            const matchedEnumValue = getEnumTypedValues(checkEnum).find((actualEnumValue) => {
+                return String(actualEnumValue).toUpperCase() === String(currentInput).toUpperCase();
+            });
+            if (matchedEnumValue) {
+                return accum.concat(matchedEnumValue);
+            }
+            else {
+                return accum;
+            }
+        }, []);
+    }
+    else {
+        return inputs.filter((input) => isEnumValue(input, checkEnum));
+    }
+}
+exports.filterToEnumValues = filterToEnumValues;
+function getObjectTypedKeys(input) {
+    let reflectKeys;
+    try {
+        reflectKeys = Reflect.ownKeys(input);
+    }
+    catch (error) { }
+    return (reflectKeys !== null && reflectKeys !== void 0 ? reflectKeys : [
+        ...Object.keys(input),
+        ...Object.getOwnPropertySymbols(input),
+    ]);
+}
+exports.getObjectTypedKeys = getObjectTypedKeys;
+function getObjectTypedValues(input) {
+    return getObjectTypedKeys(input).map((key) => input[key]);
+}
+exports.getObjectTypedValues = getObjectTypedValues;
+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;
+    },
+];
+function typedHasProperty(inputObject, inputKey) {
+    if (!inputObject) {
+        return false;
+    }
+    return hasPropertyAttempts.some((attemptCallback) => {
+        try {
+            return attemptCallback(inputObject, inputKey);
+        }
+        catch (error) {
+            return false;
+        }
+    });
+}
+exports.typedHasProperty = typedHasProperty;
+function typedHasProperties(inputObject, inputKeys) {
+    return inputObject && inputKeys.every((key) => typedHasProperty(inputObject, key));
+}
+exports.typedHasProperties = typedHasProperties;
+function isObject(input) {
+    return !!input && typeof input === 'object';
+}
+exports.isObject = isObject;
+function getEntriesSortedByKey(input) {
+    return Object.entries(input).sort((tupleA, tupleB) => tupleA[0].localeCompare(tupleB[0]));
+}
+exports.getEntriesSortedByKey = getEntriesSortedByKey;
+function areJsonEqual(a, b) {
+    try {
+        const sortedAEntries = getEntriesSortedByKey(a);
+        const sortedBEntries = getEntriesSortedByKey(b);
+        return JSON.stringify(sortedAEntries) === JSON.stringify(sortedBEntries);
+    }
+    catch (error) {
+        console.error(`Failed to compare objects using JSON.stringify`);
+        throw error;
+    }
+}
+exports.areJsonEqual = areJsonEqual;
+/**
+ * Creates a new object with the same properties as the input object, but with values set to the
+ * result of mapCallback for each property.
+ */
+function mapObjectValues(inputObject, mapCallback) {
+    let gotAPromise = false;
+    const mappedObject = getObjectTypedKeys(inputObject).reduce((accum, currentKey) => {
+        const mappedValue = mapCallback(currentKey, inputObject[currentKey], inputObject);
+        if (mappedValue instanceof Promise) {
+            gotAPromise = true;
+        }
+        return {
+            ...accum,
+            [currentKey]: mappedValue,
+        };
+    }, {});
+    if (gotAPromise) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                await Promise.all(getObjectTypedKeys(mappedObject).map(async (key) => {
+                    const value = await mappedObject[key];
+                    mappedObject[key] = value;
+                }));
+                resolve(mappedObject);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    else {
+        return mappedObject;
+    }
+}
+exports.mapObjectValues = mapObjectValues;
+function filterObject(inputObject, callback) {
+    const filteredKeys = getObjectTypedKeys(inputObject).filter((key) => {
+        const value = inputObject[key];
+        return callback(key, value, inputObject);
+    });
+    return filteredKeys.reduce((accum, key) => {
+        accum[key] = inputObject[key];
+        return accum;
+    }, {});
+}
+exports.filterObject = filterObject;
+/** The input here must be serializable otherwise JSON parsing errors will be thrown */
+function copyThroughJson(input) {
+    try {
+        return JSON.parse(JSON.stringify(input));
+    }
+    catch (error) {
+        console.error(`Failed to JSON copy for`, input);
+        throw error;
+    }
+}
+exports.copyThroughJson = copyThroughJson;
+/**
+ * Checks that the first input, testThisOne, matches the object shape of the second input,
+ * compareToThisOne. Does not compare exact values of properties, only types.
+ *
+ * To allow the test input, the first input, to have additional keys that the compare input, the
+ * second input, does not have, pass in a third argument set to true.
+ *
+ * This function REQUIRES a generic to be assigned to it: it cannot infer it from the inputs.
+ *
+ * The compare input, the second input, is required to have at least one entry in every array value
+ * that exists. If more array values are present, they will be considered other possible types for
+ * entries in that array.
+ */
+function matchesObjectShape(testThisOne, compareToThisOne, allowExtraProps = false, shouldLogWhy = false) {
+    try {
+        assertMatchesObjectShape(testThisOne, compareToThisOne, allowExtraProps);
+        return true;
+    }
+    catch (error) {
+        if (shouldLogWhy) {
+            console.error(error);
+        }
+        return false;
+    }
+}
+exports.matchesObjectShape = matchesObjectShape;
+/**
+ * Asserts that the first input, testThisOne, matches the object shape of the second input,
+ * compareToThisOne. Does not compare exact values of properties, only types.
+ *
+ * To allow the test input, the first input, to have additional keys that the compare input, the
+ * second input, does not have, pass in a third argument set to true.
+ *
+ * This function REQUIRES a generic to be assigned to it: it cannot infer it from the inputs.
+ *
+ * The compare input, the second input, is required to have at least one entry in every array value
+ * that exists. If more array values are present, they will be considered other possible types for
+ * entries in that array.
+ */
+function assertMatchesObjectShape(testThisOne, compareToThisOne, allowExtraProps = false) {
+    const testKeys = getObjectTypedKeys(testThisOne);
+    const matchKeys = new Set(getObjectTypedKeys(compareToThisOne));
+    if (!allowExtraProps) {
+        const extraKeys = testKeys.filter((testKey) => !matchKeys.has(testKey));
+        if (extraKeys.length) {
+            throw new Error(`Test object has extra keys: ${extraKeys.join(', ')}`);
+        }
+    }
+    matchKeys.forEach((key) => {
+        if (!typedHasProperty(testThisOne, key)) {
+            throw new Error(`test object does not have key "${String(key)}" from expected shape.`);
+        }
+        function throwKeyError(reason) {
+            throw new Error(`test object value at key "${String(key)}" did not match expected shape: ${reason}`);
+        }
+        const testValue = testThisOne[key];
+        const shouldMatch = compareToThisOne[key];
+        compareInnerValue(testValue, shouldMatch, throwKeyError);
+    });
+}
+exports.assertMatchesObjectShape = assertMatchesObjectShape;
+function compareInnerValue(testValue, matchValue, throwKeyError) {
+    var _a;
+    const testType = typeof testValue;
+    const shouldMatchType = typeof matchValue;
+    if (testType !== shouldMatchType) {
+        throwKeyError(`type "${testType}" did not match expected type "${shouldMatchType}"`);
+    }
+    try {
+        if (typedHasProperty(matchValue, 'constructor')) {
+            if (!typedHasProperty(testValue, 'constructor') ||
+                testValue.constructor !== matchValue.constructor) {
+                throwKeyError(`constructor "${(_a = testValue === null || testValue === void 0 ? void 0 : testValue.constructor) === null || _a === void 0 ? void 0 : _a.name}" did not match expected constructor "${matchValue.constructor}"`);
+            }
+        }
+    }
+    catch (error) {
+        // ignore errors from trying to find the constructor
+        if (error instanceof throwKeyError) {
+            throw error;
+        }
+    }
+    if (Array.isArray(matchValue)) {
+        if (!Array.isArray(testValue)) {
+            throwKeyError(`expected an array`);
+        }
+        testValue.forEach((testValueEntry, index) => {
+            const errors = matchValue
+                .map((matchValue) => {
+                try {
+                    compareInnerValue(testValueEntry, matchValue, throwKeyError);
+                    return undefined;
+                }
+                catch (error) {
+                    return new Error(`entry at index "${index}" did not match expected shape: ${(0, error_1.extractErrorMessage)(error)}`);
+                }
+            })
+                .filter(function_1.isTruthy);
+            if (errors.length === matchValue.length) {
+                throw new Error(`entry at index "${index}" did not match any of the possible types from "${matchValue.join(', ')}"`);
+            }
+        });
+    }
+    else if (isObject(matchValue)) {
+        assertMatchesObjectShape(testValue, matchValue);
+    }
+}

package/dist/augments/promise.d.ts

@@ -0,0 +1,16 @@
+export declare function wait(delayMs: number): Promise<void>;
+export declare function isPromiseLike<T>(input: T | unknown): input is T extends PromiseLike<infer ValueType> ? PromiseLike<ValueType> : PromiseLike<unknown>;
+export declare class PromiseTimeoutError extends Error {
+    readonly durationMs: number;
+    readonly message: string;
+    readonly name = "PromiseTimeoutError";
+    constructor(durationMs: number, message?: string);
+}
+export declare function wrapPromiseInTimeout<PromiseValueType>(durationMs: number, originalPromise: PromiseLike<PromiseValueType>): Promise<PromiseValueType>;
+/** A promise which can be resolved or rejected by external code. */
+export declare type DeferredPromiseWrapper<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+};
+export declare function createDeferredPromiseWrapper<T = void>(): DeferredPromiseWrapper<T>;

package/dist/augments/promise.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeferredPromiseWrapper = exports.wrapPromiseInTimeout = exports.PromiseTimeoutError = exports.isPromiseLike = exports.wait = void 0;
+const object_1 = require("./object");
+function wait(delayMs) {
+    const deferredPromiseWrapper = createDeferredPromiseWrapper();
+    if (delayMs === Infinity || delayMs < 0) {
+        return deferredPromiseWrapper.promise;
+    }
+    setTimeout(() => {
+        deferredPromiseWrapper.resolve();
+    }, delayMs);
+    return deferredPromiseWrapper.promise;
+}
+exports.wait = wait;
+function isPromiseLike(input) {
+    if ((0, object_1.typedHasProperty)(input, 'then') && typeof input.then === 'function') {
+        return true;
+    }
+    else {
+        return false;
+    }
+}
+exports.isPromiseLike = isPromiseLike;
+class PromiseTimeoutError extends Error {
+    constructor(durationMs, message = `Promised timed out after ${durationMs} ms.`) {
+        super(message);
+        this.durationMs = durationMs;
+        this.message = message;
+        this.name = 'PromiseTimeoutError';
+    }
+}
+exports.PromiseTimeoutError = PromiseTimeoutError;
+function wrapPromiseInTimeout(durationMs, originalPromise) {
+    return new Promise(async (resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            reject(new PromiseTimeoutError(durationMs));
+        }, durationMs);
+        try {
+            const result = await originalPromise;
+            resolve(result);
+        }
+        catch (error) {
+            reject(error);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    });
+}
+exports.wrapPromiseInTimeout = wrapPromiseInTimeout;
+function createDeferredPromiseWrapper() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolveCallback, rejectCallback) => {
+        resolve = resolveCallback;
+        reject = rejectCallback;
+    });
+    if (!resolve || !reject) {
+        throw new Error(`Reject and resolve callbacks were not set by the promise constructor for ${createDeferredPromiseWrapper.name}.`);
+    }
+    return {
+        promise,
+        resolve,
+        reject,
+    };
+}
+exports.createDeferredPromiseWrapper = createDeferredPromiseWrapper;

package/dist/augments/regexp.d.ts

@@ -0,0 +1,3 @@
+export declare function deDupeRegExFlags(flags: string): string;
+export declare function addRegExpFlags(originalRegExp: RegExp, flags: string): RegExp;
+export declare function safeMatch(input: string, regExp: RegExp): string[];

package/dist/augments/regexp.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeMatch = exports.addRegExpFlags = exports.deDupeRegExFlags = void 0;
+function deDupeRegExFlags(flags) {
+    const deDuped = new Set(Array.from(flags.toLowerCase()));
+    return Array.from(deDuped).join('');
+}
+exports.deDupeRegExFlags = deDupeRegExFlags;
+function addRegExpFlags(originalRegExp, flags) {
+    return new RegExp(originalRegExp.source, deDupeRegExFlags([
+        originalRegExp.flags,
+        flags,
+    ].join('')));
+}
+exports.addRegExpFlags = addRegExpFlags;
+function safeMatch(input, regExp) {
+    const match = input.match(regExp);
+    return match !== null && match !== void 0 ? match : [];
+}
+exports.safeMatch = safeMatch;

package/dist/augments/string.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Join elements into a string with commas separating each value. Add a conjunction before the final
+ * item in the list. If the array has a length < 2, the conjunction is not added. If the list is
+ * only of length 2, then no commas are added.
+ *
+ * @param list Array of items to be converted into strings. Works best if these are simply strings
+ *   to begin with.
+ * @param conjunction Defaults to 'and'. The conjunction to be used before the final element.
+ */
+export declare function joinWithFinalConjunction<T>(list: T[], conjunction?: string): string;
+export declare function removeAnsiEscapeCodes(input: string): string;
+export declare const removeColor: typeof removeAnsiEscapeCodes;
+export declare function removeCommasFromNumberString(numberString: string): string;
+/** Collapse all consecutive white space into just one space and trim surrounding whitespace. */
+export declare function collapseWhiteSpace(input: string): string;
+/** Same as String.prototype.split but includes the delimiter to split by in the output array. */
+export declare function splitIncludeSplit(original: string, splitterInput: string | RegExp, caseSensitive: boolean): string[];
+export declare type CasingOptions = {
+    capitalizeFirstLetter: boolean;
+};
+export declare function capitalizeFirstLetter(input: string): string;
+export declare function kebabCaseToCamelCase(rawKebabCase: string, casingOptions?: Partial<CasingOptions> | undefined): string;
+export declare function camelCaseToKebabCase(rawCamelCase: string): string;
+export declare function replaceStringAtIndex(originalString: string, start: number, newString: string, length?: number): string;
+/**
+ * Escapes characters from the given string so that it can be used within a RegExp without being
+ * parsed as RegExp syntax.
+ */
+export declare function escapeStringForRegExp(input: string): string;
+export declare function getAllIndexesOf(searchIn: string, searchForInput: string | RegExp, caseSensitive: boolean, includeLength: true): {
+    index: number;
+    length: number;
+}[];
+export declare function getAllIndexesOf(searchIn: string, searchForInput: string | RegExp, caseSensitive: boolean, includeLength?: false | undefined): number[];

package/dist/augments/string.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAllIndexesOf = exports.escapeStringForRegExp = exports.replaceStringAtIndex = exports.camelCaseToKebabCase = exports.kebabCaseToCamelCase = exports.capitalizeFirstLetter = exports.splitIncludeSplit = exports.collapseWhiteSpace = exports.removeCommasFromNumberString = exports.removeColor = exports.removeAnsiEscapeCodes = exports.joinWithFinalConjunction = void 0;
+const ansi_1 = require("./ansi");
+const regexp_1 = require("./regexp");
+/**
+ * Join elements into a string with commas separating each value. Add a conjunction before the final
+ * item in the list. If the array has a length < 2, the conjunction is not added. If the list is
+ * only of length 2, then no commas are added.
+ *
+ * @param list Array of items to be converted into strings. Works best if these are simply strings
+ *   to begin with.
+ * @param conjunction Defaults to 'and'. The conjunction to be used before the final element.
+ */
+function joinWithFinalConjunction(list, conjunction = 'and') {
+    if (list.length < 2) {
+        /**
+         * If there are not multiple things in the list to join, just turn the list into a string
+         * for an empty list, this will be '', for a single item list, this will just be the first
+         * item as a string.
+         */
+        return list.join('');
+    }
+    /** When there are only two items in the list, we don't want any commas. */
+    const commaSep = list.length > 2 ? ', ' : ' ';
+    const commaJoined = list.slice(0, -1).join(commaSep);
+    const fullyJoined = `${commaJoined}${commaSep}${conjunction} ${list[list.length - 1]}`;
+    return fullyJoined;
+}
+exports.joinWithFinalConjunction = joinWithFinalConjunction;
+function removeAnsiEscapeCodes(input) {
+    return input.replace(ansi_1.ansiRegex, '');
+}
+exports.removeAnsiEscapeCodes = removeAnsiEscapeCodes;
+exports.removeColor = removeAnsiEscapeCodes;
+function removeCommasFromNumberString(numberString) {
+    return numberString.replace(/,/g, '');
+}
+exports.removeCommasFromNumberString = removeCommasFromNumberString;
+/** Collapse all consecutive white space into just one space and trim surrounding whitespace. */
+function collapseWhiteSpace(input) {
+    return (input
+        // sometimes \n isn't included in \s
+        .replace(/\n/g, ' ')
+        .trim()
+        .replace(/\s{2,}/g, ' '));
+}
+exports.collapseWhiteSpace = collapseWhiteSpace;
+/** Same as String.prototype.split but includes the delimiter to split by in the output array. */
+function splitIncludeSplit(original, splitterInput, caseSensitive) {
+    const indexLengths = getAllIndexesOf(original, splitterInput, caseSensitive, true);
+    const splitter = makeCaseInsensitiveRegExp(splitterInput, caseSensitive);
+    const splits = original.split(splitter);
+    const splitterIncluded = splits.reduce((accum, current, index) => {
+        // this will be undefined on the last index
+        const splitterLength = indexLengths[index];
+        const includeCurrent = accum.concat(current);
+        if (splitterLength) {
+            const splitterMatch = original.slice(splitterLength.index, splitterLength.index + splitterLength.length);
+            return includeCurrent.concat(splitterMatch);
+        }
+        else {
+            return includeCurrent;
+        }
+    }, []);
+    return splitterIncluded;
+}
+exports.splitIncludeSplit = splitIncludeSplit;
+const defaultCasingOptions = {
+    capitalizeFirstLetter: false,
+};
+function capitalizeFirstLetter(input) {
+    var _a;
+    if (!input.length) {
+        return '';
+    }
+    const firstLetter = (_a = input[0]) !== null && _a !== void 0 ? _a : '';
+    return firstLetter.toUpperCase() + input.slice(1);
+}
+exports.capitalizeFirstLetter = capitalizeFirstLetter;
+function maybeCapitalize(input, casingOptions = defaultCasingOptions) {
+    return casingOptions.capitalizeFirstLetter ? capitalizeFirstLetter(input) : input;
+}
+function kebabCaseToCamelCase(rawKebabCase, casingOptions = defaultCasingOptions) {
+    const kebabCase = rawKebabCase.toLowerCase();
+    if (!kebabCase.length) {
+        return '';
+    }
+    const camelCase = kebabCase
+        .replace(/^-+/, '')
+        .replace(/-{2,}/g, '-')
+        .replace(/-(?:.|$)/g, (dashMatch) => {
+        const letter = dashMatch[1];
+        if (letter) {
+            return letter.toUpperCase();
+        }
+        else {
+            return '';
+        }
+    });
+    return maybeCapitalize(camelCase, casingOptions);
+}
+exports.kebabCaseToCamelCase = kebabCaseToCamelCase;
+function isLowerCase(input) {
+    // this excludes letters that are identical between lower and upper case like punctuation
+    return input !== input.toUpperCase();
+}
+function camelCaseToKebabCase(rawCamelCase) {
+    const kebabCase = rawCamelCase
+        .split('')
+        .reduce((accum, currentLetter, index, originalString) => {
+        var _a, _b;
+        const previousLetter = index > 0 ? (_a = originalString[index - 1]) !== null && _a !== void 0 ? _a : '' : '';
+        const nextLetter = index < originalString.length ? (_b = originalString[index + 1]) !== null && _b !== void 0 ? _b : '' : '';
+        const possibleWordBoundary = isLowerCase(previousLetter) || isLowerCase(nextLetter);
+        if (currentLetter === currentLetter.toLowerCase() ||
+            index === 0 ||
+            !possibleWordBoundary) {
+            accum += currentLetter;
+        }
+        else {
+            accum += `-${currentLetter.toLowerCase()}`;
+        }
+        return accum;
+    }, '')
+        .toLowerCase();
+    return kebabCase;
+}
+exports.camelCaseToKebabCase = camelCaseToKebabCase;
+function replaceStringAtIndex(originalString, start, newString, length = newString.length) {
+    const before = originalString.substring(0, start);
+    const after = originalString.substring(start + length);
+    return `${before}${newString}${after}`;
+}
+exports.replaceStringAtIndex = replaceStringAtIndex;
+/**
+ * Escapes characters from the given string so that it can be used within a RegExp without being
+ * parsed as RegExp syntax.
+ */
+function escapeStringForRegExp(input) {
+    return input.replace(/[\^$\\.*+?()[\]{}|]/g, '\\$&');
+}
+exports.escapeStringForRegExp = escapeStringForRegExp;
+function makeCaseInsensitiveRegExp(searchForInput, caseSensitive) {
+    const regExpFlags = `g${!caseSensitive && typeof searchForInput === 'string' ? 'i' : ''}`;
+    const searchFor = searchForInput instanceof RegExp
+        ? new RegExp(searchForInput.source, (0, regexp_1.deDupeRegExFlags)(`${searchForInput.flags}${regExpFlags}`))
+        : new RegExp(escapeStringForRegExp(searchForInput), regExpFlags);
+    return searchFor;
+}
+function getAllIndexesOf(searchIn, searchForInput, 
+/**
+ * CaseSensitive only applies when the input is a string. Otherwise, the RegExp's "i" flag is
+ * used to determine case sensitivity.
+ */
+caseSensitive, includeLength = false) {
+    const searchFor = makeCaseInsensitiveRegExp(searchForInput, caseSensitive);
+    const indexes = [];
+    const indexesAndLengths = [];
+    searchIn.replace(searchFor, (...matchResults) => {
+        /**
+         * Grabbing the second to last entry in the array (rather than the second) takes capture
+         * groups into account.
+         */
+        const matchIndex = matchResults[matchResults.length - 2];
+        if (typeof matchIndex !== 'number') {
+            throw new Error(`Match index "${matchIndex}" is not a number. Searching for "${searchForInput}" in "${searchIn}".`);
+        }
+        const regExpMatch = matchResults[0];
+        if (typeof regExpMatch !== 'string') {
+            throw new Error(`regExpMatch should've been a string but was ${typeof regExpMatch}!`);
+        }
+        indexesAndLengths.push({ index: matchIndex, length: regExpMatch.length });
+        indexes.push(matchIndex);
+        const originalMatch = matchResults[0];
+        if (typeof originalMatch !== 'string') {
+            throw new Error(`Original match when searching for "${searchForInput}" in "${searchIn}" at index ${matchIndex} is not a string.`);
+        }
+        /**
+         * Don't actually change any text. What we do here doesn't matter because we're not using
+         * the output of the .replace method, we're just producing side effects.
+         */
+        return originalMatch;
+    });
+    if (includeLength) {
+        return indexesAndLengths;
+    }
+    else {
+        return indexes;
+    }
+}
+exports.getAllIndexesOf = getAllIndexesOf;

package/dist/augments/tuple.d.ts

@@ -0,0 +1,8 @@
+export declare type Tuple<ArrayElementGeneric, LengthGeneric extends number> = LengthGeneric extends LengthGeneric ? number extends LengthGeneric ? ArrayElementGeneric[] : _TupleOf<ArrayElementGeneric, LengthGeneric, []> : never;
+declare type _TupleOf<ArrayElementGeneric, LengthGeneric extends number, FullArrayGeneric extends unknown[]> = FullArrayGeneric['length'] extends LengthGeneric ? FullArrayGeneric : _TupleOf<ArrayElementGeneric, LengthGeneric, [ArrayElementGeneric, ...FullArrayGeneric]>;
+export declare type AtLeastTuple<ArrayElementGeneric, LengthGeneric extends number> = readonly [
+    ...Tuple<ArrayElementGeneric, LengthGeneric>,
+    ...ArrayElementGeneric[]
+];
+export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
+export {};

package/dist/augments/tuple.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLengthAtLeast = void 0;
+function isLengthAtLeast(array, length) {
+    return array.length >= length;
+}
+exports.isLengthAtLeast = isLengthAtLeast;

package/dist/augments/type-test.d.ts

@@ -0,0 +1,3 @@
+import { Equal } from '@type-challenges/utils';
+export type { Alike, Debug, Equal, ExpectExtends as DoesExtend, ExpectFalse, ExpectTrue, ExpectValidArgs as HasValidArgs, IsAny, IsFalse, IsTrue, MergeInsertions, NotAny, NotEqual, UnionToIntersection, } from '@type-challenges/utils';
+export declare type CouldBeNullish<VALUE> = Equal<VALUE, NonNullable<VALUE>> extends true ? false : true;

package/dist/augments/type-test.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/augments/type.d.ts

@@ -0,0 +1,54 @@
+/** Makes all properties in an object writable. This is the opposite of Readonly<> */
+export declare type Writeable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+/** Makes all property values in an object also readonly. Can cause issues on primitive. */
+export declare type DeepWriteable<T> = {
+    -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
+/** Replace properties in T with properties in U. */
+export declare type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
+/** Extract the element type out of an array type. */
+export declare type ArrayElement<ArrayType extends ReadonlyArray<any>> = ArrayType[number];
+/**
+ * Same as the Required<> built-in type helper but this requires that each property be present and
+ * be not null.
+ */
+export declare type RequiredAndNotNull<T> = {
+    [P in keyof T]-?: NonNullable<T[P]>;
+};
+/** Require only a subset of object properties. */
+export declare type RequiredBy<T, K extends keyof T> = Overwrite<T, Required<Pick<T, K>>>;
+/**
+ * Require only a subset of object properties and require that they be not null. This is
+ * particularly useful in conjunction with the "exactOptionalPropertyTypes" tsconfig flag.
+ */
+export declare type RequiredAndNotNullBy<T, K extends keyof T> = Omit<T, K> & Required<{
+    [PropertyName in K]: NonNullable<T[PropertyName]>;
+}>;
+/** If type T = type U, then type Y. Else type N. */
+export declare type IfEquals<T, U, Y = unknown, N = never> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? Y : N;
+export declare type UnPromise<T> = T extends PromiseLike<infer PromiseType> ? Awaited<PromiseType> : T;
+/**
+ * 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 declare function wrapNarrowTypeWithTypeCheck<P>(): <T extends P>(input: T) => Readonly<T>;
+/**
+ * This type helper is useful for forcing function generics to be explicitly provided, rather than
+ * inferring them from the given inputs. See the test file for examples.
+ */
+export declare type NoInfer<T> = [T][T extends any ? 0 : never];
+/**
+ * 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 declare function ensureType<ExpectedType = never>(input: NoInfer<ExpectedType>): NoInfer<ExpectedType>;

package/dist/augments/type.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureType = exports.wrapNarrowTypeWithTypeCheck = void 0;
+/**
+ * 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.
+ */
+function wrapNarrowTypeWithTypeCheck() {
+    return (input) => {
+        return input;
+    };
+}
+exports.wrapNarrowTypeWithTypeCheck = wrapNarrowTypeWithTypeCheck;
+/**
+ * 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.
+ */
+function ensureType(input) {
+    return input;
+}
+exports.ensureType = ensureType;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './augments/ansi';
+export * from './augments/array';
+export * from './augments/date';
+export * from './augments/error';
+export * from './augments/function';
+export * from './augments/number';
+export * from './augments/object';
+export * from './augments/promise';
+export * from './augments/regexp';
+export * from './augments/string';
+export * from './augments/tuple';
+export * from './augments/type';
+export * from './augments/type-test';

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./augments/ansi"), exports);
+__exportStar(require("./augments/array"), exports);
+__exportStar(require("./augments/date"), exports);
+__exportStar(require("./augments/error"), exports);
+__exportStar(require("./augments/function"), exports);
+__exportStar(require("./augments/number"), exports);
+__exportStar(require("./augments/object"), exports);
+__exportStar(require("./augments/promise"), exports);
+__exportStar(require("./augments/regexp"), exports);
+__exportStar(require("./augments/string"), exports);
+__exportStar(require("./augments/tuple"), exports);
+__exportStar(require("./augments/type"), exports);
+__exportStar(require("./augments/type-test"), exports);

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@augment-vir/common",
+    "version": "4.0.0",
+    "homepage": "https://github.com/electrovir/augment-vir/tree/main/packages/common",
+    "bugs": {
+        "url": "https://github.com/electrovir/augment-vir/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/electrovir/augment-vir"
+    },
+    "license": "MIT",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "compile": "rm -rf dist && virmator compile",
+        "docs:update": "virmator code-in-markdown",
+        "test": "echo \"use common-test to run tests\" && exit 0"
+    },
+    "dependencies": {
+        "@type-challenges/utils": "^0.1.1"
+    },
+    "devDependencies": {
+        "prettier": "^2.7.1",
+        "prettier-plugin-jsdoc": "^0.4.2",
+        "prettier-plugin-multiline-arrays": "^1.1.1",
+        "prettier-plugin-organize-imports": "^3.2.0",
+        "prettier-plugin-packagejson": "^2.3.0",
+        "prettier-plugin-sort-json": "^0.0.3",
+        "prettier-plugin-toml": "^0.3.1",
+        "ts-node": "^10.9.1",
+        "typescript": "^4.8.4"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}