complete-common 1.0.0

package/src/functions/enums.ts

@@ -0,0 +1,105 @@
+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.
+ */
+export function getEnumEntries<T extends TranspiledEnum>(
+  transpiledEnum: T,
+): ReadonlyArray<[key: string, value: T[keyof T]]> {
+  const entries = Object.entries(transpiledEnum);
+  const numberEntries = entries.filter(
+    ([_key, value]) => typeof value === "number",
+  );
+
+  // If there are no number values, then this must be a string enum, and no filtration is required.
+  const entriesToReturn = numberEntries.length > 0 ? numberEntries : entries;
+  return entriesToReturn as never;
+}
+
+/**
+ * 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.
+ */
+export function getEnumKeys(transpiledEnum: TranspiledEnum): readonly string[] {
+  const enumEntries = getEnumEntries(transpiledEnum);
+  return enumEntries.map(([key, _value]) => key);
+}
+
+/**
+ * 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.
+ */
+export function getEnumValues<T extends TranspiledEnum>(
+  transpiledEnum: T,
+): ReadonlyArray<T[keyof T]> {
+  const enumEntries = getEnumEntries(transpiledEnum);
+  return enumEntries.map(([_key, value]) => value);
+}
+
+/**
+ * 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.
+ */
+export function interfaceSatisfiesEnum<
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-unnecessary-type-parameters
+  T extends Record<Enum, unknown>,
+  Enum extends string | number,
+>(): void {} // eslint-disable-line @typescript-eslint/no-empty-function
+
+/**
+ * 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.
+ */
+export function isEnumValue<T extends TranspiledEnum>(
+  value: number | string,
+  transpiledEnum: T,
+  set?: ReadonlySet<string | number>,
+): value is T[keyof T] {
+  if (set !== undefined) {
+    return set.has(value);
+  }
+
+  const enumValues = getEnumValues(transpiledEnum);
+  return enumValues.includes(value as T[keyof T]);
+}

