assertie 0.3.2 → 1.0.0

package/CHANGELOG.md

@@ -1,8 +1,31 @@
 # Changelog
 
+## [1.0.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.3.2...v1.0.0) (2026-02-15)
+
+### Breaking Changes
+
+* [`a04c1be`](https://github.com/OfficialHalfwayDead/assertie/commit/a04c1be1f86d6280ce925dff8c5b0fdef6811660) Rename AssertionError to AssertieError to reduce the likelihood of name conflicts.
+* [`e91af47`](https://github.com/OfficialHalfwayDead/assertie/commit/e91af47062b6255dd415b5fcbbd6768ac836beb4) Changed the type that functions get narrowed to, so that they return `unknown` when called instead of `any`. This only affects cases where the TypeScript has no other way of inferring the true return type.
+
+### Features
+
+* [`2c021d7`](https://github.com/OfficialHalfwayDead/assertie/commit/2c021d7796e1d1e1663f0149d3ada35d9f0b744d) Enable passing abstract classes to `assertType` and `assertInstanceOf`.
+* [`f307a3f`](https://github.com/OfficialHalfwayDead/assertie/commit/f307a3f28fe8dbb9b2f992578fda796006839dd3) Improve `assertIsTuple` narrowing. The narrowed type now results in TypeScript errors when trying to read/write to an index higher than the asserted tuple length.
+* [`d76b312`](https://github.com/OfficialHalfwayDead/assertie/commit/d76b31211e0e5e91673a3d2ac84b2088ba00d89d) Allow passing readonly arrays and tuples and preserve their readonlyness. Objects with readonly params were already working.
+
+### Other
+
+* [`2a91906`](https://github.com/OfficialHalfwayDead/assertie/commit/2a9190653f6c32efca5a5abf7e951e0635608f30) Add runtime tests for all assertion functions and internal helpers.
+* [`e91af47`](https://github.com/OfficialHalfwayDead/assertie/commit/e91af47062b6255dd415b5fcbbd6768ac836beb4) Add type tests for the type narrowing of assertions.
+* [`b24849e`](https://github.com/OfficialHalfwayDead/assertie/commit/b24849eeb9bc6db291d95212b3cfa736d2136c3d) Bugfix: Internal functions getTypeNameOfUnknown and isType
+  * Fix issues where getTypeNameOfUnknown returns an underspecified or
+  unexpected type, leading to assertions with poor error messages.
+  * Fix an issue where isType throws instead of returning false, leading to assertions throwing an exception of the wrong type with a poor error message.
+* [`7c8ffd3`](https://github.com/OfficialHalfwayDead/assertie/commit/7c8ffd33771e38f9f8fe95e4bff62a3f96edd0df) Improve Svelte pitfalls explanation in README.
+
 ## [0.3.2](https://github.com/OfficialHalfwayDead/assertie/compare/v0.3.1...v0.3.2) (2025-02-27)
 
-* [`0814dd2`](https://github.com/OfficialHalfwayDead/assertie/commit/0814dd2a6b9daf2bbeb99e2925710cc8a76caf07) Bugfix: Constructor type wasn't properly typed and prevent `assertInstanceOf` and `assertType` from accepting many construcable types.
+* [`0814dd2`](https://github.com/OfficialHalfwayDead/assertie/commit/0814dd2a6b9daf2bbeb99e2925710cc8a76caf07) Bugfix: Constructor type wasn't properly typed and prevented `assertInstanceOf` and `assertType` from accepting many constructible types.
 * [`940e4e4`](https://github.com/OfficialHalfwayDead/assertie/commit/940e4e424c14db20734ed4e2ec2b8a6eeae3aef3) Clarify SSR vite settings and Svelte/Proxy pitfalls in the README.
 
 

package/MIGRATION-GUIDE.md

@@ -2,6 +2,19 @@
 
 Scroll down to your previous version and then follow all the steps upwards in order until the version you're targeting.
 
+## [0.3.x to 1.0.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.3.2...v1.0.0)
+
+* When narrowing a complete unknown to a function, the type has changed so that when called, the function returns `unknown` when called instead of `any`. 
+  ```ts
+  const fn = () => 5 as unknown;
+  assertType(fn, "function");
+  fn(); // allowed
+  const res: string = fn(); // no longer valid since unknown can't be assigned to string
+  ```
+  This only affects cases where the TypeScript has no other way of inferring the true return type.
+
+* If you were relying on the name/type of the error thrown by the assertions, it has been changed from `AssertionError` to `AssertieError` to prevent name conflicts.
+
 ## [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)

package/README.md

@@ -19,7 +19,7 @@ if (original === null) return;
 const clone = original.cloneNode(true);
 assertInstanceOf(clone, HTMLElement);
 // Unlike casting, the assert will throw if you were mistaken,
-// or if someone accidentally changed const original = document;
+// or if someone changes const original = document;
 clone.innerText = "No `as` cast needed! 0 overhead in production.";
 ```
 
@@ -48,7 +48,7 @@ const config: UserConfig = {
 
 If you're getting errors when using the package, it's likely because your TypeScript targets are too low:
 
-```json
+```jsonc
 // tsconfig.json
 {
     "compilerOptions": {
@@ -135,7 +135,7 @@ f();
 
 There are multiple advantages to using an assertion in this case:
 
-It clarifies the code's intent. f was never meant to conditionally execute its body. It is always supposed to work, but the if statement was required to satisfy the compiler.
+1. It clarifies the code's intent. f was never meant to conditionally execute its body. It is always supposed to work, but the if statement was required to satisfy the compiler.
 2. The assert will throw an error in dev if the case that should never happen does happen. Without the assert, any potential behavior change due to `hoisted` not being set is more likely to go unnoticed.
 3. It's a little shorter, mainly if you have to check null and undefined and maybe have prettier rules for { brackets } on if statements.
 4. The assert will be removed in production, so there's no overhead. If that makes you uncomfortable, you can just can still put the if statement below the assert and reap the benefits of the first two points.
@@ -253,11 +253,23 @@ assert(/* @__PURE__ */ object.foo() === "yup");
 
 ### Svelte
 
-Accessing the value of a rune `x` compiles to `get(x)`, leading to the same pitfall as above. To prevent this, you need to treat the rune like a function:
+Runes in Svelte are, in reality, proxy objects, with those details hidden from the user by the compiler. Accessing `x` compiles to `get(x)`, which leads to the same pitfall as above. The cleanest solution is to create a local copy when possible:
 
 ```ts
 let rune = $state(1);
-let otherRune = $state(1);
 
-assert(/*@__PURE__*/ rune === /*@__PURE__*/ otherRune);
+// ... local context
+const lcopy = $state.snapshot(rune); // stays
+assertType(lcopy, "string"); // removed by vite in prod
+// only lcopy gets type narrowing, not rune
 ```
+
+Be aware that, by definition, the snapshot is a regular object, and therefore will not be reactive.
+
+In theory, you can also cheat by marking the rune as a pure function when accessing it:
+
+```ts
+assertType(/* @__PURE__ */ rune, "string"); // dangerous
+```
+
+Even with side-effect-free getters, this usage can cause diverging behavior between dev and prod if the Svelte compiler is in a tracking context such as `$effect()`. If you intend to use it this way, you should be absolutely certain that you understand the details of Svelte's behavior.

package/lib/assert-helpers.d.ts

@@ -0,0 +1,20 @@
+import { AllJSTypes, ResolveAnyJSType } from "./types";
+/**
+ * Gets the display name of an expected type for error messages.
+ * @param {AllJSTypes} expectedType - The expected type value.
+ * @returns {string} The normalized name of the expected type.
+ */
+export declare function getNameOfExpectedType(expectedType: AllJSTypes): string;
+/**
+ * Gets the runtime type name of an unknown item for error messages.
+ * @param {unknown} item - The item whose runtime type name should be determined.
+ * @returns {string} The runtime type name of item.
+ */
+export declare function getTypeNameOfUnknown(item: unknown): string;
+/**
+ * Checks whether the provided item is of the expectedType.
+ * @param {unknown} item - The item to check.
+ * @param {AllJSTypes} expectedType - The expected type to check against.
+ * @returns {boolean} `true` if item's type matches expectedType.
+ */
+export declare function isType<T extends AllJSTypes>(item: unknown, expectedType: T): item is ResolveAnyJSType<T>;

package/lib/assert-helpers.js

@@ -0,0 +1,66 @@
+/**
+ * Gets the display name of an expected type for error messages.
+ * @param {AllJSTypes} expectedType - The expected type value.
+ * @returns {string} The normalized name of the expected type.
+ */
+export function getNameOfExpectedType(expectedType) {
+    if (expectedType === null)
+        return "null";
+    if (expectedType === undefined)
+        return "undefined";
+    if (typeof expectedType === "string")
+        return expectedType;
+    return expectedType.name;
+}
+/**
+ * Gets the runtime type name of an unknown item for error messages.
+ * @param {unknown} item - The item whose runtime type name should be determined.
+ * @returns {string} The runtime type name of item.
+ */
+export function getTypeNameOfUnknown(item) {
+    if (item === null)
+        return "null";
+    const type = typeof item;
+    switch (type) {
+        case "object":
+        case "function":
+            try {
+                const unsafe = item; // We are using try catch for the fail cases
+                if (unsafe instanceof unsafe.constructor) {
+                    return unsafe.constructor.name;
+                }
+            }
+            catch {
+            }
+            const typeStr = Object.prototype.toString.call(item);
+            return typeStr.slice(8, -1); // "[object Type]" -> "Type"
+        default:
+            return type;
+    }
+}
+/**
+ * Checks whether the provided item is of the expectedType.
+ * @param {unknown} item - The item to check.
+ * @param {AllJSTypes} expectedType - The expected type to check against.
+ * @returns {boolean} `true` if item's type matches expectedType.
+ */
+export function isType(item, expectedType) {
+    if (typeof item === expectedType)
+        return true; // correct primitive type
+    // Now, if the expectedType is a PrimitiveTypeString,
+    // the item is guaranteed to be of the wrong type since it didn't match the typeof check above
+    if (typeof expectedType === "string")
+        return false;
+    const expectedUndefNullOrConstructor = expectedType;
+    // The type restriction on T guarantees that item is now either undefined, null, or a constructor
+    if (item === expectedUndefNullOrConstructor)
+        return true; // correct undefined, null, or constructor of itself
+    // i.e. const MyType = Date; isType(Date, Date) && isType(MyType, Date) are both true
+    if (expectedUndefNullOrConstructor === null || expectedUndefNullOrConstructor === undefined)
+        return false;
+    const expectedConstructor = expectedType;
+    // Lastly, check if the item is an instance of the provided constructor
+    if (item instanceof expectedConstructor)
+        return true;
+    return false;
+}

package/lib/index.d.ts

@@ -1,162 +1,155 @@
-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;
-    "bigint": bigint;
-    "undefined": undefined;
-    "function": Function;
-    "object": object;
-    "symbol": symbol;
-};
-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];
-declare type PropsNonNullable<T, N extends NullableKeys<T>> = T & {
-    [K in N]-?: NonNullable<T[K]>;
-};
-declare type Constructor<T> = new (...args: any[]) => 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;
+import type { UnknownFunction, Constructor, PrimitiveTypes, PrimitiveTypeStrings, NullableKeys, PropsNonNullable, AllJSTypes, ResolveAnyJSType, ResolveTuple, ResolveReadonlyTuple, Tuple, ReadonlyTuple } from "./types";
+export type { PrimitiveTypes, PrimitiveTypeStrings, NullableKeys, PropsNonNullable, AllJSTypes, ResolveAnyJSType, ResolveTuple, ResolveReadonlyTuple, Tuple, ReadonlyTuple };
+/**
+ * Error thrown by all assertie assertions when they fail.
+ */
+export declare class AssertieError extends Error {
+    constructor(msg: string);
+}
 /**
  * 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.
+ * @throws {AssertieError} if the assertion fails.
  */
 export declare function assert(hasToBeTrue: boolean, msg?: string): asserts hasToBeTrue is true;
 /**
- * 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.
+ * Asserts that the provided item is of the expectedType.
+ * @param {unknown} item - The item which ought to be of the expectedType.
+ * @param {AllJSTypes} expectedType - The expected type of the item. 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 {AssertieError} 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[]
+ * Asserts that all elements of the provided array are of the expected type. It ensures that the array is not sparse up to arr.length (even when the expectedType is undefined).
+ * @param {unknown[]} arr - The array which ought to be an array of the expectedType, i.e. expectedType: "number" means `arr: number[]`. Preserves readonly when specified.
  * @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.
+ * @throws {AssertieError} if the type isn't as expected.
  */
 export declare function assertArrayType<T extends AllJSTypes>(arr: unknown[], expectedType: T): asserts arr is ResolveAnyJSType<T>[];
+export declare function assertArrayType<T extends AllJSTypes>(arr: readonly unknown[], expectedType: T): asserts arr is readonly 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.
+ * @param {unknown[] | [unknown, ...]} arrayOrTuple - The tuple which ought to be an array of the expected length and types. Preserves readonly when specified.
+ * @param {[AllJSTypes, ...]} expectedTypes - A tuple of expected types of individual items, e.g., `expectedTypes = ["number", "string", Date]` means `arrayOrTuple: [number, string, Date]`. The individual entries can be JS primitive types, null, undefined, and constructors.
+ * @throws {AssertieError} 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]>;
-};
+} | (number extends U["length"] ? unknown[] : never)>(arrayOrTuple: U, expectedTypes: readonly [...T]): asserts arrayOrTuple is ResolveTuple<T, U>;
+export declare function assertTupleTypes<T extends readonly AllJSTypes[], U extends {
+    readonly [K in keyof T]: unknown;
+} | (number extends U["length"] ? readonly unknown[] : never)>(arrayOrTuple: U, expectedTypes: readonly [...T]): asserts arrayOrTuple is ResolveReadonlyTuple<T, U>;
 /**
  * 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} if the type isn't function.
  */
-export declare function assertTypeOfFunction(item: unknown): asserts item is Function;
+export declare function assertTypeOfFunction(item: unknown): asserts item is UnknownFunction;
 /**
  * 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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>;
+export declare function assertIsTuple<T, N extends number>(arr: T[], expectedLength: N): asserts arr is Tuple<T, N>;
+export declare function assertIsTuple<T, N extends number>(arr: readonly T[], expectedLength: N): asserts arr is ReadonlyTuple<T, 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @throws {AssertieError} 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.
+ * @param {unknown[]} arr - The array which ought to be non-sparse, and have only non-null elements. Preserves readonly when specified.
+ * @throws {AssertieError} 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>[];
+export declare function assertArrayNonNullable<T>(arr: readonly T[]): asserts arr is readonly 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.
+ * @throws {AssertieError} 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]>;
 };
+export declare function assertTupleNonNullable<T extends number extends T["length"] ? never : readonly 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.
+ * @throws {AssertieError} 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 {};