@brillout/libassert

Tiny zero-dependency tool for library authors to create assertion functions with clean strack traces.

• Complete stack traces. (Error.stackTraceLimit = Infinity; only for assertion errors.)
• Cleaned stack traces. (Fist stack line points to the assertion breaking code, useless stack lines are stripped away.)
• Error messages are guaranteed to not contain new lines.

1import { newError } from "@brillout/libassert";
2
3export { assert };
4
5function assert(condition: unknown): asserts condition {
6  if (condition) {
7    return;
8  }
9
10  const err = newError(
11    `[${libName}][Internal Error] Something unexpected happened, please open a GitHub issue.`;
12  );
13
14  throw err;
15}

Calling newError(errorMessage) is the same than new Error(errorMessage) except that:

• The stack trace is complete and cleaned as described above.
• errorMessage is forbidden to contain new lines.

You can create all kinds of assertion functions, such as assertUsage or assertWarning:

1import { newError } from "@brillout/libassert";
2
3export { assert, assertUsage, assertWarning };
4
5const libName = "My Awesome Library";
6
7// Assertions that are expected to always be true (also known as "invariants")
8function assert(condition: unknown): asserts condition {
9  if (condition) {
10    return;
11  }
12
13  const err = newError(
14    `[${libName}][Internal Error] Something unexpected happened, please open a GitHub issue.`;
15  );
16
17  throw err;
18}
19
20// Wrong usage of your library
21function assertUsage(
22  condition: unknown,
23  errorMessage: string
24): asserts condition {
25  if (condition) {
26    return;
27  }
28
29  const err = newError(prefix: `[${libName}][Wrong Usage] ${errorMessage}`);
30
31  throw err;
32}
33
34// Something unexpected happened but it is non-critical and doesn't
35// warrant interrupting code execution.
36function assertWarning(condition: unknown, errorMessage: string): void {
37  if (condition) {
38    return;
39  }
40
41  const err = newError(`[${libName}][Warning] ${errorMessage}`);
42
43  console.warn(err);
44}