@zudojs/validation

OVERVIEW

Validation means checking that a value you did not create has the shape and contents you expect before your code uses it. A form submission, a JSON request body, a config file and a row from a CSV are all values you did not create.

@zudojs/validation gives you three tools for that. A schema describes the shape of a whole value ("an object with a string name and a positive number age"). A constraint is one small reusable rule ("is an email", "at least 3 characters"). A pipeline chains schemas and constraints into one check. All three return the same ValidationResult, so you handle failures the same way everywhere.

It also ships guards for hostile input. A payload nested 20,000 levels deep, or a 50 MB object, can crash a server before validation even starts. The depth, size and circular-reference guards reject those early and cheaply.

VALIDATION VS @ZUDOJS/SCHEMA

Zudo has two packages that check data, and they do not share schemas. Pick one per project boundary.

• → @zudojs/validation (this page) is built on Zod. You write schemas with z.object(...), and the package adds constraints, pipelines, normalizers, a registry and structural guards around them. Its validate() and parse() accept a ZodType only.
• → @zudojs/schema is Zudo's own schema engine with no Zod dependency. You write schema.object(...) and call .safeParse() on the schema itself.

INSTALLATION

Install the package. It pulls in zod (v4), @zudojs/errors, @zudojs/constants and @zudojs/types as regular dependencies, so you do not install those separately.

QUICK START

This example describes a sign-up payload, validates two inputs, and prints the outcome of each.

validate() never throws. It returns an object whose success field tells you which of two shapes you got. The next section explains how to read it.

READING A RESULT

Every check in this package returns a ValidationResult<T>. It is one of two plain objects, and the success field tells them apart. TypeScript uses that field to narrow the type, so inside if (result.success) the data field is typed as T.

Two helpers turn an issue list into something you can show a user. formatIssues makes one line; toFieldErrors makes a map of field name to first message, which is what a form wants.

Other result helpers: isValidationSuccess(r) and isValidationFailure(r) are type guards; unwrapValidation(r) returns data or throws a ValidationResultError; map(r, fn) transforms data only on success; combine([r1, r2]) merges several results into one, collecting every issue.

HANDLING FAILURES

You can handle a failure in two styles. The result style uses validate() and an if, as above. The throwing style uses parse(), which returns the typed data directly and throws a SchemaValidationError when the value is bad. Use throwing when a bad value means the current operation cannot continue anyway.

This example parses in throwing style and catches the error. The error carries the same issues, plus helpers.

All validation errors extend ValidationError, which extends the ValidationError of @zudojs/errors (a BaseError). That means they already carry statusCode: 400, expose: true and a toJSON() that includes issues, so an HTTP layer can serialize them without extra code.

CONSTRAINTS

A constraint is one named rule for one value: a function that returns true or false, plus a code and message to report when it fails. Constraints exist so you can define a rule once ("must be an adult") and reuse it in many places without a full schema.

This example runs two built-in constraints against a string, then builds a custom one with createConstraint.

Built-in constraints. Those written as name(arg) are functions you call; the rest are ready-made values.

Length and count messages use the singular for one: minLength(1) reports "Value must contain at least 1 character." and minItems(1) or exactItems(1) say "1 item", where they used to say "1 characters" and "1 items". Larger counts keep the plural. The wording comes from formatCount in @zudojs/types. Messages from a z schema (such as the too_small issue in the quick start) are Zod's own text and are passed through unchanged.

PIPELINES (COMPOSER)

A pipeline runs several checks in order on one value. Each check is a step: a function that takes a value and returns a ValidationResult. You turn a schema into a step with schemaStep() and constraints into a step with constraintsStep(), then hand the list to createValidationComposer().

This pipeline first checks that the value is a number, then that it is a positive integer. It stops at the first failing step, so the constraints never see a non-number.

Steps are plain functions, so you can shape them before putting them in a pipeline:

• → all(a, b) runs every step and reports all issues; any(a, b) passes if one passes; first(a, b) like any but reports only the last failure; negate(a) flips it.
• → optional(a), nullable(a), optionalNullable(a) let undefined / null through without running a.
• → when(predicate, a) and unless(predicate, a) run a conditionally; tap(a) runs a but keeps the original value; mapValidated(a, fn) changes the value after a passes; append(composer, step) adds a step to an existing pipeline.
• → composeSchemas(s1, s2) pipes Zod schemas of the same type into one schema.

PARSERS

A parser is a schema bundled with the three ways to use it: parse() (throws), safeParse() (returns a result) and isValid() (returns a boolean). Create one when the same schema is used in several places so callers do not need to import the schema.

This example builds a parser, then uses the fallback helpers parseOr and parseMany on the same schema.

Related helpers: createAsyncValidationParser for schemas with async refinements, parseOrElse(schema, value, fn) to compute the fallback from the error, parseRecord(schema, obj) to validate every value of an object (it rejects __proto__ keys), and parseOptional / parseNullable / parseOptionalNullable to let undefined or null pass.

NORMALIZE AND TRANSFORM

Normalizing means cleaning a value before validation so that harmless differences (extra spaces, uppercase domain) do not cause failures. Transforming means converting a value after validation into the shape your code wants. Both wrap a plain function and turn any exception it throws into a validation failure instead of a crash.

This example cleans an email address, then validates a string and upper-cases it in one call.

Built-in string normalizers: normalizeTrim, normalizeWhitespace, normalizeLowercase, normalizeUppercase, normalizeUnicode (NFC), normalizeUnicodeCompatibility (NFKC), foldCase, normalizeEmail, normalizeUrl, normalizeIdentifier, normalizeQuotes, removeBom, and normalizeArray(values, fn) for lists. A normalizer object also has safeNormalize(), which returns a result instead of throwing.

