@philiprehberger/micro-schema

Lightweight schema validation library with Zod-like API in under 3KB

Installation

npm install @philiprehberger/micro-schema

Usage

Define a Schema

import { s, type Infer } from '@philiprehberger/micro-schema';

const UserSchema = s.object({
  name: s.string().min(1).max(100),
  email: s.string().email(),
  age: s.number().int().positive().optional(),
  role: s.enum(['admin', 'user', 'guest']),
});

type User = Infer<typeof UserSchema>;

Parse

// Throws ValidationError on failure
const user = UserSchema.parse(input);

// Safe parse — never throws
const result = UserSchema.safeParse(input);
if (result.success) {
  result.data; // User
} else {
  result.errors; // ValidationIssue[]
}

Types

Primitives

s.string()       // string, with .min() .max() .email() .url() .uuid() .regex() .trim()
s.number()       // number, with .min() .max() .int() .positive() .negative()
s.boolean()      // boolean
s.date()         // Date (accepts Date, string, or number)
s.literal('foo') // exact value
s.enum(['a', 'b', 'c'])

Composites

s.object({ key: s.string() })           // object with shape
s.object({ key: s.string() }).strict()   // reject unknown keys
s.array(s.number())                      // array, with .min() .max()
s.tuple([s.string(), s.number()])        // fixed-length typed array
s.union([s.string(), s.number()])        // first matching schema wins (detailed errors on failure)
s.record(s.number())                     // Record<string, number>

Modifiers

Available on all schema types:

s.string().optional()          // allows undefined
s.string().nullable()          // allows null
s.string().default('hello')    // default value if undefined
s.string().transform(s => s.toUpperCase())
s.number().refine(n => n % 2 === 0, 'Must be even')

Nested Validation Errors

const schema = s.object({
  user: s.object({
    email: s.string().email(),
  }),
});

const result = schema.safeParse({ user: { email: 'bad' } });
// errors: [{ path: ['user', 'email'], message: 'Invalid email address' }]

Type Inference

import { type Infer } from '@philiprehberger/micro-schema';

const Schema = s.object({
  name: s.string(),
  tags: s.array(s.string()),
  status: s.enum(['active', 'inactive']),
});

type MyType = Infer<typeof Schema>;
// { name: string; tags: string[]; status: 'active' | 'inactive' }

API

Schema Builder (s)

Method	Returns	Description
s.string()	StringSchema	String with .min() .max() .email() .url() .uuid() .regex() .trim()
s.number()	NumberSchema	Number with .min() .max() .int() .positive() .negative()
s.boolean()	BooleanSchema	Boolean.
s.date()	DateSchema	Date (accepts Date, string, or number).
s.literal(value)	LiteralSchema	Exact value match.
s.enum(values)	EnumSchema	One of specified string values.
s.object(shape)	ObjectSchema	Object with typed fields.
s.array(schema)	ArraySchema	Array with .min() .max().
s.tuple(schemas)	TupleSchema	Fixed-length array with per-position schemas.
s.union(schemas)	UnionSchema	First matching schema wins. Detailed errors on failure.
s.record(valueSchema)	RecordSchema	Record<string, T>.

Schema Methods (all types)

Method	Description
.parse(input)	Returns validated value or throws ValidationError.
.safeParse(input)	Returns { success: true, data } or { success: false, errors }.
.optional()	Allows undefined.
.nullable()	Allows null.
.default(value)	Use default when undefined.
.transform(fn)	Transform the output value.
.refine(check, message)	Custom validation.

ValidationError

Property	Type	Description
issues	ValidationIssue[]	Array of { path: (string | number)[], message: string }.

Infer<T>

TypeScript utility type to extract the output type from any schema:

type User = Infer<typeof UserSchema>;

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT