API reference > @kontsedal/olas-zod

olas-zod package

Functions

Function	Description
createZodForm(ctx, schema, options)	Walk a Zod schema and emit the equivalent Olas Form / FieldArray / Field tree, with validators auto-attached. z.object(...) → Form - z.array(...) → FieldArray (recurses on the element) - leaf schemas → Field with zodValidator(...) attached Each leaf's initial value is the Zod default if present, otherwise an empty value for that type ('' for strings, 0 for numbers, etc.). A.default(...) on an object or an array seeds that nested form or field array as a whole, as schema.parse({}) fills the key. A rule on an object or an array is enforced too. A root .refine(fn) lands in form.topLevelErrors, a .refine(fn, { path: ['confirm'] }) lands on confirm, and z.array(...).min(3) lands in that array'stopLevelErrors. The form parses the whole schema for these on every change, so a schema with no such rule does not get that validator. The return type is structurally precise — form.fields.title.value isstring (not string | boolean | …), form.fields.subtasks.add(...) accepts the exact item shape, etc. Consumers do not need to hand-write a CardForm = Form<{...}> matching the schema.
rootOnlyZodValidator(schema)	Run the schema and report only its first **root-level** issue, one with an empty path. Every issue with a path is dropped, on the assumption that each leaf field carries its own validator and reports it there. For a hand-built createForm whose leaves validate themselves.createZodForm does not use it: it installs a validator that also routes a path-carrying rule, such as .refine(fn, { path: ['confirm'] }) or an array's .min(3), onto the node the path names. Returns null when the schema has no root-level issue.
zodValidator(schema)	Wrap a Zod schema as an Olas validator. Zod 4 implements Standard Schema v1, so this is now a thin alias over the cross-library validator(...) from @kontsedal/olas-core. Kept under its existing name for back-compat and for code that intentionally signals "this is a Zod schema."
zodValidatorAsync(schema)	Async variant for schemas with .refine(async ...) or .transform(async ...). Returns a Promise<string | null>. Zod has no native cancellation surface, so we race safeParseAsync against the supplied signal and throw an AbortError if the signal fires. The validator runner filters AbortError via isAbortError, so a superseded pass never writes its result back.

Type Aliases

Type Alias	Description
ExtraValidators	Per-leaf extra validators keyed by dotted path. Match the leaf field's position inside the schema: top-level: 'title' - nested form: 'address.street' A path names a position in the SCHEMA, not in the value, and an array contributes no segment to it. So a path at or under an array applies to every element: z.array(z.string()) under tags → 'tags' validates each tag - z.array(z.object({ name })) under tags → 'tags.name' validates each item's name field There is no path that addresses the FieldArray itself. Put an array-level rule, such as "at least three tags" or "no duplicates", in the Zod schema instead: z.array(...).min(3) or z.array(...).refine(fn).createZodForm enforces it, and its message lands in the array'stopLevelErrors. Validators run alongside zodValidator(schema) — both must pass.
UnwrapZod	A Zod schema with its .default(), .optional() and .nullable() wrappers stripped — the type-level twin of the runtime unwrap createZodForm does before choosing a leaf.
ZodFormOptions	Options for createZodForm(ctx, schema, options?).
ZodToLeaf	Recursively map a Zod schema to its Olas form leaf: - ZodObject<S> → Form<{ [K]: ZodToLeaf<S[K]> }> - ZodArray<E> → FieldArray<ZodToLeaf<E>> (when E is object/array) or FieldArray<Field<infer<E>>> for primitive elements. - everything else → Field<infer<S>>. ZodToLeaf<S> matches what buildLeaf(ctx, s, ...) returns at runtime, so the public createZodForm<T> can publish a precise structural type without the consumer needing a hand-written CardForm = Form<{...}> cast.