complete-common 1.0.0 → 1.1.0

package/dist/types/NaturalNumbersLessThanOrEqualTo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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"]]>;
+//# sourceMappingURL=NaturalNumbersLessThanOrEqualTo.d.ts.map

package/dist/types/NaturalNumbersLessThanOrEqualTo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NaturalNumbersLessThanOrEqualTo.d.ts","sourceRoot":"","sources":["../../src/types/NaturalNumbersLessThanOrEqualTo.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,CACzC,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,IACrB,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,GAClC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GACtB,CAAC,CAAC,MAAM,CAAC,GACT,+BAA+B,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GACzD,+BAA+B,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/ObjectValues.d.cts

@@ -0,0 +1,3 @@
+/** Helper type to capture just the values of an object/record. */
+export type ObjectValues<T> = T[keyof T];
+//# sourceMappingURL=ObjectValues.d.ts.map

package/dist/types/ObjectValues.d.mts

@@ -0,0 +1,3 @@
+/** Helper type to capture just the values of an object/record. */
+export type ObjectValues<T> = T[keyof T];
+//# sourceMappingURL=ObjectValues.d.ts.map

package/dist/types/ObjectValues.d.ts

@@ -0,0 +1,3 @@
+/** Helper type to capture just the values of an object/record. */
+export type ObjectValues<T> = T[keyof T];
+//# sourceMappingURL=ObjectValues.d.ts.map

package/dist/types/ObjectValues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectValues.d.ts","sourceRoot":"","sources":["../../src/types/ObjectValues.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC"}

package/dist/types/ReadonlyMap.d.cts

@@ -0,0 +1,9 @@
+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 declare const ReadonlyMap: ReadonlyMapConstructor;
+export {};
+//# sourceMappingURL=ReadonlyMap.d.ts.map

package/dist/types/ReadonlyMap.d.mts

@@ -0,0 +1,9 @@
+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 declare const ReadonlyMap: ReadonlyMapConstructor;
+export {};
+//# sourceMappingURL=ReadonlyMap.d.ts.map

package/dist/types/ReadonlyMap.d.ts

@@ -0,0 +1,9 @@
+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 declare const ReadonlyMap: ReadonlyMapConstructor;
+export {};
+//# sourceMappingURL=ReadonlyMap.d.ts.map

package/dist/types/ReadonlyMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadonlyMap.d.ts","sourceRoot":"","sources":["../../src/types/ReadonlyMap.ts"],"names":[],"mappings":"AAEA,UAAU,sBAAsB;IAC9B,QAAQ,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,GAC1E,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;CAC3C;AAED,uEAAuE;AACvE,eAAO,MAAM,WAAW,EAAU,sBAAsB,CAAC"}

package/dist/types/ReadonlyRecord.d.cts

@@ -0,0 +1,7 @@
+/**
+ * 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>>;
+//# sourceMappingURL=ReadonlyRecord.d.ts.map

package/dist/types/ReadonlyRecord.d.mts

@@ -0,0 +1,7 @@
+/**
+ * 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>>;
+//# sourceMappingURL=ReadonlyRecord.d.ts.map

package/dist/types/ReadonlyRecord.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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>>;
+//# sourceMappingURL=ReadonlyRecord.d.ts.map

package/dist/types/ReadonlyRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadonlyRecord.d.ts","sourceRoot":"","sources":["../../src/types/ReadonlyRecord.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,QAAQ,CAC1E,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CACb,CAAC"}

package/dist/types/ReadonlySet.d.cts

@@ -0,0 +1,8 @@
+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 declare const ReadonlySet: ReadonlySetConstructor;
+export {};
+//# sourceMappingURL=ReadonlySet.d.ts.map

package/dist/types/ReadonlySet.d.mts

@@ -0,0 +1,8 @@
+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 declare const ReadonlySet: ReadonlySetConstructor;
+export {};
+//# sourceMappingURL=ReadonlySet.d.ts.map

package/dist/types/ReadonlySet.d.ts

@@ -0,0 +1,8 @@
+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 declare const ReadonlySet: ReadonlySetConstructor;
+export {};
+//# sourceMappingURL=ReadonlySet.d.ts.map

package/dist/types/ReadonlySet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadonlySet.d.ts","sourceRoot":"","sources":["../../src/types/ReadonlySet.ts"],"names":[],"mappings":"AAEA,UAAU,sBAAsB;IAC9B,KAAK,CAAC,GAAG,GAAG,EAAE,MAAM,CAAC,EAAE,SAAS,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;CACtC;AAED,uEAAuE;AACvE,eAAO,MAAM,WAAW,EAAU,sBAAsB,CAAC"}

package/dist/types/Tuple.d.cts

@@ -0,0 +1,10 @@
+/**
+ * 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]>;
+export {};
+//# sourceMappingURL=Tuple.d.ts.map

package/dist/types/Tuple.d.mts

@@ -0,0 +1,10 @@
+/**
+ * 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]>;
+export {};
+//# sourceMappingURL=Tuple.d.ts.map

package/dist/types/Tuple.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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]>;
+export {};
+//# sourceMappingURL=Tuple.d.ts.map

package/dist/types/Tuple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tuple.d.ts","sourceRoot":"","sources":["../../src/types/Tuple.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,CAAC,GAChD,MAAM,SAAS,CAAC,GACd,CAAC,EAAE,GACH,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GACpB,KAAK,CAAC;AAEV,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,GAC3E,CAAC,GACD,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/WidenLiteral.d.cts

@@ -0,0 +1,3 @@
+/** Helper type used to widen a const array to the corresponding base type. */
+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;
+//# sourceMappingURL=WidenLiteral.d.ts.map

