API Overview

// Encode and decode
encode(schema, value, options?): Uint8Array;
decode(schema, bytes, options?): Output;

safeEncode(schema, value, options?): SafeResult<Uint8Array>;
safeDecode(schema, bytes, options?): SafeResult<Output>;

encodeAsync(schema, value, options?): Promise<Uint8Array>;
decodeAsync(schema, bytes, options?): Promise<Output>;

// Codecs
compile(schema, options?): Schema<Output>;
fingerprinted(codec, options?): FingerprintedSchema<Output>;

// Low-level
m.string() | m.bytes() | m.boolean() | m.uint() | m.int()
  | m.float32() | m.float64() | m.literal(v) | m.enum([...])
  | m.array(item) | m.tuple([...]) | m.object({...});

// Errors
EncodeError;
DecodeError; // .offset

codec and fromStandard are aliases of compile.

Choosing an entry point

Situation	Use
Ordinary code, throwing is fine	encode / decode
Untrusted input	safeEncode / safeDecode
Async refinement	encodeAsync / decodeAsync
A codec object to pass around	compile
Stored, queued, version-crossing	fingerprinted(compile(schema))
No validator, or you need bytes/float32	m

All entry points use the same structural decode path through Schema.decode, so they report the same errors.

Options

interface CompileOptions {
  readonly structure: StandardJSONSchemaV1;
}

interface FingerprintOptions {
  readonly bytes?: 1 | 2 | 3 | 4; // default 3
}

{ structure } is required for validators implementing Standard Schema but not Standard JSON Schema — Valibot always, Zod before 4.2, ArkType before 2.1.28.

Types

type SafeResult<T> =
  | { success: true; data: T }
  | { success: false; error: Error };

type EncodableStandardSchema<In = unknown, Out = In> =
  StandardSchemaV1<In, Out> & StandardJSONSchemaV1<In, Out>;

type Infer<S extends Schema<unknown>> = S["_output"];

Infer reads the output type off a low-level m codec. For schema-backed codecs use your validator’s inference (z.infer, v.InferOutput, typeof T.infer).

Also exported: Schema, OptionalSchema, NullableSchema, FingerprintedSchema, Reader, Writer, ObjectOutput, Shape, CompileOptions, FingerprintOptions.

The three-line version

const Person = z.object({ name: z.string(), age: z.int().nonnegative() });

export const wire = compile(Person);                 // pinned RPC
export const stored = fingerprinted(compile(Person)); // stored or queued

Reference

Functions · m Builders · Errors