assertie 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.2.0](https://github.com/OfficialHalfwayDead/assertie/compare/v0.1.0...v0.2.0) (2025-02-17)
+
+### Breaking Changes
+
+* [`a721e02`](https://github.com/OfficialHalfwayDead/assertie/commit/a721e02b2e8b7378f4dc017e02c2dd48ba899bfb) Renamed all `assertTypeof` to `assertTypeOf` for readability and consistency with `assertInstanceOf`. Sorry for the instant breaking change if anyone was already using it. Better now than carrying that inconsistency around forever.
+
+### Features
+
+* [`76ff555`](https://github.com/OfficialHalfwayDead/assertie/commit/76ff555cbb3a17d27c07642b078f96cd807812ba) Add `assertNull` as it was the only option in `assertType(val, null)` that didn't have an individual function counterpart.

package/README.md

@@ -2,15 +2,24 @@
 
 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.
+Why? Because asserts are simple to read and safer than casting. As programmers, we sometimes make wrong assumptions. Use them when you know something is guaranteed to be true, and assertie will make sure it actually is in dev builds.
 
 ```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
+
+// If the element isn’t found, we exit here.
+// Asserts are not meant for validating uncertain values.
+if (original === null) return;
+
+// cloneNode returns type Node, but we know it will always
+// be an HTMLElement, because `original` was one.
+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;
 clone.innerText = "No `as` cast needed! 0 overhead in production.";
 ```
 
@@ -53,7 +62,8 @@ const config: UserConfig = {
 ```ts
 import { assert } from "assertie";
 
-assert(typeof "yup" === "string", "optional text if assertion fails");
+const a = "yup";
+assert(a === "yup", "optional text if assertion fails");
 
 // You get type narrowing from assertie's assertions
 const x: boolean = true;
@@ -66,7 +76,8 @@ const y: true = x; // no error
 ```ts
 import { assertType } from "assertie";
 
-// assertType can take any primitive JS type string (e.g., "number", "string"), null, undefined, or 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");
 assertType(undefined, "undefined");
@@ -84,14 +95,15 @@ 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"));
+assertTypeOfString("yup");
+assertTypeOfNumber(123);
+assertTypeOfBoolean(true);
+assertTypeOfBigint(123n);
+assertTypeOfUndefined(undefined);
+assertNull(null); // different because typeof null === "object"
+assertTypeOfFunction(() => {});
+assertTypeOfObject({});
+assertTypeOfSymbol(Symbol("yup"));
 assertInstanceOf(new Date(), Date);
 ```
 
@@ -105,7 +117,9 @@ let hoisted: string | null | undefined = null;
 const f =  () => {
     assertNonNullable(hoisted);
     // vs.
-    if (hoisted === null || hoisted === undefined) return;
+    if (hoisted === null || hoisted === undefined) {
+        return;
+    }
 
     console.log(hoisted.toUpperCase());
 };
@@ -116,10 +130,10 @@ 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.
+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.
+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 leave both in.
+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.
 
 ```ts
 // Sometimes not your entire object is null
@@ -138,11 +152,14 @@ 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.
+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.
 
 ### 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.
+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.
 
 ```ts
 const x: "a" | "b" = "a";
@@ -165,8 +182,8 @@ For now, there is only one:
 
 ```ts
 assertFiniteNumber(123);
-// Ensures passed value is typeof number and finite
+// Ensures passed value is typeof number and isFinite(num)
 // 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"`).
+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"`).

package/lib/index.d.ts

@@ -20,14 +20,15 @@ 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 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>;

package/lib/index.js

@@ -23,55 +23,61 @@ export function assertType(obj, expectedType) {
         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) {
+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) {
+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) {
+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) {
+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) {
+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) {
+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) {
+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) {
+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 assertNull(obj) {
+    if (!import.meta.env.DEV)
+        return;
+    if (obj !== null)
+        throw new AssertionError(`Provided object was not null. Was: ${obj}`);
+}
 export function assertInstanceOf(obj, constructable) {
     if (!import.meta.env.DEV)
         return;

package/package.json

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

package/src/index.ts

@@ -50,47 +50,52 @@ export function assertType<T extends AllJSTypes>(obj: unknown, expectedType: T):
     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 {
+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 {
+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 {
+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 {
+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 {
+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 {
+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 {
+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 {
+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 assertNull(obj: unknown): asserts obj is null {
+    if (!import.meta.env.DEV) return;
+    if (obj !== null) throw new AssertionError(`Provided object was not null. Was: ${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}`);