@zudojs/schema

OVERVIEW

Data that arrives from outside your program is untrusted. A request body, a query string, a JSON file, an environment variable: any of them can be missing a field, hold the wrong type, or contain nonsense. Your code has to check all of it before using it.

A schema is a description of what a value is allowed to look like. "An object with a name that is a string of at least two characters, and an email that looks like an email address." You write that description once with @zudojs/schema, and the package turns it into three things: a runtime check, a cleaned-up copy of the value, and a TypeScript type.

When a value does not match, you do not get a vague "invalid input". You get a list of issues, each one saying which field failed, why, and what was expected.

INSTALLATION

Install the package. It pulls in its own runtime dependencies (@zudojs/errors, @zudojs/constants, @zudojs/types) automatically.

QUICK START

This defines a user schema, checks a good value, then checks a bad one and prints what went wrong.

You should see the parsed user printed first, then two lines describing the two problems with the second value.

PARSE VS VALIDATE

Validating answers a yes/no question: does this value match the schema? Parsing goes one step further: it validates, and then hands you a new value that is guaranteed to match. That new value may differ from the input. Unknown object keys are dropped, .trim() removes whitespace, defaults are filled in.

Every schema has two methods that do this. They run the same checks; they differ only in how they report failure.

• → parse(input) returns the parsed value, or throws a SchemaError. Use it when a bad value means "stop here".
• → safeParse(input) never throws. It returns { success: true, data } or { success: false, issues }. Use it when you want to show the errors to someone.

Both accept unknown, so you can pass the raw result of JSON.parse straight in. This catches the thrown error from parse() and reads its issues.

parse() throws a SchemaError<SchemaIssue>. isSchemaValidationError(error) is a type guard: a function whose true answer tells TypeScript what the value is. After it, error.issues is typed readonly SchemaIssue[], and the guard has also checked at runtime that every issue has a code, path and message. Anything else, such as a TypeError from your own code, fails the guard, so you can rethrow it.

READING A VALIDATION ISSUE

An issue is one plain object describing one problem. A failed safeParse gives you an array of them in result.issues; a thrown SchemaError carries the same array in error.issues.

Here is the single issue produced by checking a nested email field.

Messages are written to be shown to people, so counts read naturally: schema.string().min(1) reports "String must be at least 1 character" and schema.array(item).min(1) reports "Array must have at least 1 item", while larger counts use the plural ("at least 2 characters"). Match on code, never on the message text.

BUILDING BLOCKS

Everything starts from the schema object. Each function on it builds a schema for one kind of value, and most return an object with extra methods that tighten the rule. Calling one of those methods returns a new schema; the original is never changed.

The two schemas you will use most are string() and number().

Every schema in this table also has the chainable .optional(), .nullable(), .default(), .refine() and .transform() methods, so schema.boolean().optional() works just like schema.string().optional(). Before 1.2.0 only string(), number() and the coerce schemas had them.

URLs and dates

.url() accepts only absolute http: and https: URLs by default. That is deliberate: a link a user submits should never be a javascript: or data: URL. For other kinds of URL, such as a database connection string in DATABASE_URL, list the schemes (protocols) you allow, or pass "any" to accept any scheme the standard URL parser understands.

.date() (YYYY-MM-DD), .datetime() (YYYY-MM-DDTHH:mm:ss with optional fractions and a Z or ±hh:mm offset) and .time() (HH:mm:ss) check that the value is a real one, not just that it has the right shape: the month is 01-12, the day exists in that month (29 February only in leap years), hours are 00-23, minutes and seconds 00-59, and an offset is at most 23:59.

OBJECTS AND ARRAYS

schema.object({ ... }) takes a shape: a plain object whose values are schemas. Every key in the shape is required unless its schema is optional or has a default. schema.array(item) checks every element against one item schema.

By default an object schema strips keys it does not know about. Call .strict() to reject them, or .passthrough() to keep them.

This builds a post with a list of tags, then derives smaller schemas from it.

Update schemas with partial()

A common pattern is one schema for creating a record and .partial() of it for updating one, where the caller sends only the fields that change. .partial() keeps checking the fields that are present but leaves the missing ones missing, even when they have a .default(). Otherwise every update would quietly reset those fields to their defaults.

OPTIONAL, NULLABLE, DEFAULT

Three wrappers change what a schema accepts when the value is absent. Optional also accepts undefined. Nullable also accepts null. Default replaces undefined with a value you choose, then checks that value.

There are two ways to apply them. Every primitive schema (string(), number(), boolean(), bigint(), symbol(), literal(), enum(), null(), undefined(), any(), unknown(), never()) and every coerce schema has .optional(), .nullable() and .default() methods. Structures (objects, arrays, tuples, records, maps, sets) and combinations (unions, intersections, lazy schemas) do not, so you wrap them with schema.optional(x), schema.nullable(x) or schema.default(x, value).

Both forms are shown here. Missing keys get their default. An optional key that is missing from the input is also missing from the result: it is not added with the value undefined.

