invariant 🔬🔨

TypeScript invariant with custom error class support — tiny as tiny-invariant, type-safe as ts-invariant, versatile as nothing else.

How it works

An invariant function takes a value and throws if the value is falsy. If the value is truthy, execution continues and TypeScript narrows the type.

import { invariant } from "@crutchcrew/invariant"

const user: User | null = getUser()
invariant(user, "User not found")
console.log(user.name) // user is narrowed to User

Why this package

| | This package | tiny-invariant | ts-invariant | invariant | | --------------------------------------- | ------------ | --------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------- | | Size (gzip) | ~364 B | ~370 B | ~1.0 kB | ~1.1 kB | | Zero Dependencies | ✅ | ✅ | ❌ | ❌ | | Tree-shakeable ESM | ✅ | ✅ | ✅ | ❌ | | Type narrowing | ✅ | ✅ | ✅ | ❌ | | Strict typing | ✅ | ❌ | ❌ | ❌ | | Lazy messages | ✅ | ❌ | ❌ | ❌ | | Console methods | ✅ | ❌ | ✅ | ❌ | | Invariant factory | ✅ | ❌ | ❌ | ❌ |

Install

Choose your fighter 🥊

pnpm add @crutchcrew/invariant

bun add @crutchcrew/invariant

yarn add @crutchcrew/invariant

npm add @crutchcrew/invariant

Usage

const response = await fetch("/users/1")
invariant(response.ok, `Request failed: ${response.status}`)

const user = await response.json()

Lazy messages

Pass a function to defer message construction and avoid expensive message computation

invariant(value, getExpensiveMessage)

Custom errors

If you need to throw domain-specific errors — a NotFoundError, a ValidationError, or anything else — you're left wrapping calls or rolling your own helper. This package provides createInvariant to build an invariant function that throws any error class you give it, with the same assertion narrowing and lazy message support.

Use createInvariant to throw your own error type:

import { createInvariant } from "@crutchcrew/invariant"

class HttpError extends Error {
	name = "HttpError"
}

const invariant = createInvariant(HttpError)

export async function getUser(id: string) {
	const response = await fetch(`/users/${id}`)
	invariant(response.ok, `Request failed: ${response.status}`)

	return response.json()
}

Console methods

The invariant function exposes debug, log, warn, and error methods that delegate to the corresponding console methods:

invariant.debug(`Message ${id} sent`)
invariant.log("User", user)
invariant.warn("Unexpected state", { detail })
invariant.error("Something went wrong")

Strict typing

The default invariant allows to pass any value as a condition so it can check on any truthy/falsy value — objects, strings, numbers, whatever you hand it. Import from @crutchcrew/invariant/strict instead to require an actual boolean, catching accidental truthy/falsy checks at the type level:

import { invariant } from "@crutchcrew/invariant/strict"

invariant(user !== null, "User not found") // ✅ boolean condition
invariant(user, "User not found") // ❌ type error: User | null is not assignable to boolean

It's the same runtime as the regular invariant — just a stricter type layer — so createInvariant and InvariantError are also available from /strict.

API

invariant(condition, message?)

// default
(condition: unknown, message?: string | (() => string)) => asserts condition
// strict
(condition: boolean, message?: string | (() => string)) => asserts condition

Throws InvariantError if condition is falsy. Narrows the type of condition to truthy.

createInvariant(ErrorClass)

;<E extends Error>(ErrorClass: new (message: string) => E) => Invariant

Returns a new invariant function that throws ErrorClass instead of InvariantError.

InvariantError

Default error class thrown by invariant. Extends Error with framesToPop = 1 for cleaner stack traces.

Development

bun install
bun test
bun run check    # fmt + lint (with type-check) in parallel

Credits

The API and InvariantError design are based on ts-invariant by Ben Newman and the Apollo team. The /strict entry point is inspired by ts-tiny-invariant by Igor Yegoroff.