Production-grade assertion library for TypeScript. Explicit contracts, fail-fast execution, richly formatted errors — zero overhead when silent.
Static types are a compile-time promise. At runtime, that promise is gone. Every null you thought was impossible, every shape you assumed was enforced — they all arrive anyway. The standard response is defensive code: if (!x) return. Silent. Invisible. The bug propagates.
AssertCheck replaces that with a contract system: declare what must never happen, fire exactly where it happens, and surface exactly what went wrong.
function chargeOrder(order: Order) {
if (!order) return // absorbed — caller gets undefined, no trace
if (!order.amount) return // absorbed — negative amounts silently pass
if (order.status !== "pending") return // absorbed — double-charge possible
// Three broken assumptions. None of them surfaced. Ever.
}function chargeOrder(order: Order) {
assert.notNil(order, "order is required")
assert.positive(order.amount, "order amount must be positive")
assert.equal(order.status, "pending", {
msg: "order must be pending before charge",
actual: "order.status",
note: "call resetOrder() before retrying",
})
// Every precondition is named, enforced, and traceable.
}When order.status is "paid" instead of "pending", you get a formatted diagnostic — not a cryptic stack trace.
══════════════════ ● order must be pending before charge ══════
── values ──────────────────────────────────────────────────────
+ expected "pending"
✗ order.status "paid"
── note ────────────────────────────────────────────────────────
call resetOrder() before retrying
════════════════════════════════════════════════════════════════Exact location. Exact values. Exact next step. No debugger, no guessing, no context-switching.
Deep equality failures go further — a field-by-field structural diff:
══════════════════ ● User shape mismatch ══════════════════════
── diff ────────────────────────────────────────────────────────
· id "usr_123"
~ status
expected "active"
actual "banned"
+ role "admin" ← missing in actual
════════════════════════════════════════════════════════════════Output adapts automatically: ANSI on TTY, plain text in CI, console.groupCollapsed in the browser.
if/return | node:assert | zod / yup | assertcheck | |
|---|---|---|---|---|
| Fails loudly in dev | — | Yes | Yes | Yes |
| Zero overhead in prod | — | — | — | Yes (disabled mode) |
| Type narrowing | — | — | Yes | Yes |
| Structured, readable errors | — | Partial | Partial | Yes |
| Chainable fluent API | — | — | — | Yes |
| Enforces function invariants | — | — | — | Yes |
| AI Copilot skills included | — | — | — | Yes |
Zod and Yup are schema validators — they validate data that comes in from the outside (forms, APIs, JSON). AssertCheck is a contract system — it enforces invariants at every internal boundary: function arguments, state transitions, external responses, collection shapes. The two are complementary, not competing.
Every assertion accepts an optional opts parameter with a message, an actual-value label, and a hint for the developer.
import { assert, check } from "assertcheck"
// Existence & type guards
assert.notNil(user, "user is required")
assert.string(userId, "userId must be a string")
assert.positive(price, "price must be positive")
// Deep equality with structural diff
assert.deepEqual(result, expected, "API response shape changed")
// Chainable invariants on collections
check(orders)
.notEmpty("cart must not be empty before checkout")
.noNils("no null order items allowed")
.all(o => o.amount > 0, "all orders must have a positive amount")
.uniqueBy("id", "duplicate order IDs detected")
// Object shape guards
check(config)
.hasKeys(["host", "port", "database"], "missing required config keys")
.dig("database.pool.max", 10, "pool size must be at least 10")50+ methods covering existence, types, numerics, equality, arrays, objects, and function purity.
No configuration. No polyfills. No runtime dependencies beyond lodash.
deno add jsr:assertcheckconsole.groupCollapsed outputAssertCheck is maintained by Vagabond Studio — a fully remote, senior-only collective of engineers and designers.
We build TypeScript, Vue.js, Rails, and Django products from greenfield to production. AssertCheck is how we guard every internal boundary in every service we ship.