package/dist/types/WidenLiteral.d.mts

@@ -0,0 +1,3 @@
+/** Helper type used to widen a const array to the corresponding base type. */
+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;
+//# sourceMappingURL=WidenLiteral.d.ts.map

package/dist/types/WidenLiteral.d.ts

@@ -0,0 +1,3 @@
+/** Helper type used to widen a const array to the corresponding base type. */
+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;
+//# sourceMappingURL=WidenLiteral.d.ts.map

package/dist/types/WidenLiteral.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidenLiteral.d.ts","sourceRoot":"","sources":["../../src/types/WidenLiteral.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC1C,MAAM,GACN,CAAC,SAAS,MAAM,GACd,MAAM,GACN,CAAC,SAAS,OAAO,GACf,OAAO,GACP,CAAC,SAAS,MAAM,GACd,MAAM,GACN,CAAC,SAAS,MAAM,GACd,MAAM,GACN,CAAC,CAAC"}

package/dist/types/Writeable.d.cts

@@ -0,0 +1,9 @@
+/**
+ * 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];
+};
+//# sourceMappingURL=Writeable.d.ts.map

package/dist/types/Writeable.d.mts

@@ -0,0 +1,9 @@
+/**
+ * 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];
+};
+//# sourceMappingURL=Writeable.d.ts.map

package/dist/types/Writeable.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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];
+};
+//# sourceMappingURL=Writeable.d.ts.map

package/dist/types/Writeable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Writeable.d.ts","sourceRoot":"","sources":["../../src/types/Writeable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "complete-common",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Helper functions for TypeScript projects.",
   "keywords": [],
-  "homepage": "https://complete-js.github.io/",
+  "homepage": "https://complete-ts.github.io/",
   "bugs": {
     "url": "https://github.com/complete-ts/complete/issues"
   },
@@ -30,7 +30,18 @@
   ],
   "scripts": {
     "build": "tsx ./scripts/build.ts",
+    "docs": "typedoc",
     "lint": "tsx ./scripts/lint.ts",
     "test": "glob \"./src/**/*.test.ts\" --cmd=\"node --import tsx --test --test-reporter spec\""
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "complete-node": "^1.7.4",
+    "eslint-plugin-sort-exports": "^0.9.1",
+    "execa": "^9.5.2",
+    "glob": "^11.0.1",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.1",
+    "unbuild": "^3.3.1"
   }
 }

package/src/constants.ts

@@ -1,3 +1,8 @@
+/** Equal to 1000. */
 export const SECOND_IN_MILLISECONDS = 1000;
+
+/** Equal to 60,000. */
 export const MINUTE_IN_MILLISECONDS = 60 * SECOND_IN_MILLISECONDS;
+
+/** Equal to 3,600,000. */
 export const HOUR_IN_MILLISECONDS = 60 * MINUTE_IN_MILLISECONDS;

package/src/functions/array.ts

@@ -1,7 +1,13 @@
+/**
+ * Helper functions that have to do with arrays.
+ *
+ * @module
+ */
+
 import type { WidenLiteral } from "../index.js";
 import { ReadonlySet } from "../types/ReadonlySet.js";