Transformer helpers: createValidationTransformer(fn) gives you transform() and safeTransform(); composeTransforms(a, b) chains two; withTransformer(schema, fn) returns a new Zod schema that applies fn to parsed data. Async versions exist for each: createAsyncNormalizer, createAsyncValidationTransformer, validateAndTransformAsync.

REGISTRY AND FACTORY

A registry is a named collection of rules. You register a schema or a list of constraints under a string name once, then validate by name anywhere. This is useful when the rule name comes from data, for example a field type in a form definition.

This example registers two rules and validates against each by name. A rule with both schema and constraints runs both: the schema first, then the constraints on its output.

Registering a name twice throws unless you pass { overwrite: true }. Other methods: register(rule), get(name), require(name) (throws if absent), unregister(name), entries(), size, clear(), clone(), extend(otherRegistry), and readonly() which returns a view that can look up and validate but not change anything.

A ValidationFactory is a convenience object that bundles a registry with short methods for everything on this page: factory.parser(schema), factory.composer(steps), factory.constraint(fn, options), factory.validate(schema, value), factory.registerSchema(name, schema), factory.validateRegistered(name, value) and so on. Create one with createValidationFactory().

STRUCTURAL GUARDS

A schema checks what a value contains. A structural guard checks whether the value is safe to walk at all. Deeply nested JSON can overflow the call stack, a huge object can exhaust memory, and an object that refers to itself can loop forever in a serializer. Run these guards on raw input before schema validation.

Each guard stops the moment its limit is passed, so a hostile payload costs you the limit, not the payload's full size. The size guard measures an object's toJSON() output when it has one; the cycle and depth guards walk shared subtrees once.

Too-deep input is a 400

These guards exist to check input from outside your program, so a payload that nests too deep is the client's mistake, not a crash in your server. assertDepthWithinLimit and assertNoCircularReference therefore throw SerializationDepthError with statusCode: 400 and expose: true. Exposed means the message is safe to send back to the caller; it contains only the depth that was found and the limit, never any of the payload.

An HTTP layer that honours an error's status turns it into a 400 Bad Request with no extra code. Here is a @zudojs/http handler that guards its body before using it:

Before v1.1.0 the same request was answered 500 Internal Server Error: the error was an unexposed server error, so a client that sent bad input saw what looked like your bug. The error class did not change, so instanceof SerializationDepthError checks still match. @zudojs/serialization calls these guards, so a depth failure from JSONSerializer (serialize or deserialize) is now a 400 as well.

The options the guards pass are exported as UNTRUSTED_DEPTH_ERROR ({ statusCode: 400, expose: true }). SerializationDepthError from @zudojs/errors takes them as an optional third argument; constructed without it, the error is still an unexposed 500, which is right when your own code, not a client, built the too-deep value:

The size and cycle guards are unchanged: assertSizeWithinLimit still throws SerializationPayloadTooLargeError (413) and a cycle is still CircularReferenceError (500). Neither is exposed.

The size budget

estimateSerializedSize(value, maxBytes?) charges every occurrence of a value, the way a serializer expands it. The cycle and depth guards can memoise a shared subtree and visit it once; the size estimate cannot, so a graph of n shared { a: node, b: node } pairs expands to 2^n visits. The budget is the only thing that bounds that work.

maxBytes therefore defaults to SerializationLimits.MAX_SIZE — 10,485,760 bytes (10 MB) — from @zudojs/constants. The walk stops at the first node that carries the running total past the budget, and that total is what comes back: a figure at or just past maxBytes, not the true size. It never throws and never runs unbounded. Treat a result that has reached the budget as "at least this big" rather than as a measurement. If you need an exact figure for input you trust, pass Number.POSITIVE_INFINITY explicitly.

The three error classes come from @zudojs/errors. MAX_MEASURABLE_DEPTH (512) is the ceiling the measuring functions use when you give no limit. The same object appearing twice as siblings is a shared reference, not a cycle, and is allowed.

API REFERENCE

Everything below is exported from @zudojs/validation. Constraints, normalizers and pipeline helpers are listed in their sections above.

Schema functions

Result helpers

Classes and factories

Errors and types

COMMON MISTAKES

• Reading result.data without checking success → TypeScript types data as unknown, and on a failure it is undefined at runtime → Always branch on if (result.success) first, or use parse() when you want a throw.
• Passing a @zudojs/schema schema to validate() → a type error, and a crash on invalid input because validate expects a Zod schema → Use z.object(...) from this package, or call .safeParse() on the @zudojs/schema schema directly.
• Writing a custom constraint without a guard → wrong-typed input reaches your function; a throw inside it is caught and reported as a plain failure, but a non-throwing check such as value >= 18 silently compares a string → Pass guard in createConstraint options so non-numbers fail cleanly.
• Expecting the rejected value inside an issue → constraint issues never include the value, on purpose: errors are exposed with a 400 and would echo passwords and tokens → Log the value yourself where it is safe to do so.
• Validating first, guarding second → a 20,000-level payload crashes the process before the schema runs → Call assertDepthWithinLimit and assertSizeWithinLimit on the raw body before validate().
• Sharing one registry across modules and calling clear() → another module's rules vanish silently → Give each module createScopedValidationFactory(parent) and never clear a shared registry.

RELATED PACKAGES

• → @zudojs/schema — Zudo's own schema builder, when you do not want a Zod dependency.
• → @zudojs/errors — the BaseError every validation error extends, plus the depth, size and circular-reference errors.
• → @zudojs/http — where request bodies come from; validate them at the handler boundary.
• → @zudojs/config — configuration loading, another place a schema check pays off at startup.
• → @zudojs/serialization — converting values to and from JSON once they are known to be safe.

COMPLETE EXPORT INDEX

Every name @zudojs/validation exports from its package root at v1.1.0 — 179 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.