Class Typer<TRegistry>

creates the types mapping type-->function

Validators that convert before validating.

Query strings, form data and environment variables arrive as strings, so without these every HTTP handler rewrites the conversion by hand — which is exactly where the mistakes are made. Each one rejects what it cannot convert rather than inventing a value, which is the difference between these and the bare Number() / Boolean() they replace:

In a schema slot the converted value replaces the original, so the object that comes out of parse holds the numbers and dates, not the strings that arrived.

The standalone validators, pre-bound to this instance.

The schema API invites passing validators around as values, but { id: typer.isPositiveInteger } loses this and fails with an opaque "Cannot read properties of undefined" — even for input that is valid. These are bound, so they can be passed, destructured and stored freely.

Built on first access and cached. Binding all of them eagerly onto the instance was measured to slow every other method down several-fold, by pushing the object out of V8's fast property mode — hence the single lazily-populated slot.

Builds a validator for an array whose elements all satisfy element, optionally constraining the length.

Every failing element is reported, not just the first.

Validates and returns an array

Validates and returns a boolean

Validates and returns a number

Validates and returns an object

Assert that a value is of a specific type. Logs a warning if incorrect.

Validates and returns a string

Recursively validates an object against a nested schema.

Shares the closure compiler with parse and safeParse, so a schema validated here is compiled once and reused — and reports the same messages the other entry points do.

Builds a validator for a union whose members are told apart by a single key — the shape most API payloads use.

union tries each variant in turn, so its cost grows with the number of variants and its error lists every variant's failure. This reads the discriminant once and goes straight to the one variant that can possibly match, in constant time, and reports against that variant alone.

The variants are keyed by discriminant value, so the mapping is exact by construction — there is no literal to extract from a schema and no way to declare two variants with the same tag.

Expects a function to conform to specified input and output types.

Exports all registered types as a JSON string.

Registers a custom type and tracks it in the instance's type, so the alias becomes usable in compile-time-checked schemas and resolves to R in Infer.

This is the type-aware counterpart of registerType: same runtime behavior, but it returns a re-typed Typer instead of void. Chain the calls and keep the returned instance — it is the same object, only seen through a wider type.

Imports types from a JSON string.

Composable form of isInstanceOf.

Checks if the provided value matches one or more specified types.

Overloads:

• When called with a known built-in alias, the type guard is automatically inferred from TypeMap (e.g. "number" narrows to number).
• For custom registered types, an explicit generic T may be supplied.

Checks if the provided value matches one or more specified types.

Overloads:

• When called with a known built-in alias, the type guard is automatically inferred from TypeMap (e.g. "number" narrows to number).
• For custom registered types, an explicit generic T may be supplied.

Type-safe array validation

Checks if the provided parameter is an array of a specified type.

Checks that the parameter is a syntactically valid Base64 string. Supports both standard and URL-safe variants. Padding is required when requirePadding is true (default).

Type-safe boolean validation

Checks if the provided parameter is a valid email address.

Checks that the parameter is "empty": empty string (after trim), empty array, empty Map/Set, or object with no own enumerable keys.

Checks that the parameter is a finite number (rejects NaN and Infinity). Stricter than isType("number", x), which accepts NaN for compatibility with typeof x === "number".