+import { assertDefined } from "./assert.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
@@ -84,7 +90,7 @@ export function arrayRemoveInPlace<T>(
 
   for (const element of elementsToRemove) {
     const index = array.indexOf(element);
-    if (index > -1) {
+    if (index !== -1) {
       const removedElement = array.splice(index, 1);
       removedElements.push(...removedElement);
     }

package/src/functions/assert.ts

@@ -0,0 +1,86 @@
+/**
+ * Helper functions that have to do with asserting.
+ *
+ * @module
+ */
+
+import { isObject } from "./types.js";
+
+const TYPES_TO_VALIDATION_FUNCTIONS = {
+  string: (val: unknown): val is string => typeof val === "string",
+  number: (val: unknown): val is number => typeof val === "number",
+  boolean: (val: unknown): val is boolean => typeof val === "boolean",
+  object: (val: unknown): val is object =>
+    val !== null && typeof val === "object",
+  array: (val: unknown): val is unknown[] => Array.isArray(val),
+  null: (val: unknown): val is null => val === null,
+  undefined: (val: unknown): val is undefined => val === undefined,
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  function: (val: unknown): val is Function => typeof val === "function",
+} as const;
+
+/**
+ * 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 throw an error if the provided value is not an object (i.e. a TypeScript
+ * record).
+ *
+ * This is useful to have TypeScript narrow a `Record<string, unknown> | undefined` value to
+ * `Record<string, unknown>` in a concise way.
+ *
+ * Under the hood, this function uses the `isObject` helper function.
+ */
+export function assertObject(
+  value: unknown,
+  msg: string,
+): asserts value is Record<string, unknown> {
+  if (!isObject(value)) {
+    throw new TypeError(msg);
+  }
+}
+
+/** Helper function to throw an error if the provided value is not of the provided type. */
+export function assertType(
+  value: unknown,
+  type: keyof typeof TYPES_TO_VALIDATION_FUNCTIONS,
+  msg: string,
+): asserts value is unknown {
+  const validationFunction = TYPES_TO_VALIDATION_FUNCTIONS[type];
+  if (!validationFunction(value)) {
+    throw new TypeError(msg);
+  }
+}

package/src/functions/enums.ts

@@ -1,3 +1,9 @@
+/**
+ * Helper functions that have to do with TypeScript enums.
+ *
+ * @module
+ */
+
 type TranspiledEnum = Record<string, string | number>;
 
 /**

package/src/functions/map.ts

@@ -1,3 +1,10 @@
+/**
+ * Helper functions that have to do with
+ * [maps](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map).
+ *
+ * @module
+ */
+
 /**
  * Helper function to get the values in a `Map` that match an arbitrary condition. Similar to the
  * `Array.map` method, but works for maps.
@@ -43,48 +50,3 @@ export function mapFind<K, V>(
 
   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

@@ -1,3 +1,9 @@
+/**
+ * Helper functions that have to do with math.
+ *
+ * @module
+ */
+
 /**
  * Helper function to normalize a number, ensuring that it is within a certain range.
  *

package/src/functions/object.ts

@@ -1,12 +1,17 @@
 /**
- * Helper function to get the values in an object that match an arbitrary condition. Similar to the
- * `Array.map` method, but works for objects.
+ * Helper functions that have to do with objects.
  *
- * This is efficient such that it avoids converting the object values into an array.
+ * @module
  */
 
 import type { ReadonlyRecord } from "../types/ReadonlyRecord.js";
 
+/**
+ * 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.
+ */
 // eslint-disable-next-line complete/no-mutable-return
 export function objectFilter<K extends string | number | symbol, V>(
   object: ReadonlyRecord<K, V>,
@@ -25,3 +30,85 @@ export function objectFilter<K extends string | number | symbol, V>(
 
   return array;
 }
+
+/**
+ * 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 converted map will only have string keys, due to the nature of JavaScript objects
+ * only having string keys 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 converted map will only have string keys, due to the nature of JavaScript objects
+ * only having string keys 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);
+}
+
+/**
+ * Helper function to convert an object to a reverse map.
+ *
+ * Note that the converted map will only have string keys, due to the nature of JavaScript objects
+ * only having string keys under the hood.
+ *
+ * Also see the `objectToReverseReadonlyMap` function.
+ */
+// eslint-disable-next-line complete/no-mutable-return
+export function objectToReverseMap<
+  K extends string | number | symbol,
+  V extends string | number | symbol,
+>(object: Record<K, V>): Map<V, K> {
+  const map = new Map<V, K>();
+
+  for (const [key, value] of Object.entries(object)) {
+    map.set(value as V, key as K);
+  }
+
+  return map;
+}
+
+/**
+ * Helper function to convert an object to a reverse read-only map.
+ *
+ * Note that the converted map will only have string keys, due to the nature of JavaScript objects
+ * only having string keys under the hood.
+ *
+ * Also see the `objectToReverseMap` function.
+ */
+export function objectToReverseReadonlyMap<
+  K extends string | number | symbol,
+  V extends string | number | symbol,
+>(object: Record<K, V>): ReadonlyMap<V, K> {
+  return objectToReverseMap(object);
+}

package/src/functions/random.ts

@@ -1,3 +1,9 @@
+/**
+ * Helper functions that have to do with getting random values.
+ *
+ * @module
+ */
+
 import { ReadonlySet } from "../types/ReadonlySet.js";
 
 /**

package/src/functions/set.ts

@@ -1,3 +1,10 @@
+/**
+ * Helper functions that have to do with
+ * [sets](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+ *
+ * @module
+ */
+
 /**
  * Helper function to add all of the values in one set to another set. The first set passed will be
  * modified in place.

package/src/functions/sort.ts

@@ -1,3 +1,9 @@
+/**
+ * Helper functions that have to do with sorting.
+ *
+ * @module
+ */
+
 /**
  * Helper function to perform a case insensitive sort. This will copy the provided array and return
  * the sorted copy.