complete-common 1.0.0 → 1.1.0

package/src/functions/string.ts

@@ -1,3 +1,9 @@
+/**
+ * Helper functions that have to do with strings.
+ *
+ * @module
+ */
+
 import { parseIntSafe } from "./utils.js";
 
 // When regular expressions are located at the root instead of inside the function, the functions
@@ -17,6 +23,7 @@ const KEBAB_CASE_REGEX =
 const SEMANTIC_VERSION_REGEX = /^v*(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/;
 const WHITESPACE_REGEX = /\s/g;
 
+/** Helper function to capitalize the first letter of a string. */
 export function capitalizeFirstLetter(string: string): string {
   if (string === "") {
     return string;
@@ -43,6 +50,12 @@ export function escapeHTMLCharacters(string: string): string {
     .replaceAll("'", "&#039;");
 }
 
+/**
+ * Helper function to get the number of consecutive diacritics in a string.
+ *
+ * This is useful for sanitization purposes, since many subsequent diacritics can be a sign of a
+ * malicious string.
+ */
 export function getNumConsecutiveDiacritics(string: string): number {
   // First, normalize with Normalization Form Canonical Decomposition (NFD) so that diacritics are
   // separated from other characters:
@@ -66,6 +79,7 @@ export function getNumConsecutiveDiacritics(string: string): number {
   return maxConsecutiveDiacritic;
 }
 
+/** Helper function to check if a string has one or more diacritics in it. */
 export function hasDiacritic(string: string): boolean {
   // First, normalize with Normalization Form Canonical Decomposition (NFD) so that diacritics are
   // separated from other characters:
@@ -75,6 +89,11 @@ export function hasDiacritic(string: string): boolean {
   return DIACRITIC_REGEX.test(normalizedString);
 }
 
+/**
+ * Helper function to check if a string has one or more emoji in it.
+ *
+ * Under the hood, this uses the same regex check as the Zod library.
+ */
 export function hasEmoji(string: string): boolean {
   return EMOJI_REGEX.test(string);
 }
@@ -107,6 +126,7 @@ export function isSemanticVersion(versionString: string): boolean {
   return match !== null;
 }
 
+/** Helper function to convert a string from kebab-case to camel-case. */
 export function kebabCaseToCamelCase(string: string): string {
   return string.replaceAll(/-./g, (match) => {
     const firstLetterOfWord = match[1];
@@ -154,8 +174,13 @@ export function normalizeString(string: string): string {
  */
 export function parseSemanticVersion(versionString: string):
   | {
+      /** The first number inside of the semantic version. */
       majorVersion: number;
+
+      /** The second number inside of the semantic version. */
       minorVersion: number;
+
+      /** The third number inside of the semantic version. */
       patchVersion: number;
     }
   | undefined {

package/src/functions/time.ts

@@ -0,0 +1,26 @@
+/**
+ * Helper functions having to do with time.
+ *
+ * @module
+ */
+
+/**
+ * Helper function to get the number of elapsed seconds since a starting time.
+ *
+ * This function always returns a whole number (using `Math.floor` on the result).
+ *
+ * For example:
+ *
+ * ```ts
+ * const startTime = Date.now();
+ * doSomething();
+ * const elapsedSeconds = getElapsedSeconds(startTime);
+ * ```
+ */
+export function getElapsedSeconds(startTime: number): number {
+  const endTime = Date.now();
+  const elapsedMilliseconds = endTime - startTime;
+  const elapsedSeconds = elapsedMilliseconds / 1000;
+
+  return Math.floor(elapsedSeconds);
+}

package/src/functions/tuple.ts

@@ -1,3 +1,9 @@
+/**
+ * Helper functions that have to do with TypeScript tuples.
+ *
+ * @module
+ */
+
 import type { Tuple } from "../types/Tuple.js";
 
 type TupleKey<T extends readonly unknown[]> = {

package/src/functions/types.ts

@@ -1,3 +1,9 @@
+/**
+ * Identity functions that help with narrowing.
+ *
+ * @module
+ */
+
 /**
  * Helper function to narrow an unknown value to an object (i.e. a TypeScript record).
  *

package/src/functions/utils.test.ts

@@ -1,13 +1,7 @@
 import { deepStrictEqual, strictEqual } from "node:assert";
 import test, { describe } from "node:test";
-import {
-  assertDefined,
-  assertNotNull,
-  eRange,
-  iRange,
-  parseFloatSafe,
-  parseIntSafe,
-} from "./utils.js";
+import { assertDefined, assertNotNull } from "./assert.js";
+import { eRange, iRange, parseFloatSafe, parseIntSafe } from "./utils.js";
 
 describe("assertsDefined", () => {
   /** We use a value of null since it is the least arbitrary non-undefined value. */

package/src/functions/utils.ts

@@ -1,45 +1,15 @@
+/**
+ * Helper functions that do not belong to any category in particular.
+ *
+ * @module
+ */
+
 // 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,
@@ -102,7 +72,7 @@ export function* eRange(
  * If you want an array instead of an iterator, use the spread operator like this:
  *
  * ```ts
- * const myArray = [...eRange(1, 3)];
+ * const myArray = [...iRange(1, 3)];
  * ```
  *
  * @param start The integer to start at.

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./constants.js";
 export * from "./functions/array.js";
+export * from "./functions/assert.js";
 export * from "./functions/enums.js";
 export * from "./functions/map.js";
 export * from "./functions/math.js";
@@ -8,20 +9,21 @@ export * from "./functions/random.js";
 export * from "./functions/set.js";
 export * from "./functions/sort.js";
 export * from "./functions/string.js";
+export * from "./functions/time.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 type * from "./types/AddSubtract.js";
+export type * from "./types/CompositionTypeSatisfiesEnum.js";
+export type * from "./types/ERange.js";
+export type * from "./types/Immutable.js";
+export type * from "./types/IRange.js";
+export type * from "./types/NaturalNumbersLessThan.js";
+export type * from "./types/NaturalNumbersLessThanOrEqualTo.js";
+export type * from "./types/ObjectValues.js";
 export * from "./types/ReadonlyMap.js";
-export * from "./types/ReadonlyRecord.js";
+export type * from "./types/ReadonlyRecord.js";
 export * from "./types/ReadonlySet.js";
-export * from "./types/Tuple.js";
-export * from "./types/WidenLiteral.js";
-export * from "./types/Writeable.js";
+export type * from "./types/Tuple.js";
+export type * from "./types/WidenLiteral.js";
+export type * from "./types/Writeable.js";

package/src/types/AddSubtract.ts

@@ -1,9 +1,17 @@
-/** From: https://gist.github.com/ryandabler/8b4ff4f36aed47bc09acc03174638468 */
+/**
+ * Helper type to add two other types.
+ *
+ * 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 */
+/**
+ * Helper type to subtract two other types.
+ *
+ * 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>

package/src/types/CompositionTypeSatisfiesEnum.ts

@@ -29,9 +29,11 @@
  * entry for `BazObjective`.
  */
 export type CompositionTypeSatisfiesEnum<
-  T extends { type: unknown },
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  Enum extends T["type"],
+  T extends {
+    /** The type of the discriminated union. */
+    type: unknown;
+  },
+  _Enum extends T["type"],
 > = unknown;
 
 // -----

package/src/types/ObjectValues.ts

@@ -1 +1,2 @@
+/** Helper type to capture just the values of an object/record. */
 export type ObjectValues<T> = T[keyof T];

package/src/types/ReadonlyRecord.ts

@@ -1,3 +1,8 @@
+/**
+ * Helper type to specify that a record should be read-only.
+ *
+ * This is the same thing as `Readonly<Record<K, V>>`.
+ */
 export type ReadonlyRecord<K extends string | number | symbol, V> = Readonly<
   Record<K, V>
 >;

package/src/types/Tuple.ts

@@ -9,6 +9,7 @@ export type Tuple<T, N extends number> = N 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

@@ -1,3 +1,4 @@
+/** Helper type used to widen a const array to the corresponding base type. */
 export type WidenLiteral<T> = T extends string
   ? string
   : T extends number