feat(assert): support callback for message

A callback may be passed to `assert`'s second arg instead of a string. The callback must return a string.

This is useful in when the message is expensive to create. With the callback message, we can defer the potentially costly message creation until it is actually needed.

Closes #34

src/assert.ts

@@ -29,8 +29,11 @@ export class AssertionError extends Error {
 }
 
 /** https://docs.tsafe.dev/assert */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function assert<_T extends true>(condition?: any, msg?: string): asserts condition {
+export function assert<_T extends true>(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    condition?: any,
+    msg?: string | (() => string),
+): asserts condition {
     if (arguments.length === 0) {
         condition = true;
     }
@@ -40,6 +43,6 @@ export function assert<_T extends true>(condition?: any, msg?: string): asserts
     }
 
     if (!condition) {
-        throw new AssertionError(msg);
+        throw new AssertionError(typeof msg === "function" ? msg() : msg);
     }
 }

test/assertIs.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { assert } from "../src/assert";
+import { assert, AssertionError } from "../src/assert";
 import { is } from "../src/is";
 import type { Equals } from "../src/Equals";
 
@@ -47,3 +47,78 @@ scope: {
 
     throw new Error("Fail");
 }
+
+/**
+ * When an assertion fails and no message was provided, it should throw an `AssertionError` with the
+ * message 'Wrong assertion encountered'.
+ */
+{
+    try {
+        assert(false);
+    } catch (e) {
+        assert(e instanceof AssertionError);
+        assert(e.message === "Wrong assertion encountered");
+        console.log("PASS");
+    }
+}
+
+/**
+ * When an assertion fails and a message string was provided, it should throw an `AssertionError` with
+ * the message 'Wrong assertion encountered: "<message>"'.
+ */
+{
+    try {
+        assert(false, "message");
+    } catch (e) {
+        assert(e instanceof AssertionError);
+        assert(e.message === 'Wrong assertion encountered: "message"');
+        console.log("PASS");
+    }
+}
+
+/**
+ * When an assertion passes and a message callback was provided, the callback should not be called.
+ */
+{
+    let called = false as boolean;
+    const message = () => {
+        called = true;
+        return "message";
+    };
+    assert(true, message);
+    assert(called === false);
+    console.log("PASS");
+}
+
+/**
+ * When an assertion fails and a message callback was provided, the callback should be called.
+ */
+{
+    let called = false as boolean;
+    const message = () => {
+        called = true;
+        return "message";
+    };
+    try {
+        assert(false, message);
+    } catch (e) {
+        assert(e instanceof AssertionError);
+        assert(called === true);
+        console.log("PASS");
+    }
+}
+
+/**
+ * When an assertion fails and a message callback was provided, it should throw an `AssertionError` with
+ * the message 'Wrong assertion encountered: "<return value from message callback>"'.
+ */
+{
+    const message = () => "message";
+    try {
+        assert(false, message);
+    } catch (e) {
+        assert(e instanceof AssertionError);
+        assert(e.message === 'Wrong assertion encountered: "message"');
+        console.log("PASS");
+    }
+}