Crumb

Crumb is a TypeScript first runtime contract and validation library.

It solves one problem well:

Validating untrusted data at runtime while keeping TypeScript honest.

Crumb is small, explicit, and boring on purpose.

Why Crumb exists

TypeScript types disappear at runtime.

Any data coming from the outside world is untrusted:

• API request bodies
• environment variables
• config files
• JSON payloads
• webhooks
• message queues

Crumb sits at the boundary where data becomes trusted.

You validate once.
After that, your code can rely on types without guessing.

What Crumb is

Crumb provides:

• runtime validation
• static type inference
• explicit parsing
• readable errors
• zero magic

Crumb validates data when it enters your system.

What Crumb is not

Crumb is not:

• a form library
• UI validation
• schema driven code generation
• an ORM
• automatic data transformation
• a framework

If you need state, side effects, or hidden behavior, Crumb is not the tool.

Installation

pnpm add crumb

or

npm install crumb

Basic example

import { crumb } from "crumb"

const User = crumb.object({
  id: crumb.string(),
  age: crumb.number().min(18),
  email: crumb.string().email()
})

const user = User.parse(input)

Behavior

If parsing fails:

• an error is thrown
• the error includes a readable path
• no partial data is returned

If parsing succeeds:

• user is fully typed
• no undefined fields
• no runtime guessing

Core concept

Data is untrusted until it is parsed.

Treat all external input as unknown and validate it explicitly.

Common use cases

Crumb is designed for:

• API request validation
• environment variable validation
• config file validation
• webhook payload validation
• message queue events
• internal trust boundaries
• Crumb is transport agnostic.
• It does not care where the data comes from.

Error handling

Crumb fails loudly. By default:

• invalid data throws an error
• errors include the exact failing path
• nested structures produce nested paths
• Errors are designed for humans first and machines second.

Design principles

• Runtime behavior comes first
• No implicit coercion
• No global state
• Errors must be readable by humans
• Optional values must be explicit
• One clear way to do one thing

Runtime support

Crumb v1.0 is Node first.
Other runtimes may be supported after the core API stabilizes.

Project status

• Crumb is in early development.
• APIs may change
• features are intentionally limited
• feedback is welcome
• The goal is correctness and clarity, not completeness.

License

MIT