Caveats

We know Bupkis is a rare stroke of genius—but there are things it can't do. Here are some caveats to be aware of.

Expect Is Not A Type Guard

expect() performs assertions, yes, but the type signature does not look like this:

function expect<T>(
  actual: unknown,
  phrase: string,
  ...args: unknown[]
): asserts actual is T;
Copy

Maybe better to show an example:

let foo: unknown = getFoo();

expect(foo, 'to be a string'); // foo is still inferred as `unknown`
Copy

It is currently not possible (as of TypeScript v5.9.2) for a dynamically-typed function (like expect()) to have such a type signature. AFAIK, such a function cannot be overloaded, which is in direct conflict to Bupkis' mode of operation.

But if that ever changes, we'll jump on it!

Zod Isn't an Assertion Library

…which means using it as a core building block of an assertion library has a few trade-offs.

Zod is meant for parsing and validating data, which means there may be some circumstances where Zod will attempt to mutate the data you give it …which is generally Bad.

For that reason, Bupkis recommends avoiding any Zod schema that mutates data. One example would be the .readonly() schema, which necessarily calls Object.freeze() on the input value (the output is read-only; not the input!). If you need to check that a value is read-only, you can work around this via .refine(), .preprocess(), etc.

Errata

Bits & bobs.

Under Construction

Bupkis is not yet complete (see ROADMAP). There are features that We want to implement that We just haven't gotten to yet, including (but not limited to):

• Custom diffs
• Property drilling via keypaths (to make assertions about deeply-nested props)
• Integration of async assertions into sync assertions (so that you can make any extant sync assertion against a Promise or async function)
• Chaining assertions via boolean logic (and, or, etc.); we already have not
• Unwinding assertions created via composition (i.e. containing calls to expect()) for better error messages & stack traces