Version v26.11.20 Size 8.5 KB gzip
Why Spell?
Spell keeps runtime validation, static inference, and portable definitions in one API. Checks and transforms run in the order you chain them, and every built-in constraint appears in the exported definition.
This example shows the difference between manual branching and a single reusable schema.
ts
// Before
function parseUserBefore(value: unknown) {
if (typeof value !== 'object' || value === null) throw new Error('Expected object');
const candidate = value as Record<string, unknown>;
if (typeof candidate.email !== 'string' || !candidate.email.includes('@')) {
throw new Error('Expected valid email');
}
if (typeof candidate.role !== 'string' || !['admin', 'editor', 'viewer'].includes(candidate.role)) {
throw new Error('Expected valid role');
}
return {
email: candidate.email,
role: candidate.role,
};
}
// After
import { s } from '@vielzeug/spell';
const User = s.object({
email: s.string().email(),
role: s.enum(['admin', 'editor', 'viewer'] as const),
});
const user = User.parse({ email: 'ada@example.com', role: 'admin' });| Feature | Spell | Zod | Yup |
|---|---|---|---|
| Bundle size | 8.5 KB | ~62 kB | ~14 kB |
| Type inference | Infer<T> | Partial | |
| Coercion API | s.coerce.* | ||
| Async validation | .checkAsync() | ||
| Error flattening | flatten() + flattenFirst() | Partial | |
| Zero dependencies |
Use Spell when you want a fluent schema API with strong TypeScript inference, structured errors, and no third-party runtime dependencies.
Consider alternatives when you are already standardized on another validator ecosystem and migration cost outweighs the API benefits.
Installation
Use your workspace package manager to add Spell.
sh
pnpm add @vielzeug/spellsh
npm install @vielzeug/spellsh
yarn add @vielzeug/spellQuick Start
Start with a schema, then parse unknown input and use the inferred output type everywhere else.
ts
import { s, type Infer } from '@vielzeug/spell';
const User = s
.object({
email: s.string().email(),
name: s.string().min(1),
role: s.enum(['admin', 'editor', 'viewer'] as const),
})
.relaxed(); // allow extra keys: omit for strict-mode (default)
type User = Infer<typeof User>;
const payload: unknown = {
email: 'ada@example.com',
name: 'Ada',
role: 'admin',
team: 'platform',
};
const result = User.safeParse(payload);
if (!result.success) throw result.error;
const user = result.data;Features
sbuilders for primitives, collections, objects, unions, and recursive schemas.parse(),safeParse(),parseAsync(), andsafeParseAsync(); parsing stays synchronous unless a check is async.check()andcheckAsync()run in chain order with transforms; sync parsing never skips an async check.optional,nullable,nullish,default,catch, andrequiredmodifiers; defaults are copied per parse.extend(),pick(),omit(),partial(), andtolerate()for object composition and schema evolution.definition()returns frozen data;toJsonSchema()from@vielzeug/spell/jsonconverts it to JSON Schema.schema['~standard']implements Standard Schema v1 without an adapter.createParseContext()customizes messages per request, locale, or form.SpellValidationErroroffersflatten(),flattenFirst(), andmessagesAt()for UI errors.- Object and record parsing is hardened against prototype-pollution keys.