The second call sends nickname explicitly as undefined, so the key is kept. This matters when you save the result: a key that is not there leaves the stored column alone, while a key set to undefined may be written as NULL. Before 1.2.0 every missing optional key came back as undefined.

REFINE AND TRANSFORM

Built-in rules cover types and sizes. For anything else, refine adds your own check: a function that gets the already-valid value and returns true or false, plus the message to report when it returns false. Refine and transform callbacks run only when the inner schema accepted the value.

Transform changes the output. Its function receives the valid value and returns something new, possibly of a different type. The schema's output type follows whatever you return.

Like the wrappers above, .refine() and .transform() are methods on every primitive and coerce schema (schema.boolean().transform(...) works too); for objects, arrays and other structures use schema.refine(x, check, message) and schema.transform(x, fn).

COMBINING SCHEMAS

A union means "one of these". The value is tried against each member in order and the first match wins. A discriminated union is a union of objects that all carry a tag field (the discriminator); the tag picks the member directly, which is faster and gives clearer errors.

An intersection means "both of these"; two object schemas are merged into one result (nested objects are merged deeply). A lazy schema wraps a function that returns the real schema, which lets a schema refer to itself for trees and nested comments.

This shows all four. The lazy tree needs an explicit type annotation because TypeScript cannot infer a self-referencing type.

COERCION

Query strings and form fields always arrive as text. "3" is not the number 3, so schema.number() rejects it. The schema.coerce schemas convert first, then check. They are deliberately strict: an empty string is not zero, and "1e999" is not a number.

This parses page settings from a URL query.

TYPE INFERENCE

You never write a TypeScript type by hand for a schema. Infer<typeof MySchema> reads the output type straight from it, so the type and the runtime check can never drift apart.

This derives a type and uses it for a function parameter.

An optional field becomes an optional property (age?:), because a parsed object leaves out an optional key that the input left out. That also makes the inferred type correct under TypeScript's exactOptionalPropertyTypes setting. The type that does this is exported as ObjectShapeOutput<Shape>.

Two related helpers exist. SchemaOutput<T> is the same as Infer<T>. SchemaInput<T> gives the type before a transform runs, which is only different for transform schemas.

PARSE OPTIONS

Both parse and safeParse take an optional second argument. This stops at the first issue instead of collecting all of them.

API REFERENCE

Everything below is importable from @zudojs/schema. Each schema.x() also has a standalone twin named xSchema() (for example stringSchema(), objectSchema(), coerceNumberSchema()); they are the same functions.

The schema namespace

Every schema (class Schema)

Result helpers

Types

Errors and constants

The package also exports the low-level pieces used to write a custom Schema subclass: createParseContext, childContext, addIssue, failValidation, rethrowUnexpected, enterComposite, leaveComposite, isMaxDepthExceeded, shouldAbortEarly, countIssues, SchemaValidationSignal (an internal control-flow signal; intentionally not a @zudojs/errors class), ModifiableSchema (the base class that gives a schema .optional(), .nullable(), .default(), .refine() and .transform()) and the individual schema classes. You will not need them for everyday use.

COMMON MISTAKES

• → Calling .optional() on an object, array or union schema. TypeScript reports that the method does not exist. Wrap it instead: schema.optional(schema.array(schema.string())). (Primitives, including boolean(), enum() and literal(), do have the method.)
• → Chaining .transform() after .refine(). .refine() returns a base Schema with no chain methods. Use schema.transform(refined, fn).
• → Using schema.number() for query-string values. "3" is a string, so it fails with invalid_type. Use schema.coerce.number().
• → Expecting extra keys to survive. Objects strip unknown keys by default, so parse() returns a smaller object than you passed in. Call .passthrough() to keep them or .strict() to reject them.
• → Importing SchemaError from @zudojs/schema. It is not exported there; import it from @zudojs/errors.
• → Casting error.issues as SchemaIssue[]. A cast checks nothing and hides the case where the caught value is some other error. Use if (isSchemaValidationError(error)), which narrows the type and checks the issues at runtime.
• → Using .partial() to build a create schema. .partial() does not fill in defaults, so a record created from it lacks every defaulted field the caller left out. Use the full schema for creating and .partial() for updating.
• → Forgetting the type annotation on a lazy schema. TypeScript errors with "implicitly has type any". Declare it as const Tree: Schema<TreeNode> = schema.lazy(...).

RELATED PACKAGES

• → @zudojs/errors — home of SchemaError and the shared error base classes.
• → @zudojs/api — attach a schema to an operation's input so it is checked before your handler runs.
• → @zudojs/http — where request bodies and query strings come from; parse them with a schema first.
• → @zudojs/openapi — turns schemas and their describe() metadata into API documentation.
• → @zudojs/constants — SchemaIssueCode and the default size limits.

COMPLETE EXPORT INDEX

Every name @zudojs/schema exports from its package root at v1.2.0 — 98 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.