Checks that the parameter is a valid CSS hex color (#RGB, #RGBA, #RRGGBB, or #RRGGBBAA).

Checks if the provided parameter is a number within a specified range.

Checks that the parameter is an instance of the given constructor. Type-safe alternative to writing value instanceof MyClass everywhere.

Checks if the provided parameter is an integer.

Checks that the parameter is a valid IP address, of either version.

Checks that the parameter is a valid IPv4 address (dotted-quad notation).

Checks that the parameter is a valid IPv6 address. Uses the URL constructor as a permissive parser: any string accepted as the host portion of http://[<addr>]/ is considered valid.

Checks that the parameter is a valid ISO 8601 date string and returns the parsed Date. Accepts the formats produced by Date#toISOString plus reasonable variants (e.g. with timezone offsets).

Checks that the parameter is structurally a JSON Web Token: three base64url segments separated by dots.

This validates the shape only — it does not verify the signature or decode the claims, and must not be used as an authentication check.

Checks that the length of a string or array falls within the given bounds.

Checks that the parameter is a MAC address in colon- or hyphen-separated form.

Checks if the provided parameter is a negative integer.

Checks if the provided parameter is a negative number.

Inverse of isEmpty: checks the parameter is a non-empty string, array, Map, Set, or object.

Checks if the provided parameter is a non-empty array.

Checks if the provided parameter is a non-empty string.

Type-safe number validation

Type-safe object validation

Checks if the provided parameter is one of the specified values.

Checks if the provided parameter is a valid phone number.

Checks that the parameter is a plain object (object literal or Object.create(null)). Rejects class instances, arrays, dates, maps, etc.

Checks that the parameter is a valid TCP/UDP port number (1–65535).

Port 0 is rejected: it is reserved and never a valid destination.

Checks if the provided parameter is a positive integer.

Checks if the provided parameter is a positive number.

Checks that the parameter is a Promise (or a thenable).

Checks that the parameter is a safe integer (within Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER).

Checks that the parameter is a valid Semantic Versioning 2.0.0 string, including optional pre-release and build metadata.

Checks that the parameter is a URL-friendly slug: lowercase alphanumeric groups separated by single hyphens.

Type-safe string validation

Check if the parameter matches one of the specified types.

Overloads:

• When called with a known built-in type alias (or array of aliases), the return type is inferred from TypeMap (e.g. "string" → string).
• Otherwise the caller can supply an explicit generic T, which falls back to unknown.

Check if the parameter matches one of the specified types.

Overloads:

• When called with a known built-in type alias (or array of aliases), the return type is inferred from TypeMap (e.g. "string" → string).
• Otherwise the caller can supply an explicit generic T, which falls back to unknown.

Checks if the provided parameter is a valid URL.

Checks that the parameter is a valid UUID (versions 1-5, RFC 4122).

Defers building a validator until first use, which is what makes self-referential (recursive) shapes expressible.

The factory runs at most once; the result is reused.

Get all registered types.

Builds a validator accepting only the listed literal values.

The returned validator narrows to the union of those literals, so it is the composable counterpart of isOneOf.

Checks that the parameter is a string matching the given regular expression.

Combines two schemas. Keys of extension win where the two overlap.

Wraps an existing validator so that null is also accepted and returned as-is. Useful as a building block for nullable schema fields.

Turns a schema into a Validator, so object shapes can be nested inside the other combinators.

The schema is compiled once and cached like any other, so this is as fast as calling parse directly.

The returned validator is also a Standard Schema, so it can be handed straight to tRPC, Hono, TanStack Form and friends.

Derives a schema without the listed keys — the complement of pick.

Wraps an existing validator so that undefined is also accepted. Useful for optional schema fields.

Universal "parse" entry point. Validates value against either:

• a built-in type alias ("string", "number", ...),
• an array of aliases (["string", "number"] → union),
• a Validator<T> function,
• or a Schema object.

Returns the value typed correctly. Throws a TypeError on failure.

No as const is needed when calling with a literal schema thanks to the <const S> parameter — the inferred type matches the schema.

Declare the schema once, outside the hot path. Compiled checkers are cached by schema object identity, so a literal written inside a handler is a new object on every call and is recompiled every time — about an order of magnitude slower (78 ns hoisted against 873 ns inline), with nothing to show for it:

const userSchema = typer.schema({ id: 'number' });   // once
app.post('/u', (req) => typer.parse(userSchema, req.body));

app.post('/u', (req) => typer.parse({ id: 'number' }, req.body)); // recompiles
Copy

Universal "parse" entry point. Validates value against either:

• a built-in type alias ("string", "number", ...),
• an array of aliases (["string", "number"] → union),
• a Validator<T> function,
• or a Schema object.

Returns the value typed correctly. Throws a TypeError on failure.

No as const is needed when calling with a literal schema thanks to the <const S> parameter — the inferred type matches the schema.

Declare the schema once, outside the hot path. Compiled checkers are cached by schema object identity, so a literal written inside a handler is a new object on every call and is recompiled every time — about an order of magnitude slower (78 ns hoisted against 873 ns inline), with nothing to show for it:

const userSchema = typer.schema({ id: 'number' });   // once
app.post('/u', (req) => typer.parse(userSchema, req.body));

app.post('/u', (req) => typer.parse({ id: 'number' }, req.body)); // recompiles
Copy

Universal "parse" entry point. Validates value against either:

• a built-in type alias ("string", "number", ...),
• an array of aliases (["string", "number"] → union),
• a Validator<T> function,
• or a Schema object.

Returns the value typed correctly. Throws a TypeError on failure.

No as const is needed when calling with a literal schema thanks to the <const S> parameter — the inferred type matches the schema.

Declare the schema once, outside the hot path. Compiled checkers are cached by schema object identity, so a literal written inside a handler is a new object on every call and is recompiled every time — about an order of magnitude slower (78 ns hoisted against 873 ns inline), with nothing to show for it:

const userSchema = typer.schema({ id: 'number' });   // once
app.post('/u', (req) => typer.parse(userSchema, req.body));

app.post('/u', (req) => typer.parse({ id: 'number' }, req.body)); // recompiles
Copy

Universal "parse" entry point. Validates value against either:

• a built-in type alias ("string", "number", ...),
• an array of aliases (["string", "number"] → union),
• a Validator<T> function,
• or a Schema object.

Returns the value typed correctly. Throws a TypeError on failure.

No as const is needed when calling with a literal schema thanks to the <const S> parameter — the inferred type matches the schema.

Declare the schema once, outside the hot path. Compiled checkers are cached by schema object identity, so a literal written inside a handler is a new object on every call and is recompiled every time — about an order of magnitude slower (78 ns hoisted against 873 ns inline), with nothing to show for it:

const userSchema = typer.schema({ id: 'number' });   // once
app.post('/u', (req) => typer.parse(userSchema, req.body));

app.post('/u', (req) => typer.parse({ id: 'number' }, req.body)); // recompiles
Copy

Derives a schema with every key optional, or only the listed ones.

A type-string slot simply gains the ? marker. Every other slot kind has no marker of its own in the schema language, so it is wrapped with optional — which means a nested schema or array slot made optional reports its failures as one custom issue at the slot's path, rather than one issue per offending field. Pass the keys you actually need if that matters.

Derives a schema with every key optional, or only the listed ones.

A type-string slot simply gains the ? marker. Every other slot kind has no marker of its own in the schema language, so it is wrapped with optional — which means a nested schema or array slot made optional reports its failures as one custom issue at the slot's path, rather than one issue per offending field. Pass the keys you actually need if that matters.

Derives a schema keeping only the listed keys.

Real applications derive schemas from each other constantly — CreateUserDto from UserDto — and rewriting the shape by hand means two copies that diverge at the first change.

Builds a validator for a dictionary object: any set of keys, all values satisfying value.

Rejects arrays and null, unlike the 'object' alias.

Keys that are dangerous to copy (__proto__, constructor, prototype) are dropped rather than written to the result: assigning out['__proto__'] would set the output's prototype instead of a field.