assertie 0.3.2 → 1.0.0

package/test/runtime/testing.ts

@@ -0,0 +1,168 @@
+import { inspect } from "node:util";
+import type { InspectOptions } from "node:util";
+import { AssertieError } from "../../src/index";
+
+// For grouping and executing a test case
+type GroupingClosure = () => void;
+
+type TestCase = {
+    name: string;
+    groups: string[];
+    closure: GroupingClosure;
+};
+
+const GROUP_STACK: string[] = [];
+const TESTS: TestCase[] = [];
+const INSPECT_OPTIONS: InspectOptions = { depth: 4, colors: false };
+
+class TestFailure extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = TestFailure.name;
+    }
+}
+
+function fail(message: string): never {
+    throw new TestFailure(message);
+}
+
+function limitStack(stackStr: string): string {
+    const lines = stackStr.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        // lines below this are noise from the POV of figuring out the test failure
+        if (lines[i].includes("Object.closure")) {
+            return lines.slice(0, i+1).join("\n");
+        }
+    }
+    return stackStr;
+}
+
+/**
+ * Groups related runtime tests under a shared name.
+ * @param {string} name - The name of the group.
+ * @param {GroupingClosure} closure - The closure that registers nested groups and tests.
+ */
+export function group(name: string, closure: GroupingClosure): void {
+    if (name.includes("SKIP")) return;
+    GROUP_STACK.push(name);
+    try {
+        closure();
+    } finally {
+        GROUP_STACK.pop();
+    }
+}
+
+/**
+ * Registers a runtime test case.
+ * @param {string} name - The name of the test.
+ * @param {GroupingClosure} closure - The closure that executes the test assertions.
+ */
+export function test(name: string, closure: GroupingClosure): void {
+    if (name.includes("SKIP")) return;
+    TESTS.push({
+        name,
+        groups: [...GROUP_STACK],
+        closure,
+    });
+}
+
+/**
+ * Asserts that the provided closure does not throw.
+ * @param {TestFn} fn - The closure that should complete without throwing.
+ * @throws {TestFailure} if the closure throws.
+ */
+export function mustNotThrow(fn: () => unknown): void {
+    try {
+        fn();
+    } catch (error: unknown) {
+        fail(`Expected no throw, got: ${inspect(error, INSPECT_OPTIONS)}`);
+    }
+}
+
+/**
+ * Asserts that the provided closure throws an AssertieError.
+ * @param {TestFn} fn - The closure that should throw.
+ * @param {RegExp} matcher - Optional regex that must match the thrown error message.
+ * @throws {TestFailure} if no error is thrown, a non-AssertieError is thrown, or the message does not match.
+ */
+export function mustThrow(fn: () => unknown, matcher?: RegExp): void {
+    try {
+        fn();
+    } catch (error: unknown) {
+        if (!(error instanceof AssertieError)) {
+            fail(`Expected thrown value to be ${AssertieError.name}, got: ${inspect(error, INSPECT_OPTIONS)}`);
+        }
+        if (matcher !== undefined && !matcher.test(error.message)) {
+            fail(`Expected error message to match ${matcher}, got: "${error.message}"`);
+        }
+        return;
+    }
+
+    fail("Expected throw, but function completed successfully");
+}
+
+/**
+ * Asserts that two strings are strictly equal.
+ * @param {string} actual - The actual string value.
+ * @param {string} expected - The expected string value.
+ * @throws {TestFailure} if the values are not equal.
+ */
+export function mustEqual(actual: string, expected: string): void {
+    if (actual !== expected) {
+        fail(`Expected "${expected}", got "${actual}"`);
+    }
+}
+
+/**
+ * Asserts that the provided boolean is true.
+ * @param {boolean} value - The boolean value to assert.
+ * @throws {TestFailure} if the value is false.
+ */
+export function mustBeTrue(value: boolean): void {
+    if (!value) {
+        fail("Expected true, got false");
+    }
+}
+
+/**
+ * Asserts that the provided boolean is false.
+ * @param {boolean} value - The boolean value to assert.
+ * @throws {TestFailure} if the value is true.
+ */
+export function mustBeFalse(value: boolean): void {
+    if (value) {
+        fail("Expected false, got true");
+    }
+}
+
+/**
+ * Executes all registered runtime tests and prints pass/fail output.
+ */
+export function executeTests(): void {
+    let passed = 0;
+    let failed = 0;
+
+    for (const testCase of TESTS) {
+        const name = [...testCase.groups, testCase.name].join(" > ");
+        try {
+            testCase.closure();
+            ++passed;
+            console.log(`PASS ${name}`);
+        } catch (error: unknown) {
+            ++failed;
+            console.error(`\nFAIL ${name}`);
+            if (error instanceof Error && error.stack !== undefined) {
+                console.error(`    ${limitStack(error.stack)}\n`);
+            } else {
+                console.error(`    ${inspect(error, INSPECT_OPTIONS)}\n`);
+            }
+        }
+    }
+
+    const total = passed + failed;
+    console.log(`\nRuntime tests finished: ${passed}/${total} passed, ${failed} failed\n`);
+
+    if (failed > 0) {
+        process.exitCode = 1;
+    }
+}

