complete-common 1.0.0

package/src/functions/utils.ts

@@ -0,0 +1,238 @@
+// When regexes are located at the root instead of inside the function, the functions are tested to
+// perform 11% faster.
+
+const FLOAT_REGEX = /^-?\d*\.?\d+$/;
+const INTEGER_REGEX = /^-?\d+$/;
+
+/**
+ * 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.
+ */
+export 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> {
+  if (value === undefined) {
+    throw new TypeError(msg);
+  }
+}
+
+/**
+ * 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.
+ */
+export 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> {
+  if (value === null) {
+    throw new TypeError(msg);
+  }
+}
+
+/**
+ * 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.
+ */
+export function* eRange(
+  start: number,
+  end?: number,
+  increment = 1,
+): Generator<number> {
+  if (end === undefined) {
+    yield* eRange(0, start, increment);
+    return;
+  }
+
+  for (let i = start; i < end; i += increment) {
+    yield i;
+  }
+}
+
+/**
+ * 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.
+ */
+export function* iRange(
+  start: number,
+  end?: number,
+  increment = 1,
+): Generator<number> {
+  if (end === undefined) {
+    yield* iRange(0, start, increment);
+    return;
+  }
+
+  const exclusiveEnd = end + 1;
+  yield* eRange(start, exclusiveEnd, increment);
+}
+
+/** From: https://stackoverflow.com/questions/61526746 */
+export function isKeyOf<T extends object>(
+  key: PropertyKey,
+  target: T,
+): key is keyof T {
+  return key in target;
+}
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export 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.
+ */
+export function parseFloatSafe(string: string): number | undefined {
+  if (typeof string !== "string") {
+    return undefined;
+  }
+
+  const trimmedString = string.trim();
+
+  // If the string does not entirely consist of numbers, return undefined.
+  if (FLOAT_REGEX.exec(trimmedString) === null) {
+    return undefined;
+  }
+
+  const number = Number.parseFloat(trimmedString);
+  return Number.isNaN(number) ? undefined : number;
+}
+
+/**
+ * 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.
+ */
+export function parseIntSafe(string: string): number | undefined {
+  if (typeof string !== "string") {
+    return undefined;
+  }
+
+  const trimmedString = string.trim();
+
+  // If the string does not entirely consist of numbers, return undefined.
+  if (INTEGER_REGEX.exec(trimmedString) === null) {
+    return undefined;
+  }
+
+  const number = Number.parseInt(trimmedString, 10);
+  return Number.isNaN(number) ? undefined : number;
+}
+
+/**
+ * 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"
+ * });
+ * ```
+ */
+export function repeat(num: number, func: (i: number) => void): void {
+  for (let i = 0; i < num; i++) {
+    func(i);
+  }
+}
+
+/**
+ * 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
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-empty-function
+export function todo(...args: readonly unknown[]): void {}

package/src/index.ts

@@ -0,0 +1,27 @@
+export * from "./constants.js";
+export * from "./functions/array.js";
+export * from "./functions/enums.js";
+export * from "./functions/map.js";
+export * from "./functions/math.js";
+export * from "./functions/object.js";
+export * from "./functions/random.js";
+export * from "./functions/set.js";
+export * from "./functions/sort.js";
+export * from "./functions/string.js";
+export * from "./functions/tuple.js";
+export * from "./functions/types.js";
+export * from "./functions/utils.js";
+export * from "./types/AddSubtract.js";
+export * from "./types/CompositionTypeSatisfiesEnum.js";
+export * from "./types/ERange.js";
+export * from "./types/Immutable.js";
+export * from "./types/IRange.js";
+export * from "./types/NaturalNumbersLessThan.js";
+export * from "./types/NaturalNumbersLessThanOrEqualTo.js";
+export * from "./types/ObjectValues.js";
+export * from "./types/ReadonlyMap.js";
+export * from "./types/ReadonlyRecord.js";
+export * from "./types/ReadonlySet.js";
+export * from "./types/Tuple.js";
+export * from "./types/WidenLiteral.js";
+export * from "./types/Writeable.js";

package/src/types/AddSubtract.ts

@@ -0,0 +1,19 @@
+/** From: https://gist.github.com/ryandabler/8b4ff4f36aed47bc09acc03174638468 */
+export type Add<A extends number, B extends number> = Length<
+  [...BuildTuple<A>, ...BuildTuple<B>]
+>;
+
+/** From: https://gist.github.com/ryandabler/8b4ff4f36aed47bc09acc03174638468 */
+export 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;

