assertie 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.3.1](https://github.com/OfficialHalfwayDead/assertie/compare/v0.3.0...v0.3.1) (2025-02-23)
+
+* [`0d59837`](https://github.com/OfficialHalfwayDead/assertie/commit/0d59837841707c963ce174e79a527fcb1379ac4f) Add array and tuple assertions to the README.
+
+
+## [0.3.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.2.0...v0.3.0) (2025-02-23)
+
+### Breaking Changes
+
+* [`9906290`](https://github.com/OfficialHalfwayDead/assertie/commit/990629053a10e519c4d73ece8825f8edf7003489) assertie >= 0.3.0 requires TypeScript 4.7.0 or higher in your project.
+* [`b8ca296`](https://github.com/OfficialHalfwayDead/assertie/commit/b8ca296cb80c8e46db49af8256ea8bc1f76532e4) `assertPropsNonNullable` now only accepts objects as the first argument. This is technically a breaking change because TypeScript would have previously allowed passing anything to it, but it never made sense.
+
+### Features
+
+* [`7188088`](https://github.com/OfficialHalfwayDead/assertie/commit/71880883ecc0ecc110a6074b955dc2fc5fe806a5) More accurate print of the actual type of items when an assertion fails and significantly improved error messages overall.
+* [`7188088`](https://github.com/OfficialHalfwayDead/assertie/commit/71880883ecc0ecc110a6074b955dc2fc5fe806a5) Add type and non-null assertions for arrays that check all elements in one call and provide better typing and error messages: `assertArrayType`, `assertArrayNonNullable`.
+* [`9906290`](https://github.com/OfficialHalfwayDead/assertie/commit/990629053a10e519c4d73ece8825f8edf7003489) Add assertions for tuples that can narrow types of arrays or tuples with unknown types: `assertIsTuple`, `assertTupleTypes`, `assertTupleNonNullable`.
+
+### Other
+
+* [`075fecd`](https://github.com/OfficialHalfwayDead/assertie/commit/075fecd105030191eac671d8731765f4f5af2cd4) Add JSDoc comments to all functions and improve documentation overall.
+
+
 ## [0.2.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.1.0...v0.2.0) (2025-02-17)
 
 ### Breaking Changes

package/MIGRATION-GUIDE.md

@@ -0,0 +1,12 @@
+# Migration Guide
+
+Scroll down to your previous version and then follow all the steps upwards in order until the version you're targeting.
+
+## [0.2.x to 0.3.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.2.0...v0.3.0)
+
+* New features mean assertie >= 0.3.0 requires TypeScript 4.7.0 or higher in your project. (Previous minimum version was 3.7.0)
+* Ensure that you aren't passing things that aren't objects to `assertPropsNonNullable`. It never made sense, but the TS type previously allowed it.
+
+## [0.1.x to 0.2.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.1.0...v0.2.0)
+
+* All functions which had `Typeof` in the name changed capitalization to `TypeOf` for consistency. Change all existing calls to the new spelling.

package/README.md

@@ -154,6 +154,28 @@ const safeObj = obj;
 
 The reason an array is needed here is because undefined properties may not be present in `Object.keys`, so the caller needs to provide all keys to check. Don't worry about the safety, though. If you forget to pass a key, its type will remain nullable after the assert and TypeScript will not consider it safe to access.
 
+### Arrays and tuples
+
+Arrays and tuples have equivalent versions of `assertType` and `assertNonNullable`. These make it easy to check every element at once and get great errors and type narrowing.
+
+```ts
+const arr: (number | string | null)[] = [1, 2, 3];
+assertArrayNonNullable(arr); // narrows to (number | string)[]
+assertArrayType(arr, "number"); // narrows to number[]
+```
+
+```ts
+const arr: number[] = [1, 2, 3];
+assertIsTuple(arr, 3); // narrows to [number, number, number]
+
+const arrMixed: (number | string | null)[] = [1, "a"];
+assertIsTuple(arrMixed, 2); // narrows to [T, T]
+// where T = number | string | null;
+assertTupleNonNullable(arrMixed); // narrows T to number | string
+assertTupleTypes(arrMixed, ["number", "string"]);
+const tup: [number, string] = arrMixed;
+```
+
 ### Asserting unreachable code
 
 The unreachable assertion will
@@ -186,4 +208,12 @@ assertFiniteNumber(123);
 // DO NOT USE FOR INPUT VALIDATION OF USER PROVIDED VALUES!
 ```
 
-Useful for string-to-number conversions when you expect **valid** number strings. Prevents accidental usage of strings or invalid numbers due to JS's loose equality (`123 == "123"`).
+Can prevent `NaN` propagation and accidental infinities in calculations. Also useful for string-to-number conversions when you expect **valid** number strings:
+
+```ts
+const str = "CustomObject123";
+const numStr = str.substring(11); // oops "t123"
+const num = Number(numStr); // NaN
+assertFiniteNumber(num); // throws
+arr[num] = "yup" // disaster averted
+```

package/lib/index.d.ts

@@ -1,5 +1,5 @@
-type PrimitiveTypeStrings = "string" | "number" | "boolean" | "bigint" | "undefined" | "function" | "object" | "symbol";
-type PrimitiveTypes = {
+declare type Tuple<T, N extends number, A extends unknown[] = []> = A["length"] extends N ? A : Tuple<T, N, [...A, T]>;
+declare type PrimitiveTypes = {
     "string": string;
     "number": number;
     "boolean": boolean;
@@ -9,29 +9,154 @@ type PrimitiveTypes = {
     "object": object;
     "symbol": symbol;
 };
-type NullableKeys<T> = {
+declare type PrimitiveTypeStrings = keyof PrimitiveTypes;
+declare type NullableKeys<T> = {
     [K in keyof T]-?: undefined extends T[K] ? K : null extends T[K] ? K : never;
 }[keyof T];
-type PropsNonNullable<T, N extends NullableKeys<T>> = T & {
+declare type PropsNonNullable<T, N extends NullableKeys<T>> = T & {
     [K in N]-?: NonNullable<T[K]>;
 };
-type Constructor<T> = new (...args: unknown[]) => T;
-type AllJSTypes = PrimitiveTypeStrings | null | undefined | Constructor<unknown>;
-type ResolveAnyJSType<T extends AllJSTypes> = T extends PrimitiveTypeStrings ? PrimitiveTypes[T] : T extends null ? null : T extends undefined ? undefined : T extends Constructor<infer U> ? U : never;
+declare type Constructor<T> = new (...args: unknown[]) => T;
+declare type AllJSTypes = PrimitiveTypeStrings | null | undefined | Constructor<unknown>;
+declare type ResolveAnyJSType<T extends AllJSTypes> = T extends PrimitiveTypeStrings ? PrimitiveTypes[T] : T extends null ? null : T extends undefined ? undefined : T extends Constructor<infer U> ? U : never;
+/**
+ * Asserts that the provided boolean is true.
+ * @param {boolean} hasToBeTrue - The boolean to assert.
+ * @param {string} msg - The message of the Error if the assertion fails.
+ * @throws {AssertionError} if the assertion fails.
+ */
 export declare function assert(hasToBeTrue: boolean, msg?: string): asserts hasToBeTrue is true;
-export declare function assertType<T extends AllJSTypes>(obj: unknown, expectedType: T): asserts obj is ResolveAnyJSType<T>;
-export declare function assertTypeOfString(obj: unknown): asserts obj is string;
-export declare function assertTypeOfNumber(obj: unknown): asserts obj is number;
-export declare function assertTypeOfBoolean(obj: unknown): asserts obj is boolean;
-export declare function assertTypeOfBigint(obj: unknown): asserts obj is bigint;
-export declare function assertTypeOfUndefined(obj: unknown): asserts obj is undefined;
-export declare function assertTypeOfFunction(obj: unknown): asserts obj is Function;
-export declare function assertTypeOfObject(obj: unknown): asserts obj is object;
-export declare function assertTypeOfSymbol(obj: unknown): asserts obj is symbol;
-export declare function assertNull(obj: unknown): asserts obj is null;
-export declare function assertInstanceOf<T>(obj: unknown, constructable: Constructor<T>): asserts obj is T;
-export declare function assertUnreachable(obj: never, msg?: string): asserts obj is never;
-export declare function assertPropsNonNullable<T, N extends NullableKeys<T>>(obj: T, props: N[]): asserts obj is PropsNonNullable<T, N>;
-export declare function assertNonNullable<T>(obj: T): asserts obj is NonNullable<T>;
-export declare function assertFiniteNumber(obj: unknown): asserts obj is number;
+/**
+ * Asserts that the provided object is of the expectedType.
+ * @param {unknown} item - The object which ought to be of the expectedType.
+ * @param {AllJSTypes} expectedType - The expected type of the object. JS primitive types, null, undefined, and constructable types are supported. JS primitive types are passed as the string they return from typeof, e.g., "number".
+ * @throws {AssertionError} if the type isn't as expected.
+ */
+export declare function assertType<T extends AllJSTypes>(item: unknown, expectedType: T): asserts item is ResolveAnyJSType<T>;
+/**
+ * Asserts that all elements of the provided array are of the expected type. It ensures that the array is not sparse (even when the expectedType is undefined).
+ * @param {unknown[]} arr - The array which ought to be an array of the expectedType, i.e. expectedType: "number" => arr: number[]
+ * @param {AllJSTypes} expectedType - The expected type of individual items. JS primitive types, null, undefined, and constructable types are supported.
+ * @throws {AssertionError} if the type isn't as expected.
+ */
+export declare function assertArrayType<T extends AllJSTypes>(arr: unknown[], expectedType: T): asserts arr is ResolveAnyJSType<T>[];
+/**
+ * Asserts that the array or tuple has the expected types at each index.
+ * @param {unknown[] | [unknown, ...]} arrayOrTuple - The tuple which ought to be an array of the length and types.
+ * @param {[AllJSTypes, ...]} expectedTypes - A tuple of expected types of individual items, e.g., expectedTypes = ["number", "string", Date] => arrayOrTuple: [number, string, Date]. The individual entries can be JS primitive types, null, undefined, and constructors.
+ * @throws {AssertionError} if the type of any element of the tuple isn't as expected.
+ */
+export declare function assertTupleTypes<T extends readonly AllJSTypes[], U extends {
+    [K in keyof T]: unknown;
+} | (number extends U["length"] ? unknown[] : never)>(arrayOrTuple: U, expectedTypes: readonly [...T]): asserts arrayOrTuple is U & {
+    [K in keyof T]: ResolveAnyJSType<T[K]>;
+};
+/**
+ * Asserts that the provided item is of type string.
+ * @param {unknown} item - The item which ought to be of type string.
+ * @throws {AssertionError} if the type isn't string.
+ */
+export declare function assertTypeOfString(item: unknown): asserts item is string;
+/**
+ * Asserts that the provided item is of type number.
+ * @param {unknown} item - The item which ought to be of type number.
+ * @throws {AssertionError} if the type isn't number.
+ */
+export declare function assertTypeOfNumber(item: unknown): asserts item is number;
+/**
+ * Asserts that the provided item is of type boolean.
+ * @param {unknown} item - The item which ought to be of type boolean.
+ * @throws {AssertionError} if the type isn't boolean.
+ */
+export declare function assertTypeOfBoolean(item: unknown): asserts item is boolean;
+/**
+ * Asserts that the provided item is of type bigint.
+ * @param {unknown} item - The item which ought to be of type bigint.
+ * @throws {AssertionError} if the type isn't bigint.
+ */
+export declare function assertTypeOfBigint(item: unknown): asserts item is bigint;
+/**
+ * Asserts that the provided item is of type undefined.
+ * @param {unknown} item - The item which ought to be of type undefined.
+ * @throws {AssertionError} if the type isn't undefined.
+ */
+export declare function assertTypeOfUndefined(item: unknown): asserts item is undefined;
+/**
+ * Asserts that the provided item is of type function.
+ * @param {unknown} item - The item which ought to be of type function.
+ * @throws {AssertionError} if the type isn't function.
+ */
+export declare function assertTypeOfFunction(item: unknown): asserts item is Function;
+/**
+ * Asserts that the provided item is of type object.
+ * @param {unknown} item - The item which ought to be of type object.
+ * @throws {AssertionError} if the type isn't object.
+ */
+export declare function assertTypeOfObject(item: unknown): asserts item is object;
+/**
+ * Asserts that the provided item is of type symbol.
+ * @param {unknown} item - The item which ought to be of type symbol.
+ * @throws {AssertionError} if the type isn't symbol.
+ */
+export declare function assertTypeOfSymbol(item: unknown): asserts item is symbol;
+/**
+ * Asserts that the provided item is null.
+ * @param {unknown} item - The item which ought to be null.
+ * @throws {AssertionError} if the value isn't null.
+ */
+export declare function assertNull(item: unknown): asserts item is null;
+/**
+ * Asserts that the provided item is an instance of the provided constructor.
+ * @param {unknown} item - The item which ought to be an instance of the constructor.
+ * @param {Constructor<T>} constructor - Anything that can be after an instanceof operator.
+ * @throws {AssertionError} if item instanceof constructor is false.
+ */
+export declare function assertInstanceOf<T>(item: unknown, constructor: Constructor<T>): asserts item is T;
+/**
+ * Asserts that the provided array is a tuple of exactly the expected length.
+ * @param {unknown[]} arr - The array which ought to be a tuple.
+ * @param {number} expectedLength - The exact expected length of the tuple.
+ * @throws {AssertionError} if the array isn't of the expected length or is sparse.
+ */
+export declare function assertIsTuple<T extends number extends T["length"] ? unknown[] : never, N extends number>(arr: [...T], expectedLength: N): asserts arr is T & Tuple<T[number], N>;
+/**
+ * Used to assert that code can never be reached. Pass a value which has already been checked for all types that should be possible. If the range of possible values increases, TypeScript will throw an error at compile time because the value won't be of type never.
+ * @param {never} item - An exhausted value, of which all cases are accounted for in other branches of the code, such as at the end of a switch statement.
+ * @param {string} msg - Override the default error message. Even if you do, the error message will include the value and type of item.
+ * @throws {AssertionError} if at runtime the function call was reached. This should only happen if TypeScript types are inaccurate somewhere.
+ */
+export declare function assertUnreachable(item: never, msg?: string): asserts item is never;
+/**
+ * Asserts that the provided item is neither null nor undefined.
+ * @param {unknown} item - The item which ought to be non-null.
+ * @throws {AssertionError} if the item is null or undefined.
+ */
+export declare function assertNonNullable<T>(item: T): asserts item is NonNullable<T>;
+/**
+ * Asserts that the provided object has non-null values for the properties passed as keys in the propKeys array.
+ * @param {object} obj - The object which ought to have the properties.
+ * @param {NullableKeys<T>} propKeys - An array of the stringified keys of the properties which ought to be non-null in the object.
+ * @throws {AssertionError} if any of the properties was null, undefined, or not present in the object.
+ */
+export declare function assertPropsNonNullable<T extends object, N extends NullableKeys<T>>(obj: T, propKeys: N[]): asserts obj is PropsNonNullable<T, N>;
+/**
+ * Asserts that all elements of the provided array are neither null nor undefined, or not present.
+ * @param {unknown[]} arr - The array which ought to be non-sparse, and have only non-null elements.
+ * @throws {AssertionError} if any of the elements was null, undefined, or not present in the array.
+ */
+export declare function assertArrayNonNullable<T>(arr: T[]): asserts arr is NonNullable<T>[];
+/**
+ * Asserts that the provided tuple has non-null values for all elements. This function does not take a length. So if you want to assert that the typescript tuple type is of the correct length, call @see assertIsTuple first.
+ * @param {[unknown, ...]} tuple - The tuple which ought to have only non-null values.
+ * @throws {AssertionError} if any of the elements was null, undefined, or an index not present in the tuple.
+ */
+export declare function assertTupleNonNullable<T extends number extends T["length"] ? never : unknown[]>(tuple: T): asserts tuple is {
+    [K in keyof T]: NonNullable<T[K]>;
+};
+/**
+ * Asserts that the provided item is a finite number. Use to prevent NaN propagation.
+ * @param {unknown} item - The item which ought to be a finite number.
+ * @throws {AssertionError} if the item is not of type number, or isFinite(item) is false, i.e., if the item is NaN, Infinity, or -Infinity.
+ */
+export declare function assertFiniteNumber(item: unknown): asserts item is number;
 export {};

package/lib/index.js

@@ -1,113 +1,319 @@
+function getNameOfExpectedType(expectedType) {
+    if (expectedType === null)
+        return "null";
+    if (expectedType === undefined)
+        return "undefined";
+    if (typeof expectedType === "string")
+        return expectedType;
+    return expectedType.name;
+}
+function getTypeNameOfUnknown(item) {
+    if (item === null)
+        return "null";
+    if (item === undefined)
+        return "undefined";
+    try {
+        if (item instanceof item.constructor && item.constructor.name !== "Function") {
+            // I'd like function to match the primitive name "function"
+            // because that's how the asserts are written.
+            return item.constructor.name;
+        }
+    }
+    finally {
+        return typeof item;
+    }
+}
+function isType(item, expectedType) {
+    if (typeof item === expectedType)
+        return true;
+    const reducedExpectedType = expectedType;
+    if (item === reducedExpectedType)
+        return true;
+    const remainingOption = expectedType;
+    if (item instanceof remainingOption)
+        return true;
+    return false;
+}
 class AssertionError extends Error {
     constructor(msg) {
         super(`Assertion failed: ${msg}`);
         this.name = AssertionError.name;
     }
 }
+/**
+ * Asserts that the provided boolean is true.
+ * @param {boolean} hasToBeTrue - The boolean to assert.
+ * @param {string} msg - The message of the Error if the assertion fails.
+ * @throws {AssertionError} if the assertion fails.
+ */
 export function assert(hasToBeTrue, msg = "No specific message provided.") {
     if (!import.meta.env.DEV)
         return;
     if (!hasToBeTrue)
         throw new AssertionError(msg);
 }
-export function assertType(obj, expectedType) {
+/**
+ * Asserts that the provided object is of the expectedType.
+ * @param {unknown} item - The object which ought to be of the expectedType.
+ * @param {AllJSTypes} expectedType - The expected type of the object. JS primitive types, null, undefined, and constructable types are supported. JS primitive types are passed as the string they return from typeof, e.g., "number".
+ * @throws {AssertionError} if the type isn't as expected.
+ */
+export function assertType(item, expectedType) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj === expectedType)
+    if (!isType(item, expectedType))
+        throw new AssertionError(`Provided object was not of type ${getNameOfExpectedType(expectedType)}. Was: ${getTypeNameOfUnknown(item)}, value: ${item}`);
+}
+/**
+ * Asserts that all elements of the provided array are of the expected type. It ensures that the array is not sparse (even when the expectedType is undefined).
+ * @param {unknown[]} arr - The array which ought to be an array of the expectedType, i.e. expectedType: "number" => arr: number[]
+ * @param {AllJSTypes} expectedType - The expected type of individual items. JS primitive types, null, undefined, and constructable types are supported.
+ * @throws {AssertionError} if the type isn't as expected.
+ */
+export function assertArrayType(arr, expectedType) {
+    if (!import.meta.env.DEV)
         return;
-    const reducedExpectedType = expectedType;
-    if (obj === reducedExpectedType)
+    for (let i = 0; i < arr.length; i++) {
+        if (!(i in arr))
+            throw new AssertionError(`Array to assert type of was sparse with a missing item at index ${i}`);
+        const item = arr[i];
+        if (!isType(item, expectedType))
+            throw new AssertionError(`Provided array had item at index ${i} not of type ${getNameOfExpectedType(expectedType)}. Was: ${getTypeNameOfUnknown(item)}, value: ${item}`);
+    }
+}
+/**
+ * Asserts that the array or tuple has the expected types at each index.
+ * @param {unknown[] | [unknown, ...]} arrayOrTuple - The tuple which ought to be an array of the length and types.
+ * @param {[AllJSTypes, ...]} expectedTypes - A tuple of expected types of individual items, e.g., expectedTypes = ["number", "string", Date] => arrayOrTuple: [number, string, Date]. The individual entries can be JS primitive types, null, undefined, and constructors.
+ * @throws {AssertionError} if the type of any element of the tuple isn't as expected.
+ */
+export function assertTupleTypes(arrayOrTuple, expectedTypes) {
+    if (!import.meta.env.DEV)
         return;
-    const remainingOption = expectedType;
-    if (obj instanceof remainingOption)
+    if (arrayOrTuple.length !== expectedTypes.length) {
+        throw new AssertionError(`Provided tuple length mismatch: expected ${expectedTypes.length}, but got ${arrayOrTuple.length}`);
+    }
+    for (let i = 0; i < expectedTypes.length; i++) {
+        if (!(i in arrayOrTuple))
+            throw new AssertionError(`Provided tuple was sparse with a missing item at required index ${i}`);
+        const item = arrayOrTuple[i];
+        if (!isType(item, expectedTypes[i])) {
+            throw new AssertionError(`Provided tuple had item at index ${i} not of type ${getNameOfExpectedType(expectedTypes[i])}. Was: ${getTypeNameOfUnknown(item)}, value: ${item}`);
+        }
+    }
+}
+/**
+ * Asserts that the provided item is of type string.
+ * @param {unknown} item - The item which ought to be of type string.
+ * @throws {AssertionError} if the type isn't string.
+ */
+export function assertTypeOfString(item) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof item !== "string")
+        throw new AssertionError(`Provided item was not of type string. Was: ${getTypeNameOfUnknown(item)}`);
+}
+/**
+ * Asserts that the provided item is of type number.
+ * @param {unknown} item - The item which ought to be of type number.
+ * @throws {AssertionError} if the type isn't number.
+ */
+export function assertTypeOfNumber(item) {
+    if (!import.meta.env.DEV)
         return;
-    throw new AssertionError(`Provided object was not of type ${(typeof expectedType !== "string") ? expectedType?.name : expectedType ?? expectedType}. Was: ${(obj === null) ? "null" : obj?.constructor?.name ?? typeof obj}, value: ${obj}`);
+    if (typeof item !== "number")
+        throw new AssertionError(`Provided item was not of type number. Was: ${getTypeNameOfUnknown(item)}`);
 }
-export function assertTypeOfString(obj) {
+/**
+ * Asserts that the provided item is of type boolean.
+ * @param {unknown} item - The item which ought to be of type boolean.
+ * @throws {AssertionError} if the type isn't boolean.
+ */
+export function assertTypeOfBoolean(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "string")
-        throw new AssertionError(`Provided object was not of type string. Was: ${typeof obj}`);
+    if (typeof item !== "boolean")
+        throw new AssertionError(`Provided item was not of type boolean. Was: ${getTypeNameOfUnknown(item)}`);
 }
-export function assertTypeOfNumber(obj) {
+/**
+ * Asserts that the provided item is of type bigint.
+ * @param {unknown} item - The item which ought to be of type bigint.
+ * @throws {AssertionError} if the type isn't bigint.
+ */
+export function assertTypeOfBigint(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "number")
-        throw new AssertionError(`Provided object was not of type number. Was: ${typeof obj}`);
+    if (typeof item !== "bigint")
+        throw new AssertionError(`Provided item was not of type bigint. Was: ${getTypeNameOfUnknown(item)}`);
 }
-export function assertTypeOfBoolean(obj) {
+/**
+ * Asserts that the provided item is of type undefined.
+ * @param {unknown} item - The item which ought to be of type undefined.
+ * @throws {AssertionError} if the type isn't undefined.
+ */
+export function assertTypeOfUndefined(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "boolean")
-        throw new AssertionError(`Provided object was not of type boolean. Was: ${typeof obj}`);
+    if (typeof item !== "undefined")
+        throw new AssertionError(`Provided item was not of type undefined. Was: ${getTypeNameOfUnknown(item)}`);
 }
-export function assertTypeOfBigint(obj) {
+/**
+ * Asserts that the provided item is of type function.
+ * @param {unknown} item - The item which ought to be of type function.
+ * @throws {AssertionError} if the type isn't function.
+ */
+export function assertTypeOfFunction(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "bigint")
-        throw new AssertionError(`Provided object was not of type bigint. Was: ${typeof obj}`);
+    if (typeof item !== "function")
+        throw new AssertionError(`Provided item was not of type function. Was: ${getTypeNameOfUnknown(item)}`);
 }
-export function assertTypeOfUndefined(obj) {
+/**
+ * Asserts that the provided item is of type object.
+ * @param {unknown} item - The item which ought to be of type object.
+ * @throws {AssertionError} if the type isn't object.
+ */
+export function assertTypeOfObject(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "undefined")
-        throw new AssertionError(`Provided object was not of type undefined. Was: ${typeof obj}`);
+    if (typeof item !== "object")
+        throw new AssertionError(`Provided item was not of type object. Was: ${getTypeNameOfUnknown(item)}`);
 }
-// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-export function assertTypeOfFunction(obj) {
+/**
+ * Asserts that the provided item is of type symbol.
+ * @param {unknown} item - The item which ought to be of type symbol.
+ * @throws {AssertionError} if the type isn't symbol.
+ */
+export function assertTypeOfSymbol(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "function")
-        throw new AssertionError(`Provided object was not of type function. Was: ${typeof obj}`);
+    if (typeof item !== "symbol")
+        throw new AssertionError(`Provided item was not of type symbol. Was: ${getTypeNameOfUnknown(item)}`);
 }
-export function assertTypeOfObject(obj) {
+/**
+ * Asserts that the provided item is null.
+ * @param {unknown} item - The item which ought to be null.
+ * @throws {AssertionError} if the value isn't null.
+ */
+export function assertNull(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "object")
-        throw new AssertionError(`Provided object was not of type object. Was: ${typeof obj}`);
+    if (item !== null)
+        throw new AssertionError(`Provided item was not null. Was type: ${getTypeNameOfUnknown(item)}, value: ${item}`);
 }
-export function assertTypeOfSymbol(obj) {
+/**
+ * Asserts that the provided item is an instance of the provided constructor.
+ * @param {unknown} item - The item which ought to be an instance of the constructor.
+ * @param {Constructor<T>} constructor - Anything that can be after an instanceof operator.
+ * @throws {AssertionError} if item instanceof constructor is false.
+ */
+export function assertInstanceOf(item, constructor) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "symbol")
-        throw new AssertionError(`Provided object was not of type symbol. Was: ${typeof obj}`);
+    if (!(item instanceof constructor))
+        throw new AssertionError(`Provided item was not of type ${constructor.name} but was type: ${getTypeNameOfUnknown(item)}, value: ${item}`);
 }
-export function assertNull(obj) {
+/**
+ * Asserts that the provided array is a tuple of exactly the expected length.
+ * @param {unknown[]} arr - The array which ought to be a tuple.
+ * @param {number} expectedLength - The exact expected length of the tuple.
+ * @throws {AssertionError} if the array isn't of the expected length or is sparse.
+ */
+export function assertIsTuple(arr, expectedLength) {
     if (!import.meta.env.DEV)
         return;
-    if (obj !== null)
-        throw new AssertionError(`Provided object was not null. Was: ${obj}`);
+    if (arr.length !== expectedLength) {
+        throw new AssertionError(`Provided array is not a tuple of expected length ${expectedLength}. It has length ${arr.length}.`);
+    }
+    for (let i = 0; i < expectedLength; i++) {
+        if (!(i in arr))
+            throw new AssertionError(`Provided tuple is sparse and therefore not a tuple. Index ${i} is missing.`);
+    }
 }
-export function assertInstanceOf(obj, constructable) {
+/**
+ * Used to assert that code can never be reached. Pass a value which has already been checked for all types that should be possible. If the range of possible values increases, TypeScript will throw an error at compile time because the value won't be of type never.
+ * @param {never} item - An exhausted value, of which all cases are accounted for in other branches of the code, such as at the end of a switch statement.
+ * @param {string} msg - Override the default error message. Even if you do, the error message will include the value and type of item.
+ * @throws {AssertionError} if at runtime the function call was reached. This should only happen if TypeScript types are inaccurate somewhere.
+ */
+export function assertUnreachable(item, msg = "Unreachable code of type never was reached. TypeScript types are inaccurate somewhere.") {
     if (!import.meta.env.DEV)
         return;
-    if (!(obj instanceof constructable))
-        throw new AssertionError(`Provided object was not of type ${constructable.name} but was type: ${(obj === null) ? "null" : obj?.constructor?.name ?? typeof obj}, value: ${obj}`);
+    throw new AssertionError(msg +
+        `\nValue of type never was actually of type: ${getTypeNameOfUnknown(item)}, value: ${item}`);
 }
-export function assertUnreachable(obj, msg = "Unreachable code of type never was reached. TypeScript types are inaccurate somewhere.") {
+/**
+ * Asserts that the provided item is neither null nor undefined.
+ * @param {unknown} item - The item which ought to be non-null.
+ * @throws {AssertionError} if the item is null or undefined.
+ */
+export function assertNonNullable(item) {
     if (!import.meta.env.DEV)
         return;
-    throw new AssertionError(msg);
+    if (item === undefined || item === null)
+        throw new AssertionError(`Provided item should've been non-null but was: ${item}`);
 }
-export function assertPropsNonNullable(obj, props) {
+/**
+ * Asserts that the provided object has non-null values for the properties passed as keys in the propKeys array.
+ * @param {object} obj - The object which ought to have the properties.
+ * @param {NullableKeys<T>} propKeys - An array of the stringified keys of the properties which ought to be non-null in the object.
+ * @throws {AssertionError} if any of the properties was null, undefined, or not present in the object.
+ */
+export function assertPropsNonNullable(obj, propKeys) {
     if (!import.meta.env.DEV)
         return;
-    for (const prop of props) {
-        if (obj[prop] === null || obj[prop] === undefined)
-            throw new AssertionError(`Provided object prop ${String(prop)} should've been non-null but was: ${obj[prop]}`);
+    for (const propKey of propKeys) {
+        if (!(propKey in obj))
+            throw new AssertionError(`Provided object prop ${String(propKey)} should've been non-null but was not present at all.`);
+        if (obj[propKey] === null || obj[propKey] === undefined)
+            throw new AssertionError(`Provided object prop ${String(propKey)} should've been non-null but was: ${obj[propKey]}`);
     }
 }
-export function assertNonNullable(obj) {
+/**
+ * Asserts that all elements of the provided array are neither null nor undefined, or not present.
+ * @param {unknown[]} arr - The array which ought to be non-sparse, and have only non-null elements.
+ * @throws {AssertionError} if any of the elements was null, undefined, or not present in the array.
+ */
+export function assertArrayNonNullable(arr) {
     if (!import.meta.env.DEV)
         return;
-    if (obj === undefined || obj === null)
-        throw new AssertionError(`Provided object should've been non-null but was: ${obj}`);
+    for (let i = 0; i < arr.length; i++) {
+        if (!(i in arr))
+            throw new AssertionError(`Provided array should've been non-null but was sparse with a missing item at index ${i}`);
+        const item = arr[i];
+        if (item === null)
+            throw new AssertionError(`Provided array should've been non-null but had an item with value null at index ${i}`);
+        if (item === undefined)
+            throw new AssertionError(`Provided array should've been non-null but had an undefined item at index ${i}`);
+    }
+}
+/**
+ * Asserts that the provided tuple has non-null values for all elements. This function does not take a length. So if you want to assert that the typescript tuple type is of the correct length, call @see assertIsTuple first.
+ * @param {[unknown, ...]} tuple - The tuple which ought to have only non-null values.
+ * @throws {AssertionError} if any of the elements was null, undefined, or an index not present in the tuple.
+ */
+export function assertTupleNonNullable(tuple) {
+    if (!import.meta.env.DEV)
+        return;
+    for (let i = 0; i < tuple.length; i++) {
+        if (!(i in tuple))
+            throw new AssertionError(`Provided tuple should've been non-null but is sparse. Index ${i} is missing.`);
+        if (tuple[i] === null)
+            throw new AssertionError(`Provided tuple should've been non-null but had an item with value null at index ${i}`);
+        if (tuple[i] === undefined)
+            throw new AssertionError(`Provided tuple should've been non-null but had an undefined item at index ${i}`);
+    }
 }
-export function assertFiniteNumber(obj) {
+/**
+ * Asserts that the provided item is a finite number. Use to prevent NaN propagation.
+ * @param {unknown} item - The item which ought to be a finite number.
+ * @throws {AssertionError} if the item is not of type number, or isFinite(item) is false, i.e., if the item is NaN, Infinity, or -Infinity.
+ */
+export function assertFiniteNumber(item) {
     if (!import.meta.env.DEV)
         return;
-    if (typeof obj !== "number")
-        throw new AssertionError(`Provided object was not of type number. Was: ${typeof obj}`);
-    if (!isFinite(obj))
-        throw new AssertionError(`Provided number was not finite. Was: ${obj}`);
+    if (typeof item !== "number")
+        throw new AssertionError(`Provided item was not of type number. Was: ${getTypeNameOfUnknown(item)}`);
+    if (!isFinite(item))
+        throw new AssertionError(`Provided number was not finite. Was: ${item}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assertie",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Debug assertions for TypeScript, auto tree-shaken by vite for production.",
   "keywords": [
     "TypeScript",
@@ -29,12 +29,12 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "typescript": ">=3.7.0",
+    "typescript": ">=4.7.0",
     "vite": ">=2.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.7.3",
-    "vite": "^6.1.0"
+    "typescript": "~4.7.0",
+    "vite": "~2.0.0"
   },
   "scripts": {
     "build": "tsc"

package/src/index.ts

@@ -1,21 +1,70 @@
-type PrimitiveTypeStrings = "string" | "number" | "boolean" | "bigint" | "undefined" | "function" | "object" | "symbol";
+// Creates a tuple of length N with all elements of type T
+type Tuple<T, N extends number, A extends unknown[] = []> =
+    A["length"] extends N ? A : Tuple<T, N, [...A, T]>;
+
 type PrimitiveTypes = {
-    "string": string,
-    "number": number,
-    "boolean": boolean,
-    "bigint": bigint,
-    "undefined": undefined,
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-    "function": Function,
-    "object": object,
-    "symbol": symbol
-}
-
-type NullableKeys<T> = { 
-    [K in keyof T]-?: undefined extends T[K] ? K : null extends T[K] ? K : never 
+    "string": string;
+    "number": number;
+    "boolean": boolean;
+    "bigint": bigint;
+    "undefined": undefined;
+    "function": Function;
+    "object": object;
+    "symbol": symbol;
+};
+type PrimitiveTypeStrings = keyof PrimitiveTypes;
+
+type NullableKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? K : null extends T[K] ? K : never;
 }[keyof T];
 
-type PropsNonNullable<T, N extends NullableKeys<T>> =  T & { [K in N]-?: NonNullable<T[K]> };
+type PropsNonNullable<T, N extends NullableKeys<T>> = T & {
+    [K in N]-?: NonNullable<T[K]>;
+};
+
+type Constructor<T> = new (...args: unknown[]) => T;
+
+type AllJSTypes = PrimitiveTypeStrings | null | undefined | Constructor<unknown>;
+
+type ResolveAnyJSType<T extends AllJSTypes> = T extends 
+    | PrimitiveTypeStrings ? PrimitiveTypes[T]
+    : T extends null ? null
+    : T extends undefined ? undefined
+    : T extends Constructor<infer U> ? U
+    : never;
+
+function getNameOfExpectedType(expectedType: AllJSTypes): string {
+    if (expectedType === null) return "null";
+    if (expectedType === undefined) return "undefined";
+    if (typeof expectedType === "string") return expectedType;
+    return expectedType.name;
+}
+
+function getTypeNameOfUnknown(item: unknown): string {
+    if (item === null) return "null";
+    if (item === undefined) return "undefined";
+    try {
+        if (item instanceof item.constructor && item.constructor.name !== "Function") {
+            // I'd like function to match the primitive name "function"
+            // because that's how the asserts are written.
+            return item.constructor.name;
+        }
+    } finally {
+        return typeof item;
+    }
+}
+
+function isType<T extends AllJSTypes>(item: unknown, expectedType: T): item is ResolveAnyJSType<T> {
+    if (typeof item === expectedType) return true;
+    const reducedExpectedType = expectedType as Exclude<typeof expectedType, PrimitiveTypeStrings>;
+
+    if (item === reducedExpectedType) return true;
+    const remainingOption = expectedType as Exclude<typeof reducedExpectedType, null | undefined>;
+
+    if (item instanceof remainingOption) return true;
+
+    return false;
+}
 
 class AssertionError extends Error {
     constructor(msg: string) {
@@ -24,103 +73,376 @@ class AssertionError extends Error {
     }
 }
 
-type Constructor<T> = new (...args: unknown[]) => T;
-type AllJSTypes = PrimitiveTypeStrings | null | undefined | Constructor<unknown>;
-type ResolveAnyJSType<T extends AllJSTypes> = T extends PrimitiveTypeStrings ? PrimitiveTypes[T]
-    : T extends null ? null : T extends undefined ? undefined
-    : T extends Constructor<infer U> ? U : never;
+/**
+ * Asserts that the provided boolean is true.
+ * @param {boolean} hasToBeTrue - The boolean to assert.
+ * @param {string} msg - The message of the Error if the assertion fails.
+ * @throws {AssertionError} if the assertion fails.
+ */
+export function assert(
+    hasToBeTrue: boolean,
+    msg: string = "No specific message provided."
+): asserts hasToBeTrue is true {
+    if (!import.meta.env.DEV) return;
+    if (!hasToBeTrue) throw new AssertionError(msg);
+}
 
+/**
+ * Asserts that the provided object is of the expectedType.
+ * @param {unknown} item - The object which ought to be of the expectedType.
+ * @param {AllJSTypes} expectedType - The expected type of the object. JS primitive types, null, undefined, and constructable types are supported. JS primitive types are passed as the string they return from typeof, e.g., "number".
+ * @throws {AssertionError} if the type isn't as expected.
+ */
+export function assertType<T extends AllJSTypes>(
+    item: unknown,
+    expectedType: T
+): asserts item is ResolveAnyJSType<T> {
+    if (!import.meta.env.DEV) return;
+    if (!isType(item, expectedType))
+        throw new AssertionError(
+            `Provided object was not of type ${getNameOfExpectedType(
+                expectedType
+            )}. Was: ${getTypeNameOfUnknown(item)}, value: ${item}`
+        );
+}
 
-export function assert(hasToBeTrue: boolean, msg: string = "No specific message provided."): asserts hasToBeTrue is true {
+/**
+ * Asserts that all elements of the provided array are of the expected type. It ensures that the array is not sparse (even when the expectedType is undefined).
+ * @param {unknown[]} arr - The array which ought to be an array of the expectedType, i.e. expectedType: "number" => arr: number[]
+ * @param {AllJSTypes} expectedType - The expected type of individual items. JS primitive types, null, undefined, and constructable types are supported.
+ * @throws {AssertionError} if the type isn't as expected.
+ */
+export function assertArrayType<T extends AllJSTypes>(
+    arr: unknown[],
+    expectedType: T
+): asserts arr is ResolveAnyJSType<T>[] {
     if (!import.meta.env.DEV) return;
-    if (!hasToBeTrue) throw new AssertionError(msg);
+    for (let i = 0; i < arr.length; i++) {
+        if (!(i in arr))
+            throw new AssertionError(
+                `Array to assert type of was sparse with a missing item at index ${i}`
+            );
+        const item = arr[i];
+        if (!isType(item, expectedType))
+            throw new AssertionError(
+                `Provided array had item at index ${i} not of type ${getNameOfExpectedType(
+                    expectedType
+                )}. Was: ${getTypeNameOfUnknown(item)}, value: ${item}`
+            );
+    }
 }
 
-export function assertType<T extends AllJSTypes>(obj: unknown, expectedType: T): asserts obj is ResolveAnyJSType<T> {
+/**
+ * Asserts that the array or tuple has the expected types at each index.
+ * @param {unknown[] | [unknown, ...]} arrayOrTuple - The tuple which ought to be an array of the length and types.
+ * @param {[AllJSTypes, ...]} expectedTypes - A tuple of expected types of individual items, e.g., expectedTypes = ["number", "string", Date] => arrayOrTuple: [number, string, Date]. The individual entries can be JS primitive types, null, undefined, and constructors.
+ * @throws {AssertionError} if the type of any element of the tuple isn't as expected.
+ */
+export function assertTupleTypes<
+    T extends readonly AllJSTypes[],
+    U extends
+        | { [K in keyof T]: unknown } // [...unknown] matching length of [...T]
+        | (number extends U["length"] ? unknown[] : never) // Array with compile time unknown length
+>(
+    arrayOrTuple: U,
+    expectedTypes: readonly [...T]
+): asserts arrayOrTuple is U & { [K in keyof T]: ResolveAnyJSType<T[K]> } {
     if (!import.meta.env.DEV) return;
+    if (arrayOrTuple.length !== expectedTypes.length) {
+        throw new AssertionError(
+            `Provided tuple length mismatch: expected ${expectedTypes.length}, but got ${arrayOrTuple.length}`
+        );
+    }
+    for (let i = 0; i < expectedTypes.length; i++) {
+        if (!(i in arrayOrTuple))
+            throw new AssertionError(
+                `Provided tuple was sparse with a missing item at required index ${i}`
+            );
+        const item = arrayOrTuple[i];
+        if (!isType(item, expectedTypes[i])) {
+            throw new AssertionError(
+                `Provided tuple had item at index ${i} not of type ${getNameOfExpectedType(
+                    expectedTypes[i]
+                )}. Was: ${getTypeNameOfUnknown(item)}, value: ${item}`
+            );
+        }
+    }
+}
 
-    if (typeof obj === expectedType) return;
-    const reducedExpectedType = expectedType as Exclude<typeof expectedType, PrimitiveTypeStrings>;
+/**
+ * Asserts that the provided item is of type string.
+ * @param {unknown} item - The item which ought to be of type string.
+ * @throws {AssertionError} if the type isn't string.
+ */
+export function assertTypeOfString(item: unknown): asserts item is string {
+    if (!import.meta.env.DEV) return;
+    if (typeof item !== "string")
+        throw new AssertionError(
+            `Provided item was not of type string. Was: ${getTypeNameOfUnknown(item)}`
+        );
+}
 
-    if (obj === reducedExpectedType) return;
-    const remainingOption = expectedType as Exclude<typeof reducedExpectedType, null | undefined>;
+/**
+ * Asserts that the provided item is of type number.
+ * @param {unknown} item - The item which ought to be of type number.
+ * @throws {AssertionError} if the type isn't number.
+ */
+export function assertTypeOfNumber(item: unknown): asserts item is number {
+    if (!import.meta.env.DEV) return;
+    if (typeof item !== "number")
+        throw new AssertionError(
+            `Provided item was not of type number. Was: ${getTypeNameOfUnknown(item)}`
+        );
+}
 
-    if (obj instanceof remainingOption) return;
-    
-    throw new AssertionError(`Provided object was not of type ${(typeof expectedType !== "string") ? expectedType?.name : expectedType ?? expectedType}. Was: ${(obj === null) ? "null" : obj?.constructor?.name ?? typeof obj}, value: ${obj}`);
+/**
+ * Asserts that the provided item is of type boolean.
+ * @param {unknown} item - The item which ought to be of type boolean.
+ * @throws {AssertionError} if the type isn't boolean.
+ */
+export function assertTypeOfBoolean(item: unknown): asserts item is boolean {
+    if (!import.meta.env.DEV) return;
+    if (typeof item !== "boolean")
+        throw new AssertionError(
+            `Provided item was not of type boolean. Was: ${getTypeNameOfUnknown(item)}`
+        );
 }
 
-export function assertTypeOfString(obj: unknown): asserts obj is string {
+/**
+ * Asserts that the provided item is of type bigint.
+ * @param {unknown} item - The item which ought to be of type bigint.
+ * @throws {AssertionError} if the type isn't bigint.
+ */
+export function assertTypeOfBigint(item: unknown): asserts item is bigint {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "string") throw new AssertionError(`Provided object was not of type string. Was: ${typeof obj}`);
+    if (typeof item !== "bigint")
+        throw new AssertionError(
+            `Provided item was not of type bigint. Was: ${getTypeNameOfUnknown(item)}`
+        );
 }
 
-export function assertTypeOfNumber(obj: unknown): asserts obj is number {
+/**
+ * Asserts that the provided item is of type undefined.
+ * @param {unknown} item - The item which ought to be of type undefined.
+ * @throws {AssertionError} if the type isn't undefined.
+ */
+export function assertTypeOfUndefined(item: unknown): asserts item is undefined {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "number") throw new AssertionError(`Provided object was not of type number. Was: ${typeof obj}`);
+    if (typeof item !== "undefined")
+        throw new AssertionError(
+            `Provided item was not of type undefined. Was: ${getTypeNameOfUnknown(item)}`
+        );
 }
 
-export function assertTypeOfBoolean(obj: unknown): asserts obj is boolean {
+/**
+ * Asserts that the provided item is of type function.
+ * @param {unknown} item - The item which ought to be of type function.
+ * @throws {AssertionError} if the type isn't function.
+ */
+export function assertTypeOfFunction(item: unknown): asserts item is Function {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "boolean") throw new AssertionError(`Provided object was not of type boolean. Was: ${typeof obj}`);
+    if (typeof item !== "function")
+        throw new AssertionError(
+            `Provided item was not of type function. Was: ${getTypeNameOfUnknown(item)}`
+        );
 }
 
-export function assertTypeOfBigint(obj: unknown): asserts obj is bigint {
+/**
+ * Asserts that the provided item is of type object.
+ * @param {unknown} item - The item which ought to be of type object.
+ * @throws {AssertionError} if the type isn't object.
+ */
+export function assertTypeOfObject(item: unknown): asserts item is object {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "bigint") throw new AssertionError(`Provided object was not of type bigint. Was: ${typeof obj}`);
+    if (typeof item !== "object")
+        throw new AssertionError(
+            `Provided item was not of type object. Was: ${getTypeNameOfUnknown(item)}`
+        );
 }
 
-export function assertTypeOfUndefined(obj: unknown): asserts obj is undefined {
+/**
+ * Asserts that the provided item is of type symbol.
+ * @param {unknown} item - The item which ought to be of type symbol.
+ * @throws {AssertionError} if the type isn't symbol.
+ */
+export function assertTypeOfSymbol(item: unknown): asserts item is symbol {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "undefined") throw new AssertionError(`Provided object was not of type undefined. Was: ${typeof obj}`);
+    if (typeof item !== "symbol")
+        throw new AssertionError(
+            `Provided item was not of type symbol. Was: ${getTypeNameOfUnknown(item)}`
+        );
 }
 
-// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-export function assertTypeOfFunction(obj: unknown): asserts obj is Function {
+/**
+ * Asserts that the provided item is null.
+ * @param {unknown} item - The item which ought to be null.
+ * @throws {AssertionError} if the value isn't null.
+ */
+export function assertNull(item: unknown): asserts item is null {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "function") throw new AssertionError(`Provided object was not of type function. Was: ${typeof obj}`);
+    if (item !== null)
+        throw new AssertionError(
+            `Provided item was not null. Was type: ${getTypeNameOfUnknown(item)}, value: ${item}`
+        );
 }
 
-export function assertTypeOfObject(obj: unknown): asserts obj is object {
+/**
+ * Asserts that the provided item is an instance of the provided constructor.
+ * @param {unknown} item - The item which ought to be an instance of the constructor.
+ * @param {Constructor<T>} constructor - Anything that can be after an instanceof operator.
+ * @throws {AssertionError} if item instanceof constructor is false.
+ */
+export function assertInstanceOf<T>(item: unknown, constructor: Constructor<T>): asserts item is T {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "object") throw new AssertionError(`Provided object was not of type object. Was: ${typeof obj}`);
+    if (!(item instanceof constructor))
+        throw new AssertionError(
+            `Provided item was not of type ${constructor.name} but was type: ${getTypeNameOfUnknown(
+                item
+            )}, value: ${item}`
+        );
 }
 
-export function assertTypeOfSymbol(obj: unknown): asserts obj is symbol {
+/**
+ * Asserts that the provided array is a tuple of exactly the expected length.
+ * @param {unknown[]} arr - The array which ought to be a tuple.
+ * @param {number} expectedLength - The exact expected length of the tuple.
+ * @throws {AssertionError} if the array isn't of the expected length or is sparse.
+ */
+export function assertIsTuple<
+    T extends number extends T["length"] ? unknown[] : never,
+    N extends number
+>(arr: [...T], expectedLength: N): asserts arr is T & Tuple<T[number], N> {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "symbol") throw new AssertionError(`Provided object was not of type symbol. Was: ${typeof obj}`);
+    if (arr.length !== expectedLength) {
+        throw new AssertionError(
+            `Provided array is not a tuple of expected length ${expectedLength}. It has length ${arr.length}.`
+        );
+    }
+    for (let i = 0; i < expectedLength; i++) {
+        if (!(i in arr))
+            throw new AssertionError(
+                `Provided tuple is sparse and therefore not a tuple. Index ${i} is missing.`
+            );
+    }
 }
 
-export function assertNull(obj: unknown): asserts obj is null {
+/**
+ * Used to assert that code can never be reached. Pass a value which has already been checked for all types that should be possible. If the range of possible values increases, TypeScript will throw an error at compile time because the value won't be of type never.
+ * @param {never} item - An exhausted value, of which all cases are accounted for in other branches of the code, such as at the end of a switch statement.
+ * @param {string} msg - Override the default error message. Even if you do, the error message will include the value and type of item.
+ * @throws {AssertionError} if at runtime the function call was reached. This should only happen if TypeScript types are inaccurate somewhere.
+ */
+export function assertUnreachable(
+    item: never,
+    msg: string = "Unreachable code of type never was reached. TypeScript types are inaccurate somewhere."
+): asserts item is never {
     if (!import.meta.env.DEV) return;
-    if (obj !== null) throw new AssertionError(`Provided object was not null. Was: ${obj}`);
+    throw new AssertionError(
+        msg +
+            `\nValue of type never was actually of type: ${getTypeNameOfUnknown(
+                item
+            )}, value: ${item}`
+    );
 }
 
-export function assertInstanceOf<T>(obj: unknown, constructable: Constructor<T>): asserts obj is T {
+/**
+ * Asserts that the provided item is neither null nor undefined.
+ * @param {unknown} item - The item which ought to be non-null.
+ * @throws {AssertionError} if the item is null or undefined.
+ */
+export function assertNonNullable<T>(item: T): asserts item is NonNullable<T> {
     if (!import.meta.env.DEV) return;
-    if (!(obj instanceof constructable)) throw new AssertionError(`Provided object was not of type ${constructable.name} but was type: ${(obj === null) ? "null" : obj?.constructor?.name ?? typeof obj}, value: ${obj}`);
+    if (item === undefined || item === null)
+        throw new AssertionError(`Provided item should've been non-null but was: ${item}`);
 }
 
-export function assertUnreachable(obj: never, msg: string = "Unreachable code of type never was reached. TypeScript types are inaccurate somewhere."): asserts obj is never {
+/**
+ * Asserts that the provided object has non-null values for the properties passed as keys in the propKeys array.
+ * @param {object} obj - The object which ought to have the properties.
+ * @param {NullableKeys<T>} propKeys - An array of the stringified keys of the properties which ought to be non-null in the object.
+ * @throws {AssertionError} if any of the properties was null, undefined, or not present in the object.
+ */
+export function assertPropsNonNullable<T extends object, N extends NullableKeys<T>>(
+    obj: T,
+    propKeys: N[]
+): asserts obj is PropsNonNullable<T, N> {
     if (!import.meta.env.DEV) return;
-    throw new AssertionError(msg);
+    for (const propKey of propKeys) {
+        if (!(propKey in obj))
+            throw new AssertionError(
+                `Provided object prop ${String(
+                    propKey
+                )} should've been non-null but was not present at all.`
+            );
+        if (obj[propKey] === null || obj[propKey] === undefined)
+            throw new AssertionError(
+                `Provided object prop ${String(propKey)} should've been non-null but was: ${
+                    obj[propKey]
+                }`
+            );
+    }
 }
 
-export function assertPropsNonNullable<T, N extends NullableKeys<T>>(obj: T, props: N[]): asserts obj is PropsNonNullable<T, N> {
+/**
+ * Asserts that all elements of the provided array are neither null nor undefined, or not present.
+ * @param {unknown[]} arr - The array which ought to be non-sparse, and have only non-null elements.
+ * @throws {AssertionError} if any of the elements was null, undefined, or not present in the array.
+ */
+export function assertArrayNonNullable<T>(arr: T[]): asserts arr is NonNullable<T>[] {
     if (!import.meta.env.DEV) return;
-    for (const prop of props) {
-        if (obj[prop] === null || obj[prop] === undefined)
-            throw new AssertionError(`Provided object prop ${String(prop)} should've been non-null but was: ${obj[prop]}`);
+    for (let i = 0; i < arr.length; i++) {
+        if (!(i in arr))
+            throw new AssertionError(
+                `Provided array should've been non-null but was sparse with a missing item at index ${i}`
+            );
+        const item = arr[i];
+        if (item === null)
+            throw new AssertionError(
+                `Provided array should've been non-null but had an item with value null at index ${i}`
+            );
+        if (item === undefined)
+            throw new AssertionError(
+                `Provided array should've been non-null but had an undefined item at index ${i}`
+            );
     }
 }
 
-export function assertNonNullable<T>(obj: T): asserts obj is NonNullable<T> {
+/**
+ * Asserts that the provided tuple has non-null values for all elements. This function does not take a length. So if you want to assert that the typescript tuple type is of the correct length, call @see assertIsTuple first.
+ * @param {[unknown, ...]} tuple - The tuple which ought to have only non-null values.
+ * @throws {AssertionError} if any of the elements was null, undefined, or an index not present in the tuple.
+ */
+export function assertTupleNonNullable<T extends number extends T["length"] ? never : unknown[]>(
+    tuple: T
+): asserts tuple is { [K in keyof T]: NonNullable<T[K]> } {
     if (!import.meta.env.DEV) return;
-    if (obj === undefined || obj === null) throw new AssertionError(`Provided object should've been non-null but was: ${obj}`);
+    for (let i = 0; i < tuple.length; i++) {
+        if (!(i in tuple))
+            throw new AssertionError(
+                `Provided tuple should've been non-null but is sparse. Index ${i} is missing.`
+            );
+        if (tuple[i] === null)
+            throw new AssertionError(
+                `Provided tuple should've been non-null but had an item with value null at index ${i}`
+            );
+        if (tuple[i] === undefined)
+            throw new AssertionError(
+                `Provided tuple should've been non-null but had an undefined item at index ${i}`
+            );
+    }
 }
 
-export function assertFiniteNumber(obj: unknown): asserts obj is number {
+
+/**
+ * Asserts that the provided item is a finite number. Use to prevent NaN propagation.
+ * @param {unknown} item - The item which ought to be a finite number.
+ * @throws {AssertionError} if the item is not of type number, or isFinite(item) is false, i.e., if the item is NaN, Infinity, or -Infinity.
+ */
+export function assertFiniteNumber(item: unknown): asserts item is number {
     if (!import.meta.env.DEV) return;
-    if (typeof obj !== "number") throw new AssertionError(`Provided object was not of type number. Was: ${typeof obj}`);
-    if (!isFinite(obj)) throw new AssertionError(`Provided number was not finite. Was: ${obj}`);
+    if (typeof item !== "number")
+        throw new AssertionError(
+            `Provided item was not of type number. Was: ${getTypeNameOfUnknown(item)}`
+        );
+    if (!isFinite(item)) throw new AssertionError(`Provided number was not finite. Was: ${item}`);
 }