package/src/functions/map.ts

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function mapFilter<K, V>(
+  map: ReadonlyMap<K, V>,
+  predicate: (value: V) => boolean,
+): V[] {
+  const array: V[] = [];
+
+  for (const value of map.values()) {
+    const match = predicate(value);
+    if (match) {
+      array.push(value);
+    }
+  }
+
+  return array;
+}
+
+/**
+ * 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.
+ */
+export function mapFind<K, V>(
+  map: ReadonlyMap<K, V>,
+  predicate: (value: V) => boolean,
+): V | undefined {
+  for (const value of map.values()) {
+    const match = predicate(value);
+    if (match) {
+      return value;
+    }
+  }
+
+  return 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.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function objectToMap<K extends string | number | symbol, V>(
+  object: Record<K, V>,
+): Map<K, V> {
+  const map = new Map<K, V>();
+
+  for (const [key, value] of Object.entries(object)) {
+    map.set(key as K, value as V);
+  }
+
+  return map;
+}
+
+/**
+ * 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.
+ */
+export function objectToReadonlyMap<K extends string | number | symbol, V>(
+  object: Record<K, V>,
+): ReadonlyMap<K, V> {
+  return objectToMap(object);
+}

package/src/functions/math.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`.
+ */
+export function clamp(num: number, min: number, max: number): number {
+  return Math.max(min, Math.min(num, max));
+}

package/src/functions/object.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+
+import type { ReadonlyRecord } from "../types/ReadonlyRecord.js";
+
+// eslint-disable-next-line complete/no-mutable-return
+export function objectFilter<K extends string | number | symbol, V>(
+  object: ReadonlyRecord<K, V>,
+  predicate: (value: V) => boolean,
+): V[] {
+  const array: V[] = [];
+
+  // eslint-disable-next-line complete/no-for-in
+  for (const key in object) {
+    const value = object[key];
+    const match = predicate(value);
+    if (match) {
+      array.push(value);
+    }
+  }
+
+  return array;
+}

package/src/functions/random.ts

@@ -0,0 +1,43 @@
+import { ReadonlySet } from "../types/ReadonlySet.js";
+
+/**
+ * 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.
+ */
+export function getRandomInt(
+  min: number,
+  max: number,
+  exceptions: readonly number[] = [],
+): number {
+  min = Math.ceil(min); // eslint-disable-line no-param-reassign
+  max = Math.floor(max); // eslint-disable-line no-param-reassign
+
+  if (min > max) {
+    const oldMin = min;
+    const oldMax = max;
+
+    min = oldMax; // eslint-disable-line no-param-reassign
+    max = oldMin; // eslint-disable-line no-param-reassign
+  }
+
+  const exceptionsSet = new ReadonlySet(exceptions);
+
+  let randomInt: number;
+  do {
+    randomInt = Math.floor(Math.random() * (max - min + 1)) + min;
+  } while (exceptionsSet.has(randomInt));
+
+  return randomInt;
+}

package/src/functions/set.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+export function addSetsToSet<T>(
+  // eslint-disable-next-line complete/prefer-readonly-parameter-types
+  mainSet: Set<T>,
+  ...setsToAdd: ReadonlyArray<ReadonlySet<T>>
+): void {
+  for (const set of setsToAdd) {
+    for (const value of set) {
+      mainSet.add(value);
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function combineSets<T>(...sets: ReadonlyArray<ReadonlySet<T>>): Set<T> {
+  const newSet = new Set<T>();
+  for (const set of sets) {
+    for (const value of set) {
+      newSet.add(value);
+    }
+  }
+
+  return newSet;
+}
+
+/** Helper function to copy a set. (You can also use a Set constructor to accomplish this task.) */
+// eslint-disable-next-line complete/no-mutable-return
+export function copySet<T>(oldSet: ReadonlySet<T>): Set<T> {
+  const newSet = new Set<T>();
+  for (const value of oldSet) {
+    newSet.add(value);
+  }
+
+  return newSet;
+}
+
+/**
+ * Helper function to convert the keys of an object to a read-only set.
+ *
+ * Also see the `objectKeysToSet` function.
+ */
+export function objectKeysToReadonlySet<K extends string | number | symbol, V>(
+  object: Record<K, V>,
+): ReadonlySet<K> {
+  return objectKeysToSet(object);
+}
+
+/**
+ * Helper function to convert the keys of an object to a set.
+ *
+ * Also see the `objectKeysToReadonlySet` function.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function objectKeysToSet<K extends string | number | symbol, V>(
+  object: Record<K, V>,
+): Set<K> {
+  const set = new Set<K>();
+
+  for (const key of Object.keys(object)) {
+    set.add(key as K);
+  }
+
+  return set;
+}
+
+/**
+ * Helper function to convert the values of an object to a read-only set.
+ *
+ * Also see the `objectValuesToSet` function.
+ */
+export function objectValuesToReadonlySet<
+  K extends string | number | symbol,
+  V,
+>(object: Record<K, V>): ReadonlySet<V> {
+  return objectValuesToSet(object);
+}
+
+/**
+ * Helper function to convert the values of an object to a set.
+ *
+ * Also see the `objectValuesToReadonlySet` function.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function objectValuesToSet<K extends string | number | symbol, V>(
+  object: Record<K, V>,
+): Set<V> {
+  const set = new Set<V>();
+
+  for (const key of Object.values(object)) {
+    set.add(key as V);
+  }
+
+  return set;
+}
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line complete/prefer-readonly-parameter-types
+export function setAdd<T>(set: Set<T>, ...elements: readonly T[]): void {
+  for (const element of elements) {
+    set.add(element);
+  }
+}
+
+/**
+ * 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.
+ */
+export function setHas<T>(
+  set: ReadonlySet<T>,
+  ...elements: readonly T[]
+): boolean {
+  return elements.some((element) => set.has(element));
+}

package/src/functions/sort.ts

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function sortCaseInsensitive(array: readonly string[]): string[] {
+  const newArray = [...array];
+  newArray.sort((a, b) =>
+    a.localeCompare(b, undefined, {
+      sensitivity: "base",
+    }),
+  );
+
+  return newArray;
+}

package/src/functions/string.test.ts

@@ -0,0 +1,42 @@
+import { equal } from "node:assert";
+import test, { describe } from "node:test";
+import { hasDiacritic, hasEmoji } from "./string.js";
+
+describe("hasEmoji", () => {
+  test("should return true for string with emoji", () => {
+    equal(hasEmoji("Hello 😃 World"), true);
+    equal(hasEmoji("This is a 🌟 test"), true);
+  });
+
+  test("should return false for string without emoji", () => {
+    equal(hasEmoji("Hello World"), false);
+    equal(hasEmoji("No emoji here!"), false);
+  });
+
+  test("should handle empty string", () => {
+    equal(hasEmoji(""), false);
+  });
+
+  test("should handle strings with only emoji", () => {
+    equal(hasEmoji("😊"), true);
+    equal(hasEmoji("🚀"), true);
+  });
+});
+
+describe("hasDiacritic", () => {
+  test("should return true for diacritic character", () => {
+    equal(hasDiacritic("á"), true);
+    equal(hasDiacritic("è"), true);
+    equal(hasDiacritic("ô"), true);
+  });
+
+  test("should return false for non-diacritic character", () => {
+    equal(hasDiacritic("A"), false);
+    equal(hasDiacritic("1"), false);
+    equal(hasDiacritic("!"), false);
+  });
+
+  test("should handle empty string", () => {
+    equal(hasDiacritic(""), false);
+  });
+});