package/src/types/CompositionTypeSatisfiesEnum.ts

@@ -0,0 +1,67 @@
+/**
+ * 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`.
+ */
+export type CompositionTypeSatisfiesEnum<
+  T extends { type: unknown },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  Enum extends T["type"],
+> = unknown;
+
+// -----
+// Tests
+// -----
+
+enum ObjectiveType {
+  Foo = "Foo",
+  Bar = "Bar",
+  Baz = "Baz",
+}
+
+interface FooObjective {
+  type: ObjectiveType.Foo;
+  fooThing: number;
+}
+
+interface BarObjective {
+  type: ObjectiveType.Bar;
+  barThing: string;
+}
+
+interface BazObjective {
+  type: ObjectiveType.Baz;
+  bazThing: string;
+}
+
+type Objective1 = FooObjective | BarObjective | BazObjective;
+type _Test1 = CompositionTypeSatisfiesEnum<Objective1, ObjectiveType>;
+
+type Objective2 = FooObjective | BarObjective;
+// @ts-expect-error Missing "Baz".
+type _Test2 = CompositionTypeSatisfiesEnum<Objective2, ObjectiveType>;

package/src/types/ERange.ts

@@ -0,0 +1,15 @@
+import type { NaturalNumbersLessThan } from "./NaturalNumbersLessThan.js";
+
+/**
+ * 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
+ */
+export type ERange<Low extends number, High extends number> = Exclude<
+  NaturalNumbersLessThan<High>,
+  NaturalNumbersLessThan<Low>
+>;

package/src/types/IRange.ts

@@ -0,0 +1,16 @@
+import type { NaturalNumbersLessThan } from "./NaturalNumbersLessThan.js";
+import type { NaturalNumbersLessThanOrEqualTo } from "./NaturalNumbersLessThanOrEqualTo.js";
+
+/**
+ * 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
+ */
+export type IRange<Low extends number, High extends number> = Exclude<
+  NaturalNumbersLessThanOrEqualTo<High>,
+  NaturalNumbersLessThan<Low>
+>;

package/src/types/Immutable.ts

@@ -0,0 +1,28 @@
+/**
+ * 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
+ */
+export 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; // eslint-disable-line @typescript-eslint/no-unsafe-function-type
+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]> };

package/src/types/NaturalNumbersLessThan.ts

@@ -0,0 +1,12 @@
+/**
+ * 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
+ */
+export type NaturalNumbersLessThan<
+  N extends number,
+  Acc extends number[] = [],
+> = Acc["length"] extends N
+  ? Acc[number]
+  : NaturalNumbersLessThan<N, [...Acc, Acc["length"]]>;

package/src/types/NaturalNumbersLessThanOrEqualTo.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+export 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"]]>;

package/src/types/ObjectValues.ts

@@ -0,0 +1 @@
+export type ObjectValues<T> = T[keyof T];

package/src/types/ReadonlyMap.ts

@@ -0,0 +1,12 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+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. */
+export const ReadonlyMap = Map as ReadonlyMapConstructor;

package/src/types/ReadonlyRecord.ts

@@ -0,0 +1,3 @@
+export type ReadonlyRecord<K extends string | number | symbol, V> = Readonly<
+  Record<K, V>
+>;

package/src/types/ReadonlySet.ts

@@ -0,0 +1,9 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+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. */
+export const ReadonlySet = Set as ReadonlySetConstructor;

package/src/types/Tuple.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+export 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]>;

package/src/types/WidenLiteral.ts

@@ -0,0 +1,11 @@
+export type WidenLiteral<T> = T extends string
+  ? string
+  : T extends number
+    ? number
+    : T extends boolean
+      ? boolean
+      : T extends bigint
+        ? bigint
+        : T extends symbol
+          ? symbol
+          : T;

package/src/types/Writeable.ts

@@ -0,0 +1,6 @@
+/**
+ * Helper type to convert a read-only object into a writable object.
+ *
+ * This is the opposite of the built-in `Readonly` utility type.
+ */
+export type Writeable<T> = { -readonly [P in keyof T]: T[P] };