package/test/runtime/tsconfig.json

@@ -0,0 +1,18 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "strict": true,
+        "moduleResolution": "node",
+        "noEmit": true,
+        "types": ["node", "vite/client"],
+        "skipLibCheck": true
+    },
+    "include": [
+        "../../src/index.ts",
+        "./testing.ts",
+        "./asserts.test.ts",
+        "./assert-helpers.test.ts",
+        "./main.ts"
+    ]
+}

package/test/types/readonly.5+.test.ts

@@ -0,0 +1,44 @@
+import {
+    assertArrayType,
+    assertTupleTypes,
+    assertArrayNonNullable,
+    assertTupleNonNullable,
+    assertPropsNonNullable,
+    assertIsTuple,
+    assertTypeOfObject,
+    assertNonNullable,
+    assertTypeOfFunction,
+    assertType,
+} from "../../src/index";
+
+/* ==================== assertType ==================== */
+
+{ // Preserves function signature readonly obj parameters on union after narrowing
+    function fn(obj: { readonly a: string }): { readonly b: string, c: string } {
+        return { b: obj.a, c: obj.a };
+    }
+    type Fn = typeof fn;
+    const union: Fn | string = fn as Fn | string;
+    assertType(union, "function");
+    const rdonly: { readonly a: string } = { a: "test" };
+    const res = union(rdonly);
+    // @ts-expect-error
+    res.b = "new";
+    res.c = "new";
+}
+
+/* ==================== assertTypeOfFunction ==================== */
+
+{ // Preserves readonly obj parameters on union after narrowing
+    function fn(obj: { readonly a: string }): { readonly b: string, c: string } {
+        return { b: obj.a, c: obj.a };
+    }
+    type Fn = typeof fn;
+    const union: Fn | string = fn as Fn | string;
+    assertTypeOfFunction(union);
+    const rdonly: { readonly a: string } = { a: "test" };
+    const res = union(rdonly);
+    // @ts-expect-error
+    res.b = "new";
+    res.c = "new";
+}

package/test/types/readonly.test.ts

