complete-common 1.0.0

package/dist/index.mjs

@@ -0,0 +1,463 @@
+const SECOND_IN_MILLISECONDS = 1e3;
+const MINUTE_IN_MILLISECONDS = 60 * SECOND_IN_MILLISECONDS;
+const HOUR_IN_MILLISECONDS = 60 * MINUTE_IN_MILLISECONDS;
+
+const ReadonlySet = Set;
+
+function getRandomInt(min, max, exceptions = []) {
+  min = Math.ceil(min);
+  max = Math.floor(max);
+  if (min > max) {
+    const oldMin = min;
+    const oldMax = max;
+    min = oldMax;
+    max = oldMin;
+  }
+  const exceptionsSet = new ReadonlySet(exceptions);
+  let randomInt;
+  do {
+    randomInt = Math.floor(Math.random() * (max - min + 1)) + min;
+  } while (exceptionsSet.has(randomInt));
+  return randomInt;
+}
+
+const FLOAT_REGEX = /^-?\d*\.?\d+$/;
+const INTEGER_REGEX = /^-?\d+$/;
+function assertDefined(value, ...[msg]) {
+  if (value === void 0) {
+    throw new TypeError(msg);
+  }
+}
+function assertNotNull(value, ...[msg]) {
+  if (value === null) {
+    throw new TypeError(msg);
+  }
+}
+function* eRange(start, end, increment = 1) {
+  if (end === void 0) {
+    yield* eRange(0, start, increment);
+    return;
+  }
+  for (let i = start; i < end; i += increment) {
+    yield i;
+  }
+}
+function* iRange(start, end, increment = 1) {
+  if (end === void 0) {
+    yield* iRange(0, start, increment);
+    return;
+  }
+  const exclusiveEnd = end + 1;
+  yield* eRange(start, exclusiveEnd, increment);
+}
+function isKeyOf(key, target) {
+  return key in target;
+}
+function noop() {
+}
+function parseFloatSafe(string) {
+  if (typeof string !== "string") {
+    return void 0;
+  }
+  const trimmedString = string.trim();
+  if (FLOAT_REGEX.exec(trimmedString) === null) {
+    return void 0;
+  }
+  const number = Number.parseFloat(trimmedString);
+  return Number.isNaN(number) ? void 0 : number;
+}
+function parseIntSafe(string) {
+  if (typeof string !== "string") {
+    return void 0;
+  }
+  const trimmedString = string.trim();
+  if (INTEGER_REGEX.exec(trimmedString) === null) {
+    return void 0;
+  }
+  const number = Number.parseInt(trimmedString, 10);
+  return Number.isNaN(number) ? void 0 : number;
+}
+function repeat(num, func) {
+  for (let i = 0; i < num; i++) {
+    func(i);
+  }
+}
+function todo(...args) {
+}
+
+function arrayCopyTwoDimensional(array) {
+  const copiedArray = [];
+  for (const subArray of array) {
+    copiedArray.push([...subArray]);
+  }
+  return copiedArray;
+}
+function arrayEquals(array1, array2) {
+  if (array1.length !== array2.length) {
+    return false;
+  }
+  return array1.every((array1Element, i) => {
+    const array2Element = array2[i];
+    return array1Element === array2Element;
+  });
+}
+function arrayRemove(originalArray, ...elementsToRemove) {
+  const elementsToRemoveSet = new ReadonlySet(elementsToRemove);
+  const array = [];
+  for (const element of originalArray) {
+    if (!elementsToRemoveSet.has(element)) {
+      array.push(element);
+    }
+  }
+  return array;
+}
+function arrayRemoveInPlace(array, ...elementsToRemove) {
+  const removedElements = [];
+  for (const element of elementsToRemove) {
+    const index = array.indexOf(element);
+    if (index > -1) {
+      const removedElement = array.splice(index, 1);
+      removedElements.push(...removedElement);
+    }
+  }
+  return removedElements;
+}
+function emptyArray(array) {
+  array.splice(0, array.length);
+}
+function filterMap(array, func) {
+  const filteredArray = [];
+  for (const element of array) {
+    const newElement = func(element);
+    if (newElement !== void 0) {
+      filteredArray.push(newElement);
+    }
+  }
+  return filteredArray;
+}
+function getRandomArrayElement(array, exceptions = []) {
+  if (array.length === 0) {
+    throw new Error(
+      "Failed to get a random array element since the provided array is empty."
+    );
+  }
+  const arrayToUse = exceptions.length > 0 ? arrayRemove(array, ...exceptions) : array;
+  const randomIndex = getRandomArrayIndex(arrayToUse);
+  const randomElement = arrayToUse[randomIndex];
+  assertDefined(
+    randomElement,
+    `Failed to get a random array element since the random index of ${randomIndex} was not valid.`
+  );
+  return randomElement;
+}
+function getRandomArrayIndex(array, exceptions = []) {
+  if (array.length === 0) {
+    throw new Error(
+      "Failed to get a random array index since the provided array is empty."
+    );
+  }
+  return getRandomInt(0, array.length - 1, exceptions);
+}
+function includes(array, searchElement) {
+  const widenedArray = array;
+  return widenedArray.includes(searchElement);
+}
+function isArray(arg) {
+  return Array.isArray(arg);
+}
+function newArray(length, value) {
+  return Array.from({ length }, () => value);
+}
+function sumArray(array) {
+  return array.reduce((accumulator, element) => accumulator + element, 0);
+}
+
+function getEnumEntries(transpiledEnum) {
+  const entries = Object.entries(transpiledEnum);
+  const numberEntries = entries.filter(
+    ([_key, value]) => typeof value === "number"
+  );
+  const entriesToReturn = numberEntries.length > 0 ? numberEntries : entries;
+  return entriesToReturn;
+}
+function getEnumKeys(transpiledEnum) {
+  const enumEntries = getEnumEntries(transpiledEnum);
+  return enumEntries.map(([key, _value]) => key);
+}
+function getEnumValues(transpiledEnum) {
+  const enumEntries = getEnumEntries(transpiledEnum);
+  return enumEntries.map(([_key, value]) => value);
+}
+function interfaceSatisfiesEnum() {
+}
+function isEnumValue(value, transpiledEnum, set) {
+  if (set !== void 0) {
+    return set.has(value);
+  }
+  const enumValues = getEnumValues(transpiledEnum);
+  return enumValues.includes(value);
+}
+
+function mapFilter(map, predicate) {
+  const array = [];
+  for (const value of map.values()) {
+    const match = predicate(value);
+    if (match) {
+      array.push(value);
+    }
+  }
+  return array;
+}
+function mapFind(map, predicate) {
+  for (const value of map.values()) {
+    const match = predicate(value);
+    if (match) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function objectToMap(object) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(object)) {
+    map.set(key, value);
+  }
+  return map;
+}
+function objectToReadonlyMap(object) {
+  return objectToMap(object);
+}
+
+function clamp(num, min, max) {
+  return Math.max(min, Math.min(num, max));
+}
+
+function objectFilter(object, predicate) {
+  const array = [];
+  for (const key in object) {
+    const value = object[key];
+    const match = predicate(value);
+    if (match) {
+      array.push(value);
+    }
+  }
+  return array;
+}
+
+function addSetsToSet(mainSet, ...setsToAdd) {
+  for (const set of setsToAdd) {
+    for (const value of set) {
+      mainSet.add(value);
+    }
+  }
+}
+function combineSets(...sets) {
+  const newSet = /* @__PURE__ */ new Set();
+  for (const set of sets) {
+    for (const value of set) {
+      newSet.add(value);
+    }
+  }
+  return newSet;
+}
+function copySet(oldSet) {
+  const newSet = /* @__PURE__ */ new Set();
+  for (const value of oldSet) {
+    newSet.add(value);
+  }
+  return newSet;
+}
+function objectKeysToReadonlySet(object) {
+  return objectKeysToSet(object);
+}
+function objectKeysToSet(object) {
+  const set = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(object)) {
+    set.add(key);
+  }
+  return set;
+}
+function objectValuesToReadonlySet(object) {
+  return objectValuesToSet(object);
+}
+function objectValuesToSet(object) {
+  const set = /* @__PURE__ */ new Set();
+  for (const key of Object.values(object)) {
+    set.add(key);
+  }
+  return set;
+}
+function setAdd(set, ...elements) {
+  for (const element of elements) {
+    set.add(element);
+  }
+}
+function setHas(set, ...elements) {
+  return elements.some((element) => set.has(element));
+}
+
+function sortCaseInsensitive(array) {
+  const newArray = [...array];
+  newArray.sort(
+    (a, b) => a.localeCompare(b, void 0, {
+      sensitivity: "base"
+    })
+  );
+  return newArray;
+}
+
+const DIACRITIC_REGEX = /\p{Diacritic}/u;
+const EMOJI_REGEX = /(\p{Extended_Pictographic}|\p{Emoji_Component})/u;
+const FIRST_LETTER_CAPITALIZED_REGEX = /^\p{Lu}/u;
+const KEBAB_CASE_REGEX = /^([a-z](?!\d)|\d(?![a-z]))+(-?([a-z](?!\d)|\d(?![a-z])))*$|^$/;
+const SEMANTIC_VERSION_REGEX = /^v*(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/;
+const WHITESPACE_REGEX = /\s/g;
+function capitalizeFirstLetter(string) {
+  if (string === "") {
+    return string;
+  }
+  const firstCharacter = string.charAt(0);
+  const capitalizedFirstLetter = firstCharacter.toUpperCase();
+  const restOfString = string.slice(1);
+  return `${capitalizedFirstLetter}${restOfString}`;
+}
+function escapeHTMLCharacters(string) {
+  return string.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#039;");
+}
+function getNumConsecutiveDiacritics(string) {
+  const normalizedString = string.normalize("NFD");
+  let numConsecutiveDiacritic = 0;
+  let maxConsecutiveDiacritic = 0;
+  for (const character of normalizedString) {
+    if (hasDiacritic(character)) {
+      numConsecutiveDiacritic++;
+      if (numConsecutiveDiacritic > maxConsecutiveDiacritic) {
+        maxConsecutiveDiacritic = numConsecutiveDiacritic;
+      }
+    } else {
+      numConsecutiveDiacritic = 0;
+    }
+  }
+  return maxConsecutiveDiacritic;
+}
+function hasDiacritic(string) {
+  const normalizedString = string.normalize("NFD");
+  return DIACRITIC_REGEX.test(normalizedString);
+}
+function hasEmoji(string) {
+  return EMOJI_REGEX.test(string);
+}
+function hasWhitespace(string) {
+  return WHITESPACE_REGEX.test(string);
+}
+function isFirstLetterCapitalized(string) {
+  return FIRST_LETTER_CAPITALIZED_REGEX.test(string);
+}
+function isKebabCase(string) {
+  return KEBAB_CASE_REGEX.test(string);
+}
+function isSemanticVersion(versionString) {
+  const match = versionString.match(SEMANTIC_VERSION_REGEX);
+  return match !== null;
+}
+function kebabCaseToCamelCase(string) {
+  return string.replaceAll(/-./g, (match) => {
+    const firstLetterOfWord = match[1];
+    return firstLetterOfWord === void 0 ? "" : firstLetterOfWord.toUpperCase();
+  });
+}
+function normalizeString(string) {
+  let sanitizedString = string;
+  sanitizedString = removeNonPrintableCharacters(sanitizedString);
+  sanitizedString = sanitizedString.replaceAll("\n\r", "\n");
+  sanitizedString = sanitizedString.replaceAll(/\p{Zl}/gu, "\n");
+  sanitizedString = sanitizedString.replaceAll(/\p{Zp}/gu, "\n");
+  sanitizedString = sanitizedString.replaceAll(/\p{Zs}/gu, " ");
+  sanitizedString = sanitizedString.trim();
+  return sanitizedString;
+}
+function parseSemanticVersion(versionString) {
+  const match = versionString.match(SEMANTIC_VERSION_REGEX);
+  if (match === null || match.groups === void 0) {
+    return void 0;
+  }
+  const { major, minor, patch } = match.groups;
+  if (major === void 0 || minor === void 0 || patch === void 0) {
+    return void 0;
+  }
+  const majorVersion = parseIntSafe(major);
+  const minorVersion = parseIntSafe(minor);
+  const patchVersion = parseIntSafe(patch);
+  if (majorVersion === void 0 || minorVersion === void 0 || patchVersion === void 0) {
+    return void 0;
+  }
+  return { majorVersion, minorVersion, patchVersion };
+}
+function removeLinesBetweenMarkers(string, marker) {
+  const lines = string.split("\n");
+  const newLines = [];
+  let skippingLines = false;
+  for (const line of lines) {
+    if (line.includes(`${marker}-start`)) {
+      skippingLines = true;
+      continue;
+    }
+    if (line.includes(`${marker}-end`)) {
+      skippingLines = false;
+      continue;
+    }
+    if (!skippingLines) {
+      newLines.push(line);
+    }
+  }
+  return newLines.join("\n");
+}
+function removeLinesMatching(string, match) {
+  const lines = string.split("\n");
+  const newLines = lines.filter((line) => !line.includes(match));
+  return newLines.join("\n");
+}
+function removeNonPrintableCharacters(string) {
+  return string.replaceAll(/\p{C}/gu, "");
+}
+function removeWhitespace(string) {
+  return string.replaceAll(WHITESPACE_REGEX, "");
+}
+function trimPrefix(string, prefix, trimAll = false) {
+  if (trimAll) {
+    const regExp = new RegExp(`^${prefix}+`, "g");
+    return string.replaceAll(regExp, "");
+  }
+  if (!string.startsWith(prefix)) {
+    return string;
+  }
+  return string.slice(prefix.length);
+}
+function trimSuffix(string, prefix) {
+  if (!string.endsWith(prefix)) {
+    return string;
+  }
+  const endCharacter = string.length - prefix.length;
+  return string.slice(0, endCharacter);
+}
+function truncateString(string, maxLength) {
+  if (string.length <= maxLength) {
+    return string;
+  }
+  return string.slice(0, maxLength);
+}
+
+function* tupleEntries(tuple) {
+  yield* tuple.entries();
+}
+function* tupleKeys(tuple) {
+  yield* tuple.keys();
+}
+
+function isObject(variable) {
+  return typeof variable === "object" && variable !== null && !Array.isArray(variable);
+}
+
+const ReadonlyMap = Map;
+
+export { HOUR_IN_MILLISECONDS, MINUTE_IN_MILLISECONDS, ReadonlyMap, ReadonlySet, SECOND_IN_MILLISECONDS, 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 };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "complete-common",
+  "version": "1.0.0",
+  "description": "Helper functions for TypeScript projects.",
+  "keywords": [],
+  "homepage": "https://complete-js.github.io/",
+  "bugs": {
+    "url": "https://github.com/complete-ts/complete/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/complete-ts/complete.git"
+  },
+  "license": "MIT",
+  "author": "Zamiell",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsx ./scripts/build.ts",
+    "lint": "tsx ./scripts/lint.ts",
+    "test": "glob \"./src/**/*.test.ts\" --cmd=\"node --import tsx --test --test-reporter spec\""
+  }
+}

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const SECOND_IN_MILLISECONDS = 1000;
+export const MINUTE_IN_MILLISECONDS = 60 * SECOND_IN_MILLISECONDS;
+export const HOUR_IN_MILLISECONDS = 60 * MINUTE_IN_MILLISECONDS;

