@nds-stack/bun-schema

Zero-dependency schema validation for Bun — TypeScript-first, Zod-like API.

import { s, Infer } from "@nds-stack/bun-schema";

const UserSchema = s.object({
  name: s.string().min(2).max(100),
  email: s.string().email(),
  age: s.number().int().min(0).optional(),
});

type User = Infer<typeof UserSchema>;

const user = UserSchema.parse({ name: "Alice", email: "alice@example.com", age: 30 });

Why bun-schema

Bun has no built-in validation library, and existing options (Zod, Valibot, TypeBox) bundle Node.js polyfills that Bun doesn't need. bun-schema is:

• Zero dependencies — pure TypeScript, uses only Bun built-in APIs
• Bun-optimized — no polyfills, no Node.js compatibility layer
• TypeScript-first — full type inference from schemas
• Familiar API — Zod-like chaining with .parse(), .safeParse(), type inference
• Tree-shakeable — import only the types you need

Installation

bun add @nds-stack/bun-schema

How It Works

Schema<T> is the abstract base class. Each schema type (StringSchema, NumberSchema, etc.) extends it and implements _safeParse() which recursively validates data and returns a Result<T> discriminated union:

• { success: true, value: T } on valid input
• { success: false, error: ValidationError } on invalid input — with an issues array tracking each failure's field path and message

Validation is lazy: checks are accumulated via method chaining (.min(), .email(), etc.) and executed in order when .parse() or .safeParse() is called. This enables tree-shaking — only the checks you use are included in your bundle.

The s builder object is the entry point: s.string(), s.number(), s.object(), etc. Each call creates a new schema instance.

TypeScript types are inferred via the Infer<T> utility type, reading the generic parameter from Schema<T>. Object schemas map each key's schema type to the corresponding property type.

// Flow:
s.string().min(3).email()
  → new StringSchema()
  → adds "min(3)" check to internal list
  → adds "email" check to internal list
  → when .parse() called, runs all checks in order

API

s.string()

Method	Description
.min(n)	Minimum string length
.max(n)	Maximum string length
.length(n)	Exact string length
.email()	Valid email format
.url()	Valid URL format
.regex(pattern)	Match regular expression
.includes(substr)	Must include substring
.startsWith(prefix)	Must start with prefix
.endsWith(suffix)	Must end with suffix
.coerce()	Coerce input to string

s.number()

Method	Description
.min(n)	Minimum value
.max(n)	Maximum value
.int()	Must be integer
.positive()	Must be > 0
.negative()	Must be < 0
.multipleOf(n)	Must be divisible by n
.finite()	Must be finite
.coerce()	Coerce input to number

s.boolean()

Method	Description
.coerce()	Coerce "true"/"false" strings

s.object(shape)

Method	Description
.strict()	Reject unknown keys
.passthrough()	Allow unknown keys

s.array(item)

Method	Description
.min(n)	Minimum array length
.max(n)	Maximum array length
.length(n)	Exact array length

Modifiers

Method	Description
.optional()	Allow undefined
.nullable()	Allow null
.pipe(schema)	Chain validation
.parse(value)	Validate and return or throw
.safeParse(value)	Validate and return Result<T>

s.union(schemas)

Tries each schema in order, returns first match.

Type Inference

import { s, Infer } from "@nds-stack/bun-schema";

const schema = s.object({ name: s.string(), age: s.number() });
type T = Infer<typeof schema>; // { name: string; age: number }

Error Handling

.parse() throws ValidationError on failure. .safeParse() returns Result<T> — a discriminated union:

const result = schema.safeParse(data);
if (result.success) {
  console.log(result.value); // T
} else {
  console.log(result.error.issues); // ValidationIssue[]
  // [{ path: ["email"], message: "Invalid email" }]
}

Limitations

• No s.date() support yet
• No s.record() key-value map support
• No s.tuple() fixed-length tuple support
• No s.enum() string literal union support
• No s.instanceOf() class instance check
• No lazy/recursive schema support
• No Standard Schema V1 compatibility yet

Multi-Instance / Cross-Boundary

Each Schema instance is stateless and immutable (once built). Schemas are safe to use across workers, serverless invocations, and concurrent contexts:

import { s } from "@nds-stack/bun-schema";

const schema = s.object({ name: s.string() });

// Safe in multiple workers
new Worker(new URL("./worker.ts", import.meta.url));

// worker.ts
import { s } from "@nds-stack/bun-schema";
const localSchema = s.object({ name: s.string() }); // independent instance

Customization Guide

Custom Validation with .pipe()

const PositiveInt = s.number().int().pipe(s.number().positive());

Wrap in your own class

import { s, Infer } from "@nds-stack/bun-schema";

class ValidatedUser {
  readonly name: string;
  readonly email: string;

  constructor(data: unknown) {
    const parsed = UserSchema.parse(data);
    this.name = parsed.name;
    this.email = parsed.email;
  }
}

Comparison Table

Aspect	@nds-stack/bun-schema	zod	valibot	typebox
Dependencies	0	1.5KB	0	0
Bun-native	✅	❌ Polyfills	❌ Polyfills	❌ Polyfills
Bundle size	~3KB	~12KB	~2KB (minimal)	~6KB
Type inference	✅	✅	✅	✅
Tree-shakeable	✅	⚠️ Partial	✅	❌
Zod-like API	✅	Native	Similar	❌ JSON Schema
Coercion	✅	✅	✅	❌

Benchmarks

bun run bench

Benchmark: @nds-stack/bun-schema (10,000 iterations each)
==================================================================================
  Operation                                                 Throughput
==================================================================================
  native: typeof x === 'string'                              2.512.373 ops/s
  native: typeof x === 'number'                              5.564.830 ops/s
  s.string().parse                                           1.479.421 ops/s
  s.number().parse                                           1.109.004 ops/s
  s.boolean().parse                                          2.118.061 ops/s
  s.object().parse (valid 3 fields)                            299.093 ops/s
  s.array().parse (5 items)                                    516.657 ops/s
  s.union().parse                                              262.655 ops/s
==================================================================================

Operation	Throughput	Baseline	Overhead
typeof string (native)	2,512,373 ops/s	—	—
s.string().parse	1,479,421 ops/s	2.5M ops/s	~41%
typeof number (native)	5,564,830 ops/s	—	—
s.number().parse	1,109,004 ops/s	5.6M ops/s	~80%
s.boolean().parse	2,118,061 ops/s	—	—
s.object().parse (3 fields)	299,093 ops/s	—	—
s.array().parse (5 items)	516,657 ops/s	—	—
s.union().parse	262,655 ops/s	—	—

Note: Overhead is expected — schema validation includes type checking, constraint validation, error collection, and path tracking. Results vary by hardware — run bun run bench on your machine.

Real-World Example

API Input Validation:

import { s, Infer, ValidationError } from "@nds-stack/bun-schema";

const CreateUserSchema = s.object({
  username: s.string().min(3).max(50).regex(/^[a-zA-Z0-9_]+$/),
  email: s.string().email(),
  age: s.number().int().min(13).max(150).optional(),
});

type CreateUserInput = Infer<typeof CreateUserSchema>;

async function handleRequest(request: Request): Promise<Response> {
  try {
    const body = await request.json();
    const input: CreateUserInput = CreateUserSchema.parse(body);
    // input is fully typed here
    return new Response(JSON.stringify({ ok: true }), { status: 201 });
  } catch (e) {
    if (e instanceof ValidationError) {
      return new Response(JSON.stringify({ error: e.issues }), { status: 400 });
    }
    return new Response("Internal error", { status: 500 });
  }
}

License

MIT