@@ -0,0 +1,238 @@
+import {
+    assertArrayType,
+    assertTupleTypes,
+    assertArrayNonNullable,
+    assertTupleNonNullable,
+    assertPropsNonNullable,
+    assertIsTuple,
+    assertTypeOfObject,
+    assertNonNullable,
+    assertTypeOfFunction,
+    assertType,
+} from "../../src/index";
+
+/* ==================== assertType ==================== */
+
+{ // Preserves function signature readonly array on union after narrowing
+    function fn(numbers: readonly number[]): readonly number[] {
+        return [...numbers];
+    }
+    type Fn = typeof fn;
+    const union: Fn | string = fn as Fn | string;
+    assertType(union, "function");
+    const rdonly: readonly number[] = [1, 2];
+    const res = union(rdonly);
+    // @ts-expect-error
+    res[0] = 3;
+}
+{ // Preserves object readonly properties on union after narrowing
+    let obj: { readonly a: string } | string = { a: "test" } as { readonly a: string } | string;
+    assertType(obj, "object");
+    // @ts-expect-error
+    obj.a = "new";
+}
+{ // Preserves readonly array after narrowing
+    const arr: readonly number[] | string = [1, 2] as readonly number[] | string;
+    assertType(arr, "object");
+    // @ts-expect-error
+    arr.push(3);
+    // @ts-expect-error
+    arr[0] = 4;
+}
+
+/* ==================== assertArrayType ==================== */
+
+{ // Preserves readonly when narrowing elements
+    const arr: readonly (string | number)[] = ["a", "b"] as readonly (string | number)[];
+    // @ts-expect-error
+    let _string: string = arr[0];
+    assertArrayType(arr, "string");
+    // read access ok after narrowing
+    _string = arr[0];
+    // @ts-expect-error
+    arr.push("c");
+    // @ts-expect-error
+    arr[0] = "d";
+}
+{ // Preserves mutability when narrowing elements
+    const arr: (string | number)[] = ["a", "b"] as (string | number)[];
+    assertArrayType(arr, "string");
+    arr.push("c");
+    arr[0] = "d";
+    // @ts-expect-error
+    arr.push(1);
+}
+{ // Narrows readonly unknown[] to readonly T[]
+    const arr: readonly unknown[] = ["a", "b"] as readonly unknown[];
+    // @ts-expect-error
+    let _string: string = arr[0];
+    assertArrayType(arr, "string");
+    // read access ok after narrowing
+    _string = arr[0];
+    // @ts-expect-error
+    arr.push("c");
+    // @ts-expect-error
+    arr[0] = "d";
+}
+{ // Narrows mutable unknown[] to mutable T[]
+    const arr: unknown[] = ["a", "b"] as unknown[];
+    assertArrayType(arr, "string");
+    arr.push("c");
+    arr[0] = "d";
+}
+
+/* ==================== assertTupleTypes ==================== */
+
+{ // Preserves readonly when narrowing tuple elements
+    const tuple: readonly [string | number] = ["a"] as readonly [string | number];
+    // @ts-expect-error
+    let _string: string = tuple[0];
+    assertTupleTypes(tuple, ["string"]);
+    // read access ok after narrowing
+    _string = tuple[0];
+    // @ts-expect-error
+    tuple[0] = "b";
+}
+{ // Preserves mutability when narrowing tuple elements
+    const tuple: [string | number] = ["a"] as [string | number];
+    assertTupleTypes(tuple, ["string"]);
+    tuple[0] = "b";
+    // @ts-expect-error
+    tuple[0] = 1;
+}
+{ // Narrows readonly tuple of unknowns
+    const tuple: readonly [unknown, unknown] = ["a", 1] as readonly [unknown, unknown];
+    // @ts-expect-error
+    let number: number = tuple[1];
+    assertTupleTypes(tuple, ["string", "number"]);
+    // read access ok after narrowing
+    number = tuple[1];
+    // @ts-expect-error
+    tuple[1] = 2;
+}
+{ // Narrows mutable tuple of unknowns
+    const tuple: [unknown, unknown] = ["a", 1] as [unknown, unknown];
+    assertTupleTypes(tuple, ["string", "number"]);
+    tuple[0] = "b";
+    tuple[1] = 2;
+}
+
+/* ==================== assertTypeOfFunction ==================== */
+
+{ // Preserves readonly array on union after narrowing
+    function fn(numbers: readonly number[]): readonly number[] {
+        return [...numbers];
+    }
+    type Fn = typeof fn;
+    const union: Fn | string = fn as Fn | string;
+    assertTypeOfFunction(union);
+    const rdonly: readonly number[] = [1, 2];
+    const res = union(rdonly);
+    // @ts-expect-error
+    res[0] = 3;
+}
+
+/* ==================== assertArrayNonNullable ==================== */
+
+{ // Preserves readonly when removing nulls
+    const arr: readonly (string | null)[] = ["a"] as readonly (string | null)[];
+    // @ts-expect-error
+    let _string: string = arr[0];
+    assertArrayNonNullable(arr);
+    // read access ok after narrowing
+    _string = arr[0];
+    // @ts-expect-error
+    arr.push("b");
+    // @ts-expect-error
+    arr[0] = "c";
+}
+{ // Preserves mutability when removing nulls
+    const arr: (string | null)[] = ["a"] as (string | null)[];
+    assertArrayNonNullable(arr);
+    arr.push("b");
+    arr[0] = "c";
+}
+
+/* ==================== assertTupleNonNullable ==================== */
+
+{ // Preserves readonly when removing nulls from tuple
+    const tuple: readonly [string | null, number | undefined] = ["a", 1] as readonly [string | null, number | undefined];
+    // @ts-expect-error
+    let _string: string = tuple[0];
+    assertTupleNonNullable(tuple);
+    // read access ok after narrowing
+    _string = tuple[0];
+    // @ts-expect-error
+    tuple[0] = "b";
+}
+{ // Preserves mutability when removing nulls from tuple
+    const tuple: [string | null, number | undefined] = ["a", 1] as [string | null, number | undefined];
+    assertTupleNonNullable(tuple);
+    tuple[0] = "b";
+    tuple[1] = 2;
+}
+
+/* ==================== assertPropsNonNullable ==================== */
+
+{ // Preserves readonly on properties
+    const obj: { readonly a?: string; b: number | null } = { a: "test", b: 1 } as { readonly a?: string; b: number  | null};
+    // @ts-expect-error
+    let _string: string = obj.a;
+    assertPropsNonNullable(obj, ["a", "b"]);
+    // read access ok after narrowing
+    _string = obj.a;
+    // @ts-expect-error
+    obj.a = "new";
+    // other property not readonly
+    obj.b = 2;
+}
+
+/* ==================== assertIsTuple ==================== */
+
+{ // Preserves readonly on array narrowing to tuple
+    const arr: readonly number[] = [1, 2] as readonly number[];
+    assertIsTuple(arr, 2);
+    // read access ok after narrowing
+    arr[0];
+    // @ts-expect-error
+    arr[2]; // ensure it did actually narrow
+    // @ts-expect-error
+    arr[0] = 3; // ensure it's still readonly
+}
+{ // Preserves mutability on array narrowing to tuple
+    const arr: number[] = [1, 2] as number[];
+    assertIsTuple(arr, 2);
+    // @ts-expect-error
+    arr[2]; // ensure it did actually narrow
+    arr[0] = 3; // ensure it's mutable
+}
+
+/* ==================== assertTypeOfObject ==================== */
+
+{ // Preserves readonly properties in union narrowing
+    const obj: { readonly x: string; y: number } | string = { x: "a", y: 1 } as { readonly x: string; y: number } | string;
+    assertTypeOfObject(obj);
+    // @ts-expect-error
+    obj.x = "b";
+    obj.y = 2;
+}
+
+/* ==================== assertNonNullable ==================== */
+
+{ // Preserves readonly on array union
+    const arr: readonly number[] | null = [1, 2] as readonly number[] | null;
+    // @ts-expect-error
+    let _number: number = arr[0];
+    assertNonNullable(arr);
+    _number = arr[0];
+    // @ts-expect-error
+    arr.push(3);
+    // @ts-expect-error
+    arr[0] = 4;
+}
+{ // Preserves mutability on array union
+    const arr: number[] | null = [1, 2] as number[] | null;
+    assertNonNullable(arr);
+    arr.push(3);
+    arr[0] = 4;
+}