package/src/functions/array.ts

@@ -0,0 +1,209 @@
+import type { WidenLiteral } from "../index.js";
+import { ReadonlySet } from "../types/ReadonlySet.js";
+import { getRandomInt } from "./random.js";
+import { assertDefined } from "./utils.js";
+
+/**
+ * Helper function to copy a two-dimensional array. Note that the sub-arrays will only be shallow
+ * copied (using the spread operator).
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function arrayCopyTwoDimensional<T>(
+  array: ReadonlyArray<readonly T[]>,
+): T[][] {
+  const copiedArray: T[][] = [];
+
+  for (const subArray of array) {
+    copiedArray.push([...subArray]);
+  }
+
+  return copiedArray;
+}
+
+/**
+ * Helper function for determining if two arrays contain the exact same elements. Note that this
+ * only performs a shallow comparison.
+ */
+export function arrayEquals<T>(
+  array1: readonly T[],
+  array2: readonly T[],
+): boolean {
+  if (array1.length !== array2.length) {
+    return false;
+  }
+
+  return array1.every((array1Element, i) => {
+    const array2Element = array2[i];
+    return array1Element === array2Element;
+  });
+}
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function arrayRemove<T>(
+  originalArray: readonly T[],
+  ...elementsToRemove: readonly T[]
+): T[] {
+  const elementsToRemoveSet = new ReadonlySet(elementsToRemove);
+
+  const array: T[] = [];
+  for (const element of originalArray) {
+    if (!elementsToRemoveSet.has(element)) {
+      array.push(element);
+    }
+  }
+
+  return array;
+}
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function arrayRemoveInPlace<T>(
+  // eslint-disable-next-line complete/prefer-readonly-parameter-types
+  array: T[],
+  ...elementsToRemove: readonly T[]
+): T[] {
+  const removedElements: T[] = [];
+
+  for (const element of elementsToRemove) {
+    const index = array.indexOf(element);
+    if (index > -1) {
+      const removedElement = array.splice(index, 1);
+      removedElements.push(...removedElement);
+    }
+  }
+
+  return removedElements;
+}
+
+/** Helper function to remove all of the elements in an array in-place. */
+// eslint-disable-next-line complete/prefer-readonly-parameter-types
+export function emptyArray<T>(array: T[]): void {
+  array.splice(0, array.length);
+}
+
+/**
+ * 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
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function filterMap<OldT, NewT>(
+  array: readonly OldT[],
+  func: (element: OldT) => NewT | undefined,
+): NewT[] {
+  const filteredArray: NewT[] = [];
+
+  for (const element of array) {
+    const newElement = func(element);
+    if (newElement !== undefined) {
+      filteredArray.push(newElement);
+    }
+  }
+
+  return filteredArray;
+}
+
+/**
+ * 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.
+ */
+export function getRandomArrayElement<T>(
+  array: readonly T[],
+  exceptions: readonly T[] = [],
+): T {
+  if (array.length === 0) {
+    throw new Error(
+      "Failed to get a random array element since the provided array is empty.",
+    );
+  }
+
+  const arrayToUse =
+    exceptions.length > 0 ? arrayRemove(array, ...exceptions) : array;
+  const randomIndex = getRandomArrayIndex(arrayToUse);
+  const randomElement = arrayToUse[randomIndex];
+  assertDefined(
+    randomElement,
+    `Failed to get a random array element since the random index of ${randomIndex} was not valid.`,
+  );
+
+  return randomElement;
+}
+
+/**
+ * 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.
+ */
+export function getRandomArrayIndex<T>(
+  array: readonly T[],
+  exceptions: readonly number[] = [],
+): number {
+  if (array.length === 0) {
+    throw new Error(
+      "Failed to get a random array index since the provided array is empty.",
+    );
+  }
+
+  return getRandomInt(0, array.length - 1, exceptions);
+}
+
+/**
+ * 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.
+ */
+export function includes<T, TupleElement extends WidenLiteral<T>>(
+  array: readonly TupleElement[],
+  searchElement: WidenLiteral<T>,
+): searchElement is TupleElement {
+  const widenedArray: ReadonlyArray<WidenLiteral<T>> = array;
+  return widenedArray.includes(searchElement);
+}
+
+/** A wrapper around `Array.isArray` that narrows to `unknown[]` instead of `any[]`. */
+export function isArray(arg: unknown): arg is unknown[] {
+  return Array.isArray(arg);
+}
+
+/** Initializes an array with all elements containing the specified default value. */
+// eslint-disable-next-line complete/no-mutable-return
+export function newArray<T>(length: number, value: T): T[] {
+  return Array.from({ length }, () => value);
+}
+
+/** Helper function to sum every value in an array together. */
+export function sumArray(array: readonly number[]): number {
+  return array.reduce((accumulator, element) => accumulator + element, 0);
+}