complete-common 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,705 @@
+declare const SECOND_IN_MILLISECONDS = 1000;
+declare const MINUTE_IN_MILLISECONDS: number;
+declare const HOUR_IN_MILLISECONDS: number;
+
+/**
+ * Helper function to copy a two-dimensional array. Note that the sub-arrays will only be shallow
+ * copied (using the spread operator).
+ */
+declare function arrayCopyTwoDimensional<T>(array: ReadonlyArray<readonly T[]>): T[][];
+/**
+ * Helper function for determining if two arrays contain the exact same elements. Note that this
+ * only performs a shallow comparison.
+ */
+declare function arrayEquals<T>(array1: readonly T[], array2: readonly T[]): boolean;
+/**
+ * Builds a new array based on the original array without the specified element(s). Returns the new
+ * array. If the specified element(s) are not found in the array, it will simply return a shallow
+ * copy of the array.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ */
+declare function arrayRemove<T>(originalArray: readonly T[], ...elementsToRemove: readonly T[]): T[];
+/**
+ * Removes the specified element(s) from the array. If the specified element(s) are not found in the
+ * array, this function will do nothing.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ *
+ * If there is more than one matching element in the array, this function will only remove the first
+ * matching element. If you want to remove all of the elements, use the `arrayRemoveAllInPlace`
+ * function instead.
+ *
+ * @returns The removed elements. This will be an empty array if no elements were removed.
+ */
+declare function arrayRemoveInPlace<T>(array: T[], ...elementsToRemove: readonly T[]): T[];
+/** Helper function to remove all of the elements in an array in-place. */
+declare function emptyArray<T>(array: T[]): void;
+/**
+ * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because the `Array.map` method will always produce an array with the same
+ * amount of elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ */
+declare function filterMap<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => NewT | undefined): NewT[];
+/**
+ * Helper function to get a random element from the provided array.
+ *
+ * Note that this will only work with arrays that do not contain values of `undefined`, since the
+ * function uses `undefined` as an indication that the corresponding element does not exist.
+ *
+ * @param array The array to get an element from.
+ * @param exceptions Optional. An array of elements to skip over if selected.
+ */
+declare function getRandomArrayElement<T>(array: readonly T[], exceptions?: readonly T[]): T;
+/**
+ * Helper function to get a random index from the provided array.
+ *
+ * @param array The array to get the index from.
+ * @param exceptions Optional. An array of indexes that will be skipped over when getting the random
+ *                   index. Default is an empty array.
+ */
+declare function getRandomArrayIndex<T>(array: readonly T[], exceptions?: readonly number[]): number;
+/**
+ * Similar to the `Array.includes` method, but works on a widened version of the array.
+ *
+ * This is useful when the normal `Array.includes` produces a type error from an array that uses an
+ * `as const` assertion.
+ */
+declare function includes<T, TupleElement extends WidenLiteral<T>>(array: readonly TupleElement[], searchElement: WidenLiteral<T>): searchElement is TupleElement;
+/** A wrapper around `Array.isArray` that narrows to `unknown[]` instead of `any[]`. */
+declare function isArray(arg: unknown): arg is unknown[];
+/** Initializes an array with all elements containing the specified default value. */
+declare function newArray<T>(length: number, value: T): T[];
+/** Helper function to sum every value in an array together. */
+declare function sumArray(array: readonly number[]): number;
+
+type TranspiledEnum = Record<string, string | number>;
+/**
+ * Helper function to get the entries of an enum.
+ *
+ * (By default, TypeScript will put the keys inside of the values of a number-based enum, so those
+ * have to be filtered out.)
+ *
+ * This function will work properly for both number and string enums.
+ */
+declare function getEnumEntries<T extends TranspiledEnum>(transpiledEnum: T): ReadonlyArray<[key: string, value: T[keyof T]]>;
+/**
+ * Helper function to get the keys of an enum.
+ *
+ * (By default, TypeScript will put the keys inside of the values of a number-based enum, so those
+ * have to be filtered out.)
+ *
+ * This function will work properly for both number and string enums.
+ */
+declare function getEnumKeys(transpiledEnum: TranspiledEnum): readonly string[];
+/**
+ * Helper function to get the only the values of an enum.
+ *
+ * (By default, TypeScript will put the keys inside of the values of a number-based enum, so those
+ * have to be filtered out.)
+ *
+ * This function will work properly for both number and string enums.
+ */
+declare function getEnumValues<T extends TranspiledEnum>(transpiledEnum: T): ReadonlyArray<T[keyof T]>;
+/**
+ * Helper function to validate that an interface contains all of the keys of an enum. You must
+ * specify both generic parameters in order for this to work properly (i.e. the interface and then
+ * the enum).
+ *
+ * For example:
+ *
+ * ```ts
+ * enum MyEnum {
+ *   Value1,
+ *   Value2,
+ *   Value3,
+ * }
+ *
+ * interface MyEnumToType {
+ *   [MyEnum.Value1]: boolean;
+ *   [MyEnum.Value2]: number;
+ *   [MyEnum.Value3]: string;
+ * }
+ *
+ * interfaceSatisfiesEnum<MyEnumToType, MyEnum>();
+ * ```
+ *
+ * This function is only meant to be used with interfaces (i.e. types that will not exist at
+ * run-time). If you are generating an object that will contain all of the keys of an enum, use the
+ * `satisfies` operator with the `Record` type instead.
+ */
+declare function interfaceSatisfiesEnum<T extends Record<Enum, unknown>, Enum extends string | number>(): void;
+/**
+ * Helper function to validate that a particular value exists inside of an enum.
+ *
+ * @param value The value to check.
+ * @param transpiledEnum The enum to check against.
+ * @param set Optional. A set that contains all of the values of an enum. If provided, this function
+ *            will check for existence using the set (instead of the enum itself). Using a set
+ *            should be more performant for enums with around 52 or more elements.
+ */
+declare function isEnumValue<T extends TranspiledEnum>(value: number | string, transpiledEnum: T, set?: ReadonlySet<string | number>): value is T[keyof T];
+
+/**
+ * Helper function to get the values in a `Map` that match an arbitrary condition. Similar to the
+ * `Array.map` method, but works for maps.
+ *
+ * This is efficient such that it avoids converting the map values into an array.
+ *
+ * If you want to perform a filter and a map at the same time on an array, use the `filterMap`
+ * helper function instead.
+ */
+declare function mapFilter<K, V>(map: ReadonlyMap<K, V>, predicate: (value: V) => boolean): V[];
+/**
+ * Helper function to find a value in a `Map`. Similar to the `Array.find` method, but works for
+ * maps.
+ *
+ * This is efficient such that it avoids converting the map values into an array.
+ */
+declare function mapFind<K, V>(map: ReadonlyMap<K, V>, predicate: (value: V) => boolean): V | undefined;
+/**
+ * Helper function to convert an object to a map.
+ *
+ * This is useful when you need to construct a type safe object with the `satisfies` operator, but
+ * then later on you need to query it in a way where you expect the return value to be T or
+ * undefined. In this situation, by converting the object to a map, you can avoid unsafe type
+ * assertions.
+ *
+ * Note that the map values will be inserted in a random order, due to how `pairs` works under the
+ * hood.
+ *
+ * Also see the `objectToReadonlyMap` function.
+ */
+declare function objectToMap<K extends string | number | symbol, V>(object: Record<K, V>): Map<K, V>;
+/**
+ * Helper function to convert an object to a read-only map.
+ *
+ * This is useful when you need to construct a type safe object with the `satisfies` operator, but
+ * then later on you need to query it in a way where you expect the return value to be T or
+ * undefined. In this situation, by converting the object to a map, you can avoid unsafe type
+ * assertions.
+ *
+ * Note that the map values will be inserted in a random order, due to how `pairs` works under the
+ * hood.
+ *
+ * Also see the `objectToMap` function.
+ */
+declare function objectToReadonlyMap<K extends string | number | symbol, V>(object: Record<K, V>): ReadonlyMap<K, V>;
+
+/**
+ * Helper function to normalize a number, ensuring that it is within a certain range.
+ *
+ * - If `num` is less than `min`, then it will be clamped to `min`.
+ * - If `num` is greater than `max`, then it will be clamped to `max`.
+ */
+declare function clamp(num: number, min: number, max: number): number;
+
+type ReadonlyRecord<K extends string | number | symbol, V> = Readonly<Record<K, V>>;
+
+/**
+ * Helper function to get the values in an object that match an arbitrary condition. Similar to the
+ * `Array.map` method, but works for objects.
+ *
+ * This is efficient such that it avoids converting the object values into an array.
+ */
+
+declare function objectFilter<K extends string | number | symbol, V>(object: ReadonlyRecord<K, V>, predicate: (value: V) => boolean): V[];
+
+/**
+ * This returns a random integer between min and max. It is inclusive on both ends.
+ *
+ * For example:
+ *
+ * ```ts
+ * const oneTwoOrThree = getRandomInt(1, 3);
+ * ```
+ *
+ * @param min The lower bound for the random number (inclusive).
+ * @param max The upper bound for the random number (inclusive).
+ * @param exceptions Optional. An array of elements that will be skipped over when getting the
+ *                   random integer. For example, a min of 1, a max of 4, and an exceptions array of
+ *                   `[2]` would cause the function to return either 1, 3, or 4. Default is an empty
+ *                   array.
+ */
+declare function getRandomInt(min: number, max: number, exceptions?: readonly number[]): number;
+
+/**
+ * Helper function to add all of the values in one set to another set. The first set passed will be
+ * modified in place.
+ *
+ * This function is variadic, meaning that you can specify N sets to add to the first set.
+ */
+declare function addSetsToSet<T>(mainSet: Set<T>, ...setsToAdd: ReadonlyArray<ReadonlySet<T>>): void;
+/**
+ * Helper function to create a new set that is the composition of two or more sets.
+ *
+ * This function is variadic, meaning that you can specify N sets.
+ */
+declare function combineSets<T>(...sets: ReadonlyArray<ReadonlySet<T>>): Set<T>;
+/** Helper function to copy a set. (You can also use a Set constructor to accomplish this task.) */
+declare function copySet<T>(oldSet: ReadonlySet<T>): Set<T>;
+/**
+ * Helper function to convert the keys of an object to a read-only set.
+ *
+ * Also see the `objectKeysToSet` function.
+ */
+declare function objectKeysToReadonlySet<K extends string | number | symbol, V>(object: Record<K, V>): ReadonlySet<K>;
+/**
+ * Helper function to convert the keys of an object to a set.
+ *
+ * Also see the `objectKeysToReadonlySet` function.
+ */
+declare function objectKeysToSet<K extends string | number | symbol, V>(object: Record<K, V>): Set<K>;
+/**
+ * Helper function to convert the values of an object to a read-only set.
+ *
+ * Also see the `objectValuesToSet` function.
+ */
+declare function objectValuesToReadonlySet<K extends string | number | symbol, V>(object: Record<K, V>): ReadonlySet<V>;
+/**
+ * Helper function to convert the values of an object to a set.
+ *
+ * Also see the `objectValuesToReadonlySet` function.
+ */
+declare function objectValuesToSet<K extends string | number | symbol, V>(object: Record<K, V>): Set<V>;
+/**
+ * Helper function to add one or more elements to a set at once without having to repeatedly call
+ * the `Set.add` method.
+ *
+ * This function is variadic, meaning that you can pass as many things as you want to add.
+ */
+declare function setAdd<T>(set: Set<T>, ...elements: readonly T[]): void;
+/**
+ * Helper function to check for one or more elements in a set at once without having to repeatedly
+ * call the `Set.has` method.
+ *
+ * This function is variadic, meaning that you can pass as many things as you want to check for. It
+ * will return true if one or more elements are found.
+ */
+declare function setHas<T>(set: ReadonlySet<T>, ...elements: readonly T[]): boolean;
+
+/**
+ * Helper function to perform a case insensitive sort. This will copy the provided array and return
+ * the sorted copy.
+ *
+ * From:
+ * https://stackoverflow.com/questions/8996963/how-to-perform-case-insensitive-sorting-array-of-string-in-javascript
+ */
+declare function sortCaseInsensitive(array: readonly string[]): string[];
+
+declare function capitalizeFirstLetter(string: string): string;
+/**
+ * Helper function to replace all of the ampersands, less than signs, greater than signs, double
+ * quotes, and single quotes in a string with the escaped counterparts. For example, "<" will be
+ * replaced with "&lt;".
+ */
+declare function escapeHTMLCharacters(string: string): string;
+declare function getNumConsecutiveDiacritics(string: string): number;
+declare function hasDiacritic(string: string): boolean;
+declare function hasEmoji(string: string): boolean;
+/** From: https://stackoverflow.com/questions/1731190/check-if-a-string-has-white-space */
+declare function hasWhitespace(string: string): boolean;
+/**
+ * From:
+ * https://stackoverflow.com/questions/8334606/check-if-first-letter-of-word-is-a-capital-letter
+ */
+declare function isFirstLetterCapitalized(string: string): boolean;
+/** Kebab case is the naming style of using all lowercase and hyphens, like "foo-bar". */
+declare function isKebabCase(string: string): boolean;
+/**
+ * Helper function to check if a given string is a valid Semantic Version.
+ *
+ * @see https://semver.org/
+ */
+declare function isSemanticVersion(versionString: string): boolean;
+declare function kebabCaseToCamelCase(string: string): string;
+/**
+ * Helper function to normalize a string. Specifically, this performs the following steps:
+ *
+ * - Removes any non-printable characters, if any.
+ * - Normalizes all newlines to "\n".
+ * - Normalizes all spaces to " ".
+ * - Removes leading/trailing whitespace.
+ *
+ * @see
+ * https://stackoverflow.com/questions/11598786/how-to-replace-non-printable-unicode-characters-javascript
+ */
+declare function normalizeString(string: string): string;
+/**
+ * Helper function to parse a Semantic Versioning string into its individual constituents. Returns
+ * undefined if the submitted string was not a proper Semantic Version.
+ *
+ * @see https://semver.org/
+ */
+declare function parseSemanticVersion(versionString: string): {
+    majorVersion: number;
+    minorVersion: number;
+    patchVersion: number;
+} | undefined;
+/**
+ * Helper function to remove lines from a multi-line string. This function looks for a "-start" and
+ * a "-end" suffix after the marker. Lines with markets will be completely removed from the output.
+ *
+ * For example, by using a marker of "@foo":
+ *
+ * ```text
+ * line1
+ * # @foo-start
+ * line2
+ * line3
+ * # @foo-end
+ * line4
+ * ```
+ *
+ * Would return:
+ *
+ * ```text
+ * line1
+ * line4
+ * ```
+ */
+declare function removeLinesBetweenMarkers(string: string, marker: string): string;
+/** Helper function to remove lines from a multi-line string matching a certain other string. */
+declare function removeLinesMatching(string: string, match: string): string;
+/**
+ * Helper function to remove all non-printable characters from a string.
+ *
+ * @see
+ * https://stackoverflow.com/questions/11598786/how-to-replace-non-printable-unicode-characters-javascript
+ */
+declare function removeNonPrintableCharacters(string: string): string;
+/** Helper function to remove all whitespace characters from a string. */
+declare function removeWhitespace(string: string): string;
+/**
+ * Helper function to trim a prefix from a string, if it exists. Returns the trimmed string.
+ *
+ * @param string The string to trim.
+ * @param prefix The prefix to trim.
+ * @param trimAll Whether to remove multiple instances of the prefix, if they exist. If this is set
+ *                to true, the prefix must only be a single character.
+ */
+declare function trimPrefix(string: string, prefix: string, trimAll?: boolean): string;
+/** Helper function to trim a suffix from a string, if it exists. Returns the trimmed string. */
+declare function trimSuffix(string: string, prefix: string): string;
+/**
+ * Helper function to truncate a string to a maximum length. If the length of the string is less
+ * than or equal to the provided maximum length, the string will be returned unmodified.
+ */
+declare function truncateString(string: string, maxLength: number): string;
+
+/**
+ * Helper type to represent a tuple of length N.
+ *
+ * From:
+ * https://stackoverflow.com/questions/52489261/typescript-can-i-define-an-n-length-tuple-type/52490977#52490977
+ */
+type Tuple<T, N extends number> = N extends N ? number extends N ? T[] : _TupleOf<T, N, []> : never;
+type _TupleOf<T, N extends number, R extends unknown[]> = R["length"] extends N ? R : _TupleOf<T, N, [T, ...R]>;
+
+type TupleKey<T extends readonly unknown[]> = {
+    [L in T["length"]]: Exclude<Partial<Tuple<unknown, L>>["length"], L>;
+}[T["length"]];
+type TupleValue<T extends readonly unknown[]> = T[0];
+type TupleEntry<T extends readonly unknown[]> = [TupleKey<T>, TupleValue<T>];
+/**
+ * Helper function to get the entries (i.e. indexes and values) of a tuple in a type-safe way.
+ *
+ * This is useful because the vanilla `Array.entries` method will always have the keys be of type
+ * `number`.
+ */
+declare function tupleEntries<T extends readonly unknown[]>(tuple: T): Generator<TupleEntry<T>>;
+/**
+ * Helper function to get the keys (i.e. indexes) of a tuple in a type-safe way.
+ *
+ * This is useful because the vanilla `Array.keys` method will always have the keys be of type
+ * `number`.
+ */
+declare function tupleKeys<T extends readonly unknown[]>(tuple: T): Generator<TupleKey<T>>;
+
+/**
+ * Helper function to narrow an unknown value to an object (i.e. a TypeScript record).
+ *
+ * Under the hood, this checks for `typeof variable === "object"`, `variable !== null`, and
+ * `!Array.isArray(variable)`.
+ */
+declare function isObject(variable: unknown): variable is Record<string, unknown>;
+
+/**
+ * Helper function to throw an error if the provided value is equal to `undefined`.
+ *
+ * This is useful to have TypeScript narrow a `T | undefined` value to `T` in a concise way.
+ */
+declare function assertDefined<T>(value: T, ...[msg]: [undefined] extends [T] ? [string] : [
+    "The assertion is useless because the provided value does not contain undefined."
+]): asserts value is Exclude<T, undefined>;
+/**
+ * Helper function to throw an error if the provided value is equal to `null`.
+ *
+ * This is useful to have TypeScript narrow a `T | null` value to `T` in a concise way.
+ */
+declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T] ? [string] : [
+    "The assertion is useless because the provided value does not contain null."
+]): asserts value is Exclude<T, null>;
+/**
+ * Helper function to get an iterator of integers with the specified range, inclusive on the lower
+ * end and exclusive on the high end. (The "e" in the function name stands for exclusive.) Thus,
+ * this function works in the same way as the built-in `range` function from Python.
+ *
+ * If the end is lower than the start, then an empty range will be returned.
+ *
+ * For example:
+ *
+ * - `eRange(2)` returns `[0, 1]`.
+ * - `eRange(3)` returns `[0, 1, 2]`.
+ * - `eRange(-3)` returns `[0, -1, -2]`.
+ * - `eRange(1, 3)` returns `[1, 2]`.
+ * - `eRange(2, 5)` returns `[2, 3, 4]`.
+ * - `eRange(5, 2)` returns `[]`.
+ * - `eRange(3, 3)` returns `[]`.
+ *
+ * If you want an array instead of an iterator, use the spread operator like this:
+ *
+ * ```ts
+ * const myArray = [...eRange(1, 3)];
+ * ```
+ *
+ * @param start The integer to start at.
+ * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
+ *            first argument will be the end.
+ * @param increment Optional. The increment to use. Default is 1.
+ */
+declare function eRange(start: number, end?: number, increment?: number): Generator<number>;
+/**
+ * Helper function to get an array of integers with the specified range, inclusive on both ends.
+ * (The "i" in the function name stands for inclusive.)
+ *
+ * If the end is lower than the start, then an empty range will be returned.
+ *
+ * For example:
+ *
+ * - `iRange(2)` returns `[0, 1, 2]`.
+ * - `iRange(3)` returns `[0, 1, 2, 3]`.
+ * - `iRange(-3)` returns `[0, -1, -2, -3]`.
+ * - `iRange(1, 3)` returns `[1, 2, 3]`.
+ * - `iRange(2, 5)` returns `[2, 3, 4, 5]`.
+ * - `iRange(5, 2)` returns `[]`.
+ * - `iRange(3, 3)` returns `[3]`.
+ *
+ * If you want an array instead of an iterator, use the spread operator like this:
+ *
+ * ```ts
+ * const myArray = [...eRange(1, 3)];
+ * ```
+ *
+ * @param start The integer to start at.
+ * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
+ *            first argument will be the end.
+ * @param increment Optional. The increment to use. Default is 1.
+ */
+declare function iRange(start: number, end?: number, increment?: number): Generator<number>;
+/** From: https://stackoverflow.com/questions/61526746 */
+declare function isKeyOf<T extends object>(key: PropertyKey, target: T): key is keyof T;
+/**
+ * Helper function to perform a no-op. This can be useful in order to make a trailing return valid
+ * in functions that use the early return pattern.
+ */
+declare function noop(): void;
+/**
+ * This is a more reliable version of `Number.parseFloat`:
+ *
+ * - `undefined` is returned instead of `Number.NaN`, which is helpful in conjunction with
+ *   TypeScript type narrowing patterns.
+ * - Strings that are a mixture of numbers and letters will result in undefined instead of the part
+ *   of the string that is the number. (e.g. "1a" --> undefined instead of "1a" --> 1)
+ * - Non-strings will result in undefined instead of being coerced to a number.
+ *
+ * @param string A string to convert to an integer.
+ */
+declare function parseFloatSafe(string: string): number | undefined;
+/**
+ * This is a more reliable version of `Number.parseInt`:
+ *
+ * - `undefined` is returned instead of `Number.NaN`, which is helpful in conjunction with
+ *   TypeScript type narrowing patterns.
+ * - Strings that are a mixture of numbers and letters will result in undefined instead of the part
+ *   of the string that is the number. (e.g. "1a" --> undefined instead of "1a" --> 1)
+ * - Non-strings will result in undefined instead of being coerced to a number.
+ *
+ * If you have to use a radix other than 10, use the vanilla `Number.parseInt` function instead,
+ * because this function ensures that the string contains no letters.
+ */
+declare function parseIntSafe(string: string): number | undefined;
+/**
+ * Helper function to repeat code N times. This is faster to type and cleaner than using a for loop.
+ *
+ * For example:
+ *
+ * ```ts
+ * repeat(10, () => {
+ *   foo();
+ * });
+ * ```
+ *
+ * The repeated function is passed the index of the iteration, if needed:
+ *
+ * ```ts
+ * repeat(3, (i) => {
+ *   console.log(i); // Prints "0", "1", "2"
+ * });
+ * ```
+ */
+declare function repeat(num: number, func: (i: number) => void): void;
+/**
+ * Helper function to signify that the enclosing code block is not yet complete. Using this function
+ * is similar to writing a "TODO" comment, but it has the benefit of preventing ESLint errors due to
+ * unused variables or early returns.
+ *
+ * When you see this function, it simply means that the programmer intends to add in more code to
+ * this spot later.
+ *
+ * This function is variadic, meaning that you can pass as many arguments as you want. (This is
+ * useful as a means to prevent unused variables.)
+ *
+ * This function does not actually do anything. (It is an "empty" function.)
+ *
+ * @allowEmptyVariadic
+ */
+declare function todo(...args: readonly unknown[]): void;
+
+/** From: https://gist.github.com/ryandabler/8b4ff4f36aed47bc09acc03174638468 */
+type Add<A extends number, B extends number> = Length<[
+    ...BuildTuple<A>,
+    ...BuildTuple<B>
+]>;
+/** From: https://gist.github.com/ryandabler/8b4ff4f36aed47bc09acc03174638468 */
+type Subtract<A extends number, B extends number> = A extends A ? BuildTuple<A> extends [...infer U, ...BuildTuple<B>] ? Length<U> : never : never;
+type BuildTuple<L extends number, T extends unknown[] = []> = T extends {
+    length: L;
+} ? T : BuildTuple<L, [...T, unknown]>;
+type Length<T extends unknown[]> = T extends {
+    length: infer L;
+} ? L : never;
+
+/**
+ * Helper type to validate that a union of interfaces with a field of `type` that is based on an
+ * enum is complete.
+ *
+ * For example:
+ *
+ * ```ts
+ * enum ObjectiveType {
+ *   Foo,
+ *   Bar,
+ *   Baz,
+ * }
+ *
+ * interface FooObjective {
+ *   type: ObjectiveType.Foo;
+ *   fooThing: number;
+ * }
+ *
+ * interface BarObjective {
+ *   type: ObjectiveType.Bar;
+ *   barThing: string;
+ * }
+ *
+ * type Objective = FooObjective | BarObjective;
+ * type _Test = CompositionTypeSatisfiesEnum<Objective, ObjectiveType>;
+ * ```
+ *
+ * In this example, `Test` would be flagged by TypeScript because `Objective` does not contain an
+ * entry for `BazObjective`.
+ */
+type CompositionTypeSatisfiesEnum<T extends {
+    type: unknown;
+}, Enum extends T["type"]> = unknown;
+
+/**
+ * Helper type to get a range of integers between 0 and N - 1.
+ *
+ * From:
+ * https://stackoverflow.com/questions/39494689/is-it-possible-to-restrict-number-to-a-certain-range
+ */
+type NaturalNumbersLessThan<N extends number, Acc extends number[] = []> = Acc["length"] extends N ? Acc[number] : NaturalNumbersLessThan<N, [...Acc, Acc["length"]]>;
+
+/**
+ * Helper type to get a range of integers. It is inclusive on the lower end and exclusive on the
+ * high end. (The "E" in the type name stands for exclusive.)
+ *
+ * For example, `ERange<3, 5>` will return `3 | 4`.
+ *
+ * From:
+ * https://stackoverflow.com/questions/39494689/is-it-possible-to-restrict-number-to-a-certain-range
+ */
+type ERange<Low extends number, High extends number> = Exclude<NaturalNumbersLessThan<High>, NaturalNumbersLessThan<Low>>;
+
+/**
+ * Immutable is a utility type that will make the given array/map/set/object recursively read-only.
+ *
+ * You can use this type to easily build safe data structures.
+ *
+ * From: https://stackoverflow.com/questions/41879327/deepreadonly-object-typescript
+ */
+type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
+type ImmutablePrimitive = undefined | null | boolean | string | number | Function;
+type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
+type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
+type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
+type ImmutableObject<T> = {
+    readonly [K in keyof T]: Immutable<T[K]>;
+};
+
+/**
+ * Helper type to get a range of integers between 0 and N.
+ *
+ * From:
+ * https://stackoverflow.com/questions/39494689/is-it-possible-to-restrict-number-to-a-certain-range
+ */
+type NaturalNumbersLessThanOrEqualTo<N extends number, T extends number[] = []> = T extends [unknown, ...infer Tail] ? Tail["length"] extends N ? T[number] : NaturalNumbersLessThanOrEqualTo<N, [...T, T["length"]]> : NaturalNumbersLessThanOrEqualTo<N, [...T, T["length"]]>;
+
+/**
+ * Helper type to get a range of integers. It is inclusive on both ends. (The "I" in the type name
+ * stands for inclusive.)
+ *
+ * For example, `IRange<3, 5>` will return `3 | 4 | 5`.
+ *
+ * From:
+ * https://stackoverflow.com/questions/39494689/is-it-possible-to-restrict-number-to-a-certain-range
+ */
+type IRange<Low extends number, High extends number> = Exclude<NaturalNumbersLessThanOrEqualTo<High>, NaturalNumbersLessThan<Low>>;
+
+type ObjectValues<T> = T[keyof T];
+
+interface ReadonlyMapConstructor {
+    new (): ReadonlyMap<any, any>;
+    new <K, V>(entries?: ReadonlyArray<readonly [K, V]> | Iterable<readonly [K, V]> | null): ReadonlyMap<K, V>;
+    readonly prototype: ReadonlyMap<any, any>;
+}
+/** An alias for the `Map` constructor that returns a read-only map. */
+declare const ReadonlyMap: ReadonlyMapConstructor;
+
+interface ReadonlySetConstructor {
+    new <T = any>(values?: readonly T[] | Iterable<T> | null): ReadonlySet<T>;
+    readonly prototype: ReadonlySet<any>;
+}
+/** An alias for the `Set` constructor that returns a read-only set. */
+declare const ReadonlySet: ReadonlySetConstructor;
+
+type WidenLiteral<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends bigint ? bigint : T extends symbol ? symbol : T;
+
+/**
+ * Helper type to convert a read-only object into a writable object.
+ *
+ * This is the opposite of the built-in `Readonly` utility type.
+ */
+type Writeable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+
+export { type Add, type CompositionTypeSatisfiesEnum, type ERange, HOUR_IN_MILLISECONDS, type IRange, type Immutable, MINUTE_IN_MILLISECONDS, type NaturalNumbersLessThan, type NaturalNumbersLessThanOrEqualTo, type ObjectValues, ReadonlyMap as ReadonlyMap, type ReadonlyRecord, ReadonlySet as ReadonlySet, SECOND_IN_MILLISECONDS, type Subtract, type Tuple, type WidenLiteral, type Writeable, addSetsToSet, arrayCopyTwoDimensional, arrayEquals, arrayRemove, arrayRemoveInPlace, assertDefined, assertNotNull, capitalizeFirstLetter, clamp, combineSets, copySet, eRange, emptyArray, escapeHTMLCharacters, filterMap, getEnumEntries, getEnumKeys, getEnumValues, getNumConsecutiveDiacritics, getRandomArrayElement, getRandomArrayIndex, getRandomInt, hasDiacritic, hasEmoji, hasWhitespace, iRange, includes, interfaceSatisfiesEnum, isArray, isEnumValue, isFirstLetterCapitalized, isKebabCase, isKeyOf, isObject, isSemanticVersion, kebabCaseToCamelCase, mapFilter, mapFind, newArray, noop, normalizeString, objectFilter, objectKeysToReadonlySet, objectKeysToSet, objectToMap, objectToReadonlyMap, objectValuesToReadonlySet, objectValuesToSet, parseFloatSafe, parseIntSafe, parseSemanticVersion, removeLinesBetweenMarkers, removeLinesMatching, removeNonPrintableCharacters, removeWhitespace, repeat, setAdd, setHas, sortCaseInsensitive, sumArray, todo, trimPrefix, trimSuffix, truncateString, tupleEntries, tupleKeys };