package/test/types/run.ts

@@ -0,0 +1,29 @@
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+import typescript from 'typescript';
+
+function atLeast(versionMajorMinor: `${number}.${number}`, major: number, minor?: number): boolean {
+  const [verMajor, verMinor] = versionMajorMinor.split('.').map(Number);
+  return verMajor > major || (verMajor === major && (minor === undefined || verMinor >= minor));
+}
+
+const atLeast5 = atLeast(typescript.versionMajorMinor, 5);
+if (!atLeast5) {
+  console.log(`TypeScript < 5.0 detected, skipping incompatible type tests.`);
+}
+const tsconfigPath = atLeast5
+  ? 'test/types/tsconfig.json'
+  : 'test/types/tsconfig.4.x.json';
+console.log(`Running tests based on ${tsconfigPath}`);
+
+const require = createRequire(import.meta.url);
+const tscPath = require.resolve('typescript/lib/tsc.js');
+const result = spawnSync(process.execPath, [tscPath, '-p', tsconfigPath], { stdio: 'inherit' });
+
+console.log((result.status === 0) ? 'TypeScript tests passed!' : 'TypeScript tests failed!');
+if (result.error) {
+  throw result.error;
+}
+
+process.exit(result.status ?? 1);

package/test/types/tsconfig.4.x.json

@@ -0,0 +1,7 @@
+{
+    "extends": "./tsconfig.json",
+    "exclude": [
+        "./type-narrowing.5+.test.ts",
+        "./readonly.5+.test.ts",
+    ],
+}

package/test/types/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+      "target": "ESNext",
+      "module": "ESNext",
+      "strict": true,
+      "moduleResolution": "node",
+      "noEmit": true,
+      "types": ["vite/client"],
+      "skipLibCheck": true
+  },
+  "include": [
+    "../../src/index.ts",
+    "./type-narrowing.test.ts",
+    "./type-narrowing.5+.test.ts",
+    "./readonly.test.ts",
+    "./readonly.5+.test.ts",
+  ],
+}

package/test/types/type-narrowing.5+.test.ts

@@ -0,0 +1,32 @@
+// Tests for improved type narrowing in TypeScript 5.0+ only
+import { assertType, assertTypeOfFunction } from "../../src/index";
+
+{ // assertType narrows union to specific function
+    type X = string | ((arg: string) => string);
+    const x: X = ((arg: string) => arg) as X;
+    // @ts-expect-error
+    let _res: string = x("test");
+    assertType(x, "function");
+    _res = x("test");
+
+    // @ts-expect-error
+    x(123);
+    // These don't error on TypeScript < 5.0
+    // because it only narrows unions to () => {} or (args: any[]) => {}
+    // @ts-expect-error
+    const _res2: number = x("test");
+}
+
+{ // assertTypeOfFunction narrows union to specific function
+    type X = string | ((arg: string) => string);
+    const x: X = ((arg: string) => arg) as X;
+    // @ts-expect-error
+    let _res: string = x("test");
+    assertTypeOfFunction(x);
+    _res = x("test");
+
+    // @ts-expect-error
+    x(123);
+    // @ts-expect-error
+    const _res2: number = x("test");
+}