assertie 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [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.
+* [`940e4e4`](https://github.com/OfficialHalfwayDead/assertie/commit/940e4e424c14db20734ed4e2ec2b8a6eeae3aef3) Clarify SSR vite settings and Svelte/Proxy pitfalls in the README.
+
+
+## [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
@@ -17,6 +28,7 @@
 
 * [`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/README.md

@@ -29,6 +29,23 @@ clone.innerText = "No `as` cast needed! 0 overhead in production.";
 npm i -D assertie
 ```
 
+By default, vite will tree-shake the functions in the frontend, but for SSR it will actually not touch libraries unless you specify that the module should not be externalized.
+
+```ts
+// vite.config.ts
+const config: UserConfig = {
+    build: {
+        ssr: { // crucial if you have SSR
+            noExternal: ["assertie"],
+        },
+        rollupOptions: {
+            treeshake: true, // this is default
+            // just make sure it's not explicitly false
+        },
+    },
+};
+```
+
 If you're getting errors when using the package, it's likely because your TypeScript targets are too low:
 
 ```json
@@ -42,18 +59,6 @@ If you're getting errors when using the package, it's likely because your TypeSc
 }
 ```
 
-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
 
@@ -76,7 +81,7 @@ const y: true = x; // no error
 ```ts
 import { assertType } from "assertie";
 
-// assertType can take null, undefined, a class/constructable 
+// assertType can take null, undefined, a class/constructable,
 // or a primitive JS type string (e.g., "number")
 assertType(1, "number");
 assertType(() => {}, "function");
@@ -109,7 +114,7 @@ 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.
+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;
@@ -128,9 +133,9 @@ hoisted = "yup";
 f();
 ```
 
-There are multiple ways in which an assert is better in this specific case:
+There are multiple advantages to using an assertion in this case:
 
-1. Making the code intention clear. `f` was never meant to only run its body some of the time. It is always supposed to work. But the if statement was required to make the compiler happy.
+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.
@@ -154,12 +159,34 @@ 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 provide excellent error messages 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
 
 1. ensure switch/if statements are exhaustive at compile time.
-2. throw an error at runtime if TypeScript types are inaccurate.
+2. throw an error at runtime if some TypeScript types are inaccurate.
 
 ```ts
 const x: "a" | "b" = "a";
@@ -195,3 +222,42 @@ const num = Number(numStr); // NaN
 assertFiniteNumber(num); // throws
 arr[num] = "yup" // disaster averted
 ```
+
+
+## Pitfalls
+
+While assertions will never throw in production, complete removal of the code may not happen if you call another function inside the assertion call:
+
+```js
+assert(object.foo() === "yup");
+
+// bundler leaves this stub:
+function assert(hasToBeTrue, msg = "No specific message provided.") {
+    return;
+}
+```
+
+Since `foo()` might have side effects, it is not possible to remove the entire line. And it seems, the vite bundler **is not capable** of turning the code into:
+
+```ts
+// stays because of potential side effects
+const assertValue = object.foo() === "yup";
+assert(assertValue); // gets removed now
+```
+
+Therefore, you'll have to do that yourself, or if you know `foo()` is a pure function, you can mark it as such:
+
+```ts
+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:
+
+```ts
+let rune = $state(1);
+let otherRune = $state(1);
+
+assert(/*@__PURE__*/ rune === /*@__PURE__*/ otherRune);
+```

package/lib/index.d.ts

@@ -16,7 +16,7 @@ declare type NullableKeys<T> = {
 declare type PropsNonNullable<T, N extends NullableKeys<T>> = T & {
     [K in N]-?: NonNullable<T[K]>;
 };
-declare type Constructor<T> = new (...args: unknown[]) => T;
+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;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assertie",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Debug assertions for TypeScript, auto tree-shaken by vite for production.",
   "keywords": [
     "TypeScript",

package/src/index.ts

@@ -22,7 +22,7 @@ type PropsNonNullable<T, N extends NullableKeys<T>> = T & {
     [K in N]-?: NonNullable<T[K]>;
 };
 
-type Constructor<T> = new (...args: unknown[]) => T;
+type Constructor<T> = new (...args: any[]) => T;
 
 type AllJSTypes = PrimitiveTypeStrings | null | undefined | Constructor<unknown>;
 

package/manual_test/index.ts

@@ -1,35 +0,0 @@
-import { assertArrayNonNullable, assertIsTuple, assertTupleNonNullable, assertTupleTypes, assertType } from "../src/index";
-
-const func = (tuple: [unknown, unknown, unknown]) => {
-    console.log(tuple);
-}
-
-const tuple: [unknown, unknown, unknown] = [1, 2, 3];
-const tuple3 = [1, 2, 3] as const;
-const tuple1: [number | undefined, number] = [1, 2];
-const arr: (number|null)[] = [1, 2, 3];
-assertIsTuple(arr, 2);
-assertTupleNonNullable(arr);
-const nntuple1: [number, number] = arr;
-tuple1[0] = 1;
-// assertTupleTypes(tuple3, ["number", "number", "number"]);
-
-type Tuple<T, N extends number, A extends unknown[] = []> = A extends { length: N } ? A : Tuple<T, N, [...A, T]>;
-
-type Tuple20 = Tuple<number, 20>;
-
-func(tuple);
-
-const tuple2 = tuple3;
-// const tuple5: [number, number, number | undefined] = tuple3;
-
-type Tuple3 = typeof tuple3;
-type Tuple3Length = Tuple3["length"];
-
-function func2<T extends number[]>(
-  nums: T & (number extends T["length"] ? unknown : never)
-) {
-    console.log(nums);
-}
-
-// func2(tuple3);

package/migration-guide-template.md

@@ -1,3 +0,0 @@
-## [0.1.x to 0.2.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.1.0...v0.2.0)
-
-* Change all calls to `assertTypeof<<Something>>` to `assertTypeOf<<Something>>` (capitalization change for consistency).