assertie 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OfficialHalfwayDead
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# assertie
+
+Debug assertions for TypeScript, auto tree-shaken by vite for production.
+
+Why? Because asserts are simple to read and safer than casting. Use them when you know something is guaranteed to be true, and assertie will make sure it is in dev builds. As programmers, we sometimes make wrong assumptions.
+
+```ts
+import { assertInstanceOf } from "assertie";
+...
+const original = document.getElementById("probably-mounted");
+if (original === null) return; // This isn't the place for an assert because the element isn't guaranteed to be present.
+const clone = original.cloneNode(true); // returns type Node but we know it'll always be an HTMLElement
+assertInstanceOf(clone, HTMLElement);
+clone.innerText = "No `as` cast needed! 0 overhead in production.";
+```
+
+## Installation
+
+```bash
+npm i -D assertie
+```
+
+If you're getting errors when using the package, it's likely because your TypeScript targets are too low:
+
+```json
+// tsconfig.json
+{
+    "compilerOptions": {
+        "target": "ES6", // minimum
+        "module": "ES2020", // minimum
+        "types": ["vite/client"] // may be needed depending on your setup
+    }
+}
+```
+
+By default, vite will tree-shake the functions for production, but make sure you haven't specifically disabled it in your vite config:
+
+```ts
+// vite.config.ts
+const config: UserConfig = {
+    build: {
+        rollupOptions: {
+            treeshake: true,
+        },
+    },
+};
+```
+
+## Usage
+
+### Basic assert
+
+```ts
+import { assert } from "assertie";
+
+assert(typeof "yup" === "string", "optional text if assertion fails");
+
+// You get type narrowing from assertie's assertions
+const x: boolean = true;
+assert(x);
+const y: true = x; // no error
+```
+
+### Type assertion
+
+```ts
+import { assertType } from "assertie";
+
+// assertType can take any primitive JS type string (e.g., "number", "string"), null, undefined, or a class/constructable
+assertType(1, "number");
+assertType(() => {}, "function");
+assertType(undefined, "undefined");
+assertType(undefined, undefined);
+assertType(null, null);
+assertType(new Date(), Date);
+
+// Use type assertions to replace all your type casts
+const value: unknown = "yup";
+const bad: string = value as string;
+assertType(value, "string");
+const good: string = value; // no `as` needed
+```
+
+You don't need to use strings to narrow primitives. There are specific functions for specific types if you prefer that.
+
+```ts
+assertTypeofString("yup");
+assertTypeofNumber(123);
+assertTypeofBoolean(true);
+assertTypeofBigint(123n);
+assertTypeofUndefined(undefined);
+assertTypeofFunction(() => {});
+assertTypeofObject({});
+assertTypeofSymbol(Symbol("yup"));
+assertInstanceOf(new Date(), Date);
+```
+
+### Asserting non-null
+
+Sometimes you'll find yourself in a situation where you know from the calling context that a hoisted variable is not `null` or `undefined`, but TypeScript doesn't.
+
+```ts
+let hoisted: string | null | undefined = null;
+
+const f =  () => {
+    assertNonNullable(hoisted);
+    // vs.
+    if (hoisted === null || hoisted === undefined) return;
+
+    console.log(hoisted.toUpperCase());
+};
+
+hoisted = "yup";
+f();
+```
+
+There are multiple ways in which an assert is better in this specific case:
+
+1. Making the code intention clear. Your function was never meant to only run some of the time. It is always supposed to work. You only added the if statement to make the compiler happy.
+2. The assert will throw an error in dev if the case that should never happen does happen. Without an error, it would be easy to change how the hoisted variable is set, and the potential behavior change 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 leave both in.
+
+```ts
+// Sometimes not your entire object is null
+const obj: {
+    a?: string,
+    b: string,
+    c: number | null
+} = {
+    a: "yeah",
+    b: "yup",
+    c: 123,
+};
+// Pass an array of all keys to check
+assertPropsNonNullable(obj, ["a", "c"]);
+const safeObj = obj;
+// typeof safeObj === { a: string, b: string, c: number }
+```
+
+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, it will remain undefined/null after the assert.
+
+### Asserting unreachable code
+
+The unreachable assertion can both help you ensure that switch/if statements are exhaustive at compile time and throw at runtime if the TypeScript types were inaccurate somewhere.
+
+```ts
+const x: "a" | "b" = "a";
+
+switch (x) {
+    case "a":
+        break;
+    case "b":
+        break;
+    default:
+        assertUnreachable(x);
+}
+```
+
+If you were to extend `x`'s type to include `"c"`, TypeScript would not compile anymore because `assertUnreachable` only accepts values of type `never`, but the type in the default case would be `"c"`.
+
+### Other utils
+
+For now, there is only one:
+
+```ts
+assertFiniteNumber(123);
+// Ensures passed value is typeof number and finite
+// 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 JavaScript's loose equality (`123 == "123"`).

package/lib/index.d.ts

@@ -0,0 +1,36 @@
+type PrimitiveTypeStrings = "string" | "number" | "boolean" | "bigint" | "undefined" | "function" | "object" | "symbol";
+type PrimitiveTypes = {
+    "string": string;
+    "number": number;
+    "boolean": boolean;
+    "bigint": bigint;
+    "undefined": undefined;
+    "function": Function;
+    "object": object;
+    "symbol": symbol;
+};
+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 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;
+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 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;
+export {};

package/lib/index.js

@@ -0,0 +1,107 @@
+class AssertionError extends Error {
+    constructor(msg) {
+        super(`Assertion failed: ${msg}`);
+        this.name = AssertionError.name;
+    }
+}
+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) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj === expectedType)
+        return;
+    const reducedExpectedType = expectedType;
+    if (obj === reducedExpectedType)
+        return;
+    const remainingOption = expectedType;
+    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}`);
+}
+export function assertTypeofString(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "string")
+        throw new AssertionError(`Provided object was not of type string. Was: ${typeof obj}`);
+}
+export function assertTypeofNumber(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "number")
+        throw new AssertionError(`Provided object was not of type number. Was: ${typeof obj}`);
+}
+export function assertTypeofBoolean(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "boolean")
+        throw new AssertionError(`Provided object was not of type boolean. Was: ${typeof obj}`);
+}
+export function assertTypeofBigint(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "bigint")
+        throw new AssertionError(`Provided object was not of type bigint. Was: ${typeof obj}`);
+}
+export function assertTypeofUndefined(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "undefined")
+        throw new AssertionError(`Provided object was not of type undefined. Was: ${typeof obj}`);
+}
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function assertTypeofFunction(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "function")
+        throw new AssertionError(`Provided object was not of type function. Was: ${typeof obj}`);
+}
+export function assertTypeofObject(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "object")
+        throw new AssertionError(`Provided object was not of type object. Was: ${typeof obj}`);
+}
+export function assertTypeofSymbol(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (typeof obj !== "symbol")
+        throw new AssertionError(`Provided object was not of type symbol. Was: ${typeof obj}`);
+}
+export function assertInstanceOf(obj, constructable) {
+    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}`);
+}
+export function assertUnreachable(obj, msg = "Unreachable code of type never was reached. TypeScript types are inaccurate somewhere.") {
+    if (!import.meta.env.DEV)
+        return;
+    throw new AssertionError(msg);
+}
+export function assertPropsNonNullable(obj, props) {
+    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]}`);
+    }
+}
+export function assertNonNullable(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (obj === undefined || obj === null)
+        throw new AssertionError(`Provided object should've been non-null but was: ${obj}`);
+}
+export function assertFiniteNumber(obj) {
+    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}`);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "assertie",
+  "version": "0.1.0",
+  "description": "Debug assertions for TypeScript, auto tree-shaken by vite for production.",
+  "keywords": [
+    "TypeScript",
+    "vite",
+    "debug",
+    "assert"
+  ],
+  "homepage": "https://github.com/OfficialHalfwayDead/assertie#readme",
+  "bugs": {
+    "url": "https://github.com/OfficialHalfwayDead/assertie/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OfficialHalfwayDead/assertie.git"
+  },
+  "license": "MIT",
+  "author": "halfie",
+  "type": "module",
+  "types": "./lib/index.d.ts",
+  "main": "./lib/index.js",
+  "exports": {
+    "import": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "typescript": ">=3.7.0",
+    "vite": ">=2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vite": "^6.1.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+type PrimitiveTypeStrings = "string" | "number" | "boolean" | "bigint" | "undefined" | "function" | "object" | "symbol";
+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 
+}[keyof T];
+
+type PropsNonNullable<T, N extends NullableKeys<T>> =  T & { [K in N]-?: NonNullable<T[K]> };
+
+class AssertionError extends Error {
+    constructor(msg: string) {
+        super(`Assertion failed: ${msg}`);
+        this.name = AssertionError.name;
+    }
+}
+
+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;
+
+
+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);
+}
+
+export function assertType<T extends AllJSTypes>(obj: unknown, expectedType: T): asserts obj is ResolveAnyJSType<T> {
+    if (!import.meta.env.DEV) return;
+
+    if (typeof obj === expectedType) return;
+    const reducedExpectedType = expectedType as Exclude<typeof expectedType, PrimitiveTypeStrings>;
+
+    if (obj === reducedExpectedType) return;
+    const remainingOption = expectedType as Exclude<typeof reducedExpectedType, null | undefined>;
+
+    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}`);
+}
+
+export function assertTypeofString(obj: unknown): asserts obj is string {
+    if (!import.meta.env.DEV) return;
+    if (typeof obj !== "string") throw new AssertionError(`Provided object was not of type string. Was: ${typeof obj}`);
+}
+
+export function assertTypeofNumber(obj: unknown): asserts obj 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}`);
+}
+
+export function assertTypeofBoolean(obj: unknown): asserts obj is boolean {
+    if (!import.meta.env.DEV) return;
+    if (typeof obj !== "boolean") throw new AssertionError(`Provided object was not of type boolean. Was: ${typeof obj}`);
+}
+
+export function assertTypeofBigint(obj: unknown): asserts obj is bigint {
+    if (!import.meta.env.DEV) return;
+    if (typeof obj !== "bigint") throw new AssertionError(`Provided object was not of type bigint. Was: ${typeof obj}`);
+}
+
+export function assertTypeofUndefined(obj: unknown): asserts obj is undefined {
+    if (!import.meta.env.DEV) return;
+    if (typeof obj !== "undefined") throw new AssertionError(`Provided object was not of type undefined. Was: ${typeof obj}`);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function assertTypeofFunction(obj: unknown): asserts obj is Function {
+    if (!import.meta.env.DEV) return;
+    if (typeof obj !== "function") throw new AssertionError(`Provided object was not of type function. Was: ${typeof obj}`);
+}
+
+export function assertTypeofObject(obj: unknown): asserts obj is object {
+    if (!import.meta.env.DEV) return;
+    if (typeof obj !== "object") throw new AssertionError(`Provided object was not of type object. Was: ${typeof obj}`);
+}
+
+export function assertTypeofSymbol(obj: unknown): asserts obj is symbol {
+    if (!import.meta.env.DEV) return;
+    if (typeof obj !== "symbol") throw new AssertionError(`Provided object was not of type symbol. Was: ${typeof obj}`);
+}
+
+export function assertInstanceOf<T>(obj: unknown, constructable: Constructor<T>): asserts obj is 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}`);
+}
+
+export function assertUnreachable(obj: never, msg: string = "Unreachable code of type never was reached. TypeScript types are inaccurate somewhere."): asserts obj is never {
+    if (!import.meta.env.DEV) return;
+    throw new AssertionError(msg);
+}
+
+export function assertPropsNonNullable<T, N extends NullableKeys<T>>(obj: T, props: N[]): asserts obj is PropsNonNullable<T, N> {
+    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]}`);
+    }
+}
+
+export function assertNonNullable<T>(obj: T): asserts obj is NonNullable<T> {
+    if (!import.meta.env.DEV) return;
+    if (obj === undefined || obj === null) throw new AssertionError(`Provided object should've been non-null but was: ${obj}`);
+}
+
+export function assertFiniteNumber(obj: unknown): asserts obj 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}`);
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "types": ["vite/client"],
+        "outDir": "lib",
+        "declaration": true,
+        "declarationDir": "lib",
+    },
+    "include": ["src/index.ts"],
+}