@kontsedal/olas-zod 0.0.1-rc.1 → 0.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 Zod ↔ Olas forms adapter. Two helpers — `zodValidator` (single field) and `formFromZod` (whole form, inferred from schema).
 
-Olas core stays Zod-free. This package has a peer dep on `zod ^3`.
+Olas core stays Zod-free. This package has a peer dep on `zod ^4`.
 
 ## Install
 
@@ -70,7 +70,7 @@ function formFromZod<S extends z.ZodObject<z.ZodRawShape>>(
 
 `zodValidator` runs `schema.safeParse(value)` and reports the first `ZodIssue`'s `message`. `zodValidatorAsync` awaits `.safeParseAsync(...)` for schemas with async `.refine` / `.transform`.
 
-Form-level `.refine(...)` on the root `z.object(...)` is attached as a top-level form validator (surfaces via `form.topLevelErrors`).
+Root-level `.refine(...)` rules on `z.object(...)` are **not** auto-promoted to a form-level validator today. Wire one manually with `ctx.form(fields, { validators: [zodValidator(schema)] })`, or assert on `form.isValid` for leaf-level rules. Tracked in [`../../BACKLOG.md`](../../BACKLOG.md).
 
 ## Limitation
 

package/dist/index.cjs

@@ -23,6 +23,23 @@ function zodValidatorAsync(schema) {
 		return result.error.issues[0]?.message ?? "Invalid";
 	};
 }
+/**
+* Run the schema and report only **root-level** issues (those with empty
+* `path`). Leaf issues are already covered by `zodValidator(propSchema)` on
+* each leaf field — surfacing them here would double-count.
+*
+* Used by `formFromZod` to lift root-level `.refine(...)` rules into a
+* form-level validator. Returns `null` when every issue belongs to a leaf
+* (or there are no issues at all).
+*/
+function rootOnlyZodValidator(schema) {
+	return (value, signal) => {
+		const result = schema.safeParse(value);
+		if (result.success) return null;
+		for (const issue of result.error.issues) if (issue.path.length === 0) return issue.message;
+		return null;
+	};
+}
 function unwrap(schema) {
 	let s = schema;
 	for (let i = 0; i < 5; i++) if (s instanceof zod.z.ZodDefault) s = s.def.innerType;
@@ -46,50 +63,36 @@ function defaultInitial(schema) {
 		return typeof first === "string" ? first : "";
 	}
 }
-/**
-* 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.).
-*
-* The return type is structurally precise — `form.fields.title.value` is
-* `string` (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.
-*/
 function formFromZod(ctx, schema, options) {
-	return buildForm(ctx, schema, options?.initials);
+	return buildForm(ctx, schema, options?.initials, "", options?.extraValidators, schema);
 }
-function buildForm(ctx, schema, initials) {
+function buildForm(ctx, schema, initials, path, extras, rootSchema) {
 	const shape = schema.shape;
 	const fields = {};
 	for (const key of Object.keys(shape)) {
 		const propSchema = shape[key];
 		const initial = initials?.[key];
-		fields[key] = buildLeaf(ctx, propSchema, initial);
+		fields[key] = buildLeaf(ctx, propSchema, initial, path === "" ? key : `${path}.${key}`, extras);
 	}
-	const formOpts = {};
-	const topLevelValidators = [];
-	if (topLevelValidators.length > 0) formOpts.validators = topLevelValidators;
-	return ctx.form(fields, formOpts);
+	if (rootSchema !== void 0) return ctx.form(fields, { validators: [rootOnlyZodValidator(rootSchema)] });
+	return ctx.form(fields);
 }
-function buildLeaf(ctx, schema, initial) {
+function buildLeaf(ctx, schema, initial, path, extras) {
 	const inner = unwrap(schema);
-	if (inner instanceof zod.z.ZodObject) return buildForm(ctx, inner, initial);
+	if (inner instanceof zod.z.ZodObject) return buildForm(ctx, inner, initial, path, extras);
 	if (inner instanceof zod.z.ZodArray) {
 		const elementSchema = inner.element;
-		return ctx.fieldArray((itemInitial) => buildLeaf(ctx, elementSchema, itemInitial), initial !== void 0 ? { initial } : void 0);
+		return ctx.fieldArray((itemInitial) => buildLeaf(ctx, elementSchema, itemInitial, path, extras), initial !== void 0 ? { initial } : void 0);
 	}
 	const ini = initial !== void 0 ? initial : defaultInitial(schema);
-	return ctx.field(ini, [zodValidator(schema)]);
+	const validators = [zodValidator(schema)];
+	const extra = extras?.[path];
+	if (extra !== void 0) validators.push(extra);
+	return ctx.field(ini, validators);
 }
 //#endregion
 exports.formFromZod = formFromZod;
+exports.rootOnlyZodValidator = rootOnlyZodValidator;
 exports.zodValidator = zodValidator;
 exports.zodValidatorAsync = zodValidatorAsync;
 

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["z"],"sources":["../src/index.ts"],"sourcesContent":["import type { Ctx, Field, FieldArray, Form, FormOptions, Validator } from '@kontsedal/olas-core'\nimport { z } from 'zod'\n\n/**\n * Wrap a Zod schema as an Olas validator. Returns a sync or async Validator\n * depending on whether the schema requires async parsing (e.g. `.refine(async ...)`).\n */\nexport function zodValidator<T>(schema: z.ZodType<T>): Validator<T> {\n  return (value, signal) => {\n    // signal isn't used by Zod (parsing is sync) — kept for interface parity.\n    void signal\n    const result = schema.safeParse(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n/**\n * Async variant for schemas with `.refine(async ...)` or `.transform(async ...)`.\n * Returns a Promise<string | null>.\n */\nexport function zodValidatorAsync<T>(schema: z.ZodType<T>): Validator<T> {\n  return async (value, signal) => {\n    void signal\n    const result = await schema.safeParseAsync(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n// Zod 4 typed every wrapper as `z.ZodType`-compatible; the public unwrap path\n// is `.unwrap()` for optional/nullable and `.def.innerType` for default.\ntype AnyZodType = z.ZodType\n\n// Strip the outer optional/nullable/default wrappers to find the inner schema.\nfunction unwrap(schema: AnyZodType): AnyZodType {\n  let s: AnyZodType = schema\n  // Unwrap default + optional + nullable, in any combination.\n  for (let i = 0; i < 5; i++) {\n    if (s instanceof z.ZodDefault) {\n      // ZodDefault stores the inner schema on `def.innerType`. The runtime\n      // shape is stable across 3.x and 4.x; the public type just shifts.\n      s = (s as unknown as { def: { innerType: AnyZodType } }).def.innerType\n    } else if (s instanceof z.ZodOptional) {\n      s = (s as z.ZodOptional<AnyZodType>).unwrap() as AnyZodType\n    } else if (s instanceof z.ZodNullable) {\n      s = (s as z.ZodNullable<AnyZodType>).unwrap() as AnyZodType\n    } else {\n      return s\n    }\n  }\n  return s\n}\n\nfunction defaultInitial(schema: AnyZodType): unknown {\n  // Honor Zod default if present.\n  if (schema instanceof z.ZodDefault) {\n    const raw = (schema as unknown as { def: { defaultValue: unknown } }).def.defaultValue\n    return typeof raw === 'function' ? (raw as () => unknown)() : raw\n  }\n  const inner = unwrap(schema)\n  if (inner instanceof z.ZodString) return ''\n  if (inner instanceof z.ZodNumber) return 0\n  if (inner instanceof z.ZodBoolean) return false\n  if (inner instanceof z.ZodArray) return []\n  if (inner instanceof z.ZodEnum) {\n    // Zod 4 widened ZodEnum's options to support record-style enums. The\n    // runtime values are still iterable; pick the first.\n    const opts = (inner as unknown as { options: readonly unknown[] }).options\n    const first = opts[0]\n    return typeof first === 'string' ? first : ''\n  }\n  // For unknown/any/dates etc., undefined is the safest starting point.\n  return undefined\n}\n\ntype AnyForm = Form<Record<string, Field<any> | Form<any> | FieldArray<any>>>\n\n// Strip the same wrappers as the runtime `unwrap` helper, at the type level.\ntype UnwrapZod<S> =\n  S extends z.ZodDefault<infer Inner>\n    ? UnwrapZod<Inner>\n    : S extends z.ZodOptional<infer Inner>\n      ? UnwrapZod<Inner>\n      : S extends z.ZodNullable<infer Inner>\n        ? UnwrapZod<Inner>\n        : S\n\n/**\n * Recursively map a Zod schema to its Olas form leaf:\n *  - `ZodObject<S>` → `Form<{ [K]: ZodToLeaf<S[K]> }>`\n *  - `ZodArray<E>`  → `FieldArray<ZodToLeaf<E>>` (when E is object/array)\n *                     or `FieldArray<Field<infer<E>>>` for primitive elements.\n *  - everything else → `Field<infer<S>>`.\n *\n * `ZodToLeaf<S>` matches what `buildLeaf(ctx, s, ...)` returns at runtime,\n * so the public `formFromZod<T>` can publish a precise structural type\n * without the consumer needing a hand-written `CardForm = Form<{...}>` cast.\n */\nexport type ZodToLeaf<S> =\n  UnwrapZod<S> extends z.ZodObject<infer RawShape>\n    ? Form<{ [K in keyof RawShape]: ZodToLeaf<RawShape[K]> }>\n    : UnwrapZod<S> extends z.ZodArray<infer Element>\n      ? FieldArray<ZodToLeaf<Element> extends Form<any> | Field<any> ? ZodToLeaf<Element> : never>\n      : Field<z.infer<UnwrapZod<S> & z.ZodType>>\n\n/**\n * Walk a Zod schema and emit the equivalent Olas Form / FieldArray / Field\n * tree, with validators auto-attached.\n *\n * - `z.object(...)` → `Form`\n * - `z.array(...)`  → `FieldArray` (recurses on the element)\n * - leaf schemas    → `Field` with `zodValidator(...)` attached\n *\n * Each leaf's initial value is the Zod default if present, otherwise an empty\n * value for that type (`''` for strings, `0` for numbers, etc.).\n *\n * The return type is structurally precise — `form.fields.title.value` is\n * `string` (not `string | boolean | …`), `form.fields.subtasks.add(...)`\n * accepts the exact item shape, etc. Consumers do not need to hand-write\n * a `CardForm = Form<{...}>` matching the schema.\n */\nexport function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(\n  ctx: Ctx,\n  schema: T,\n  options?: { initials?: Partial<z.infer<T>> },\n): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }> {\n  return buildForm(ctx, schema, options?.initials) as never\n}\n\nfunction buildForm(\n  ctx: Ctx,\n  schema: z.ZodObject<z.ZodRawShape>,\n  initials?: Record<string, unknown>,\n): AnyForm {\n  const shape = schema.shape\n  const fields: Record<string, Field<unknown> | Form<any> | FieldArray<any>> = {}\n  for (const key of Object.keys(shape)) {\n    const propSchema = shape[key] as AnyZodType\n    const initial = initials?.[key]\n    fields[key] = buildLeaf(ctx, propSchema, initial)\n  }\n  const formOpts: FormOptions<typeof fields> = {}\n  // If the schema has top-level refinements (z.object().refine(...)), Zod\n  // wraps it in ZodEffects. We expose those as form-level validators.\n  const topLevelValidators: Validator<unknown>[] = []\n  // Note: we received an unwrapped ZodObject here, so there's nothing extra.\n  if (topLevelValidators.length > 0) {\n    ;(formOpts as { validators: Validator<unknown>[] }).validators = topLevelValidators\n  }\n  return ctx.form(fields, formOpts) as AnyForm\n}\n\nfunction buildLeaf(\n  ctx: Ctx,\n  schema: AnyZodType,\n  initial: unknown,\n): Field<unknown> | Form<any> | FieldArray<any> {\n  const inner = unwrap(schema)\n\n  if (inner instanceof z.ZodObject) {\n    return buildForm(\n      ctx,\n      inner as z.ZodObject<z.ZodRawShape>,\n      initial as Record<string, unknown> | undefined,\n    )\n  }\n\n  if (inner instanceof z.ZodArray) {\n    const elementSchema = (inner as z.ZodArray<AnyZodType>).element as AnyZodType\n    return ctx.fieldArray(\n      (itemInitial) => buildLeaf(ctx, elementSchema, itemInitial) as Field<unknown> | Form<any>,\n      initial !== undefined ? { initial: initial as Array<unknown> } : undefined,\n    )\n  }\n\n  const ini = initial !== undefined ? initial : defaultInitial(schema)\n  return ctx.field(ini, [zodValidator(schema as z.ZodType<unknown>)])\n}\n"],"mappings":";;;;;;;AAOA,SAAgB,aAAgB,QAAoC;CAClE,QAAQ,OAAO,WAAW;EAGxB,MAAM,SAAS,OAAO,UAAU,KAAK;EACrC,IAAI,OAAO,SAAS,OAAO;EAC3B,OAAO,OAAO,MAAM,OAAO,IAAI,WAAW;CAC5C;AACF;;;;;AAMA,SAAgB,kBAAqB,QAAoC;CACvE,OAAO,OAAO,OAAO,WAAW;EAE9B,MAAM,SAAS,MAAM,OAAO,eAAe,KAAK;EAChD,IAAI,OAAO,SAAS,OAAO;EAC3B,OAAO,OAAO,MAAM,OAAO,IAAI,WAAW;CAC5C;AACF;AAOA,SAAS,OAAO,QAAgC;CAC9C,IAAI,IAAgB;CAEpB,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KACrB,IAAI,aAAaA,IAAAA,EAAE,YAGjB,IAAK,EAAoD,IAAI;MACxD,IAAI,aAAaA,IAAAA,EAAE,aACxB,IAAK,EAAgC,OAAO;MACvC,IAAI,aAAaA,IAAAA,EAAE,aACxB,IAAK,EAAgC,OAAO;MAE5C,OAAO;CAGX,OAAO;AACT;AAEA,SAAS,eAAe,QAA6B;CAEnD,IAAI,kBAAkBA,IAAAA,EAAE,YAAY;EAClC,MAAM,MAAO,OAAyD,IAAI;EAC1E,OAAO,OAAO,QAAQ,aAAc,IAAsB,IAAI;CAChE;CACA,MAAM,QAAQ,OAAO,MAAM;CAC3B,IAAI,iBAAiBA,IAAAA,EAAE,WAAW,OAAO;CACzC,IAAI,iBAAiBA,IAAAA,EAAE,WAAW,OAAO;CACzC,IAAI,iBAAiBA,IAAAA,EAAE,YAAY,OAAO;CAC1C,IAAI,iBAAiBA,IAAAA,EAAE,UAAU,OAAO,CAAC;CACzC,IAAI,iBAAiBA,IAAAA,EAAE,SAAS;EAI9B,MAAM,QADQ,MAAqD,QAChD;EACnB,OAAO,OAAO,UAAU,WAAW,QAAQ;CAC7C;AAGF;;;;;;;;;;;;;;;;;AAgDA,SAAgB,YACd,KACA,QACA,SAC6D;CAC7D,OAAO,UAAU,KAAK,QAAQ,SAAS,QAAQ;AACjD;AAEA,SAAS,UACP,KACA,QACA,UACS;CACT,MAAM,QAAQ,OAAO;CACrB,MAAM,SAAuE,CAAC;CAC9E,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GAAG;EACpC,MAAM,aAAa,MAAM;EACzB,MAAM,UAAU,WAAW;EAC3B,OAAO,OAAO,UAAU,KAAK,YAAY,OAAO;CAClD;CACA,MAAM,WAAuC,CAAC;CAG9C,MAAM,qBAA2C,CAAC;CAElD,IAAI,mBAAmB,SAAS,GAC7B,SAAmD,aAAa;CAEnE,OAAO,IAAI,KAAK,QAAQ,QAAQ;AAClC;AAEA,SAAS,UACP,KACA,QACA,SAC8C;CAC9C,MAAM,QAAQ,OAAO,MAAM;CAE3B,IAAI,iBAAiBA,IAAAA,EAAE,WACrB,OAAO,UACL,KACA,OACA,OACF;CAGF,IAAI,iBAAiBA,IAAAA,EAAE,UAAU;EAC/B,MAAM,gBAAiB,MAAiC;EACxD,OAAO,IAAI,YACR,gBAAgB,UAAU,KAAK,eAAe,WAAW,GAC1D,YAAY,KAAA,IAAY,EAAW,QAA0B,IAAI,KAAA,CACnE;CACF;CAEA,MAAM,MAAM,YAAY,KAAA,IAAY,UAAU,eAAe,MAAM;CACnE,OAAO,IAAI,MAAM,KAAK,CAAC,aAAa,MAA4B,CAAC,CAAC;AACpE"}
+{"version":3,"file":"index.cjs","names":["z"],"sources":["../src/index.ts"],"sourcesContent":["import type { Ctx, Field, FieldArray, Form, Validator } from '@kontsedal/olas-core'\nimport { z } from 'zod'\n\n/**\n * Wrap a Zod schema as an Olas validator. Returns a sync or async Validator\n * depending on whether the schema requires async parsing (e.g. `.refine(async ...)`).\n */\nexport function zodValidator<T>(schema: z.ZodType<T>): Validator<T> {\n  return (value, signal) => {\n    // signal isn't used by Zod (parsing is sync) — kept for interface parity.\n    void signal\n    const result = schema.safeParse(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n/**\n * Async variant for schemas with `.refine(async ...)` or `.transform(async ...)`.\n * Returns a Promise<string | null>.\n */\nexport function zodValidatorAsync<T>(schema: z.ZodType<T>): Validator<T> {\n  return async (value, signal) => {\n    void signal\n    const result = await schema.safeParseAsync(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n/**\n * Run the schema and report only **root-level** issues (those with empty\n * `path`). Leaf issues are already covered by `zodValidator(propSchema)` on\n * each leaf field — surfacing them here would double-count.\n *\n * Used by `formFromZod` to lift root-level `.refine(...)` rules into a\n * form-level validator. Returns `null` when every issue belongs to a leaf\n * (or there are no issues at all).\n */\nexport function rootOnlyZodValidator<T>(schema: z.ZodType<T>): Validator<T> {\n  return (value, signal) => {\n    void signal\n    const result = schema.safeParse(value)\n    if (result.success) return null\n    for (const issue of result.error.issues) {\n      if (issue.path.length === 0) return issue.message\n    }\n    return null\n  }\n}\n\n// Zod 4 typed every wrapper as `z.ZodType`-compatible; the public unwrap path\n// is `.unwrap()` for optional/nullable and `.def.innerType` for default.\ntype AnyZodType = z.ZodType\n\n// Strip the outer optional/nullable/default wrappers to find the inner schema.\nfunction unwrap(schema: AnyZodType): AnyZodType {\n  let s: AnyZodType = schema\n  // Unwrap default + optional + nullable, in any combination.\n  for (let i = 0; i < 5; i++) {\n    if (s instanceof z.ZodDefault) {\n      // ZodDefault stores the inner schema on `def.innerType`. The runtime\n      // shape is stable across 3.x and 4.x; the public type just shifts.\n      s = (s as unknown as { def: { innerType: AnyZodType } }).def.innerType\n    } else if (s instanceof z.ZodOptional) {\n      s = (s as z.ZodOptional<AnyZodType>).unwrap() as AnyZodType\n    } else if (s instanceof z.ZodNullable) {\n      s = (s as z.ZodNullable<AnyZodType>).unwrap() as AnyZodType\n    } else {\n      return s\n    }\n  }\n  return s\n}\n\nfunction defaultInitial(schema: AnyZodType): unknown {\n  // Honor Zod default if present.\n  if (schema instanceof z.ZodDefault) {\n    const raw = (schema as unknown as { def: { defaultValue: unknown } }).def.defaultValue\n    return typeof raw === 'function' ? (raw as () => unknown)() : raw\n  }\n  const inner = unwrap(schema)\n  if (inner instanceof z.ZodString) return ''\n  if (inner instanceof z.ZodNumber) return 0\n  if (inner instanceof z.ZodBoolean) return false\n  if (inner instanceof z.ZodArray) return []\n  if (inner instanceof z.ZodEnum) {\n    // Zod 4 widened ZodEnum's options to support record-style enums. The\n    // runtime values are still iterable; pick the first.\n    const opts = (inner as unknown as { options: readonly unknown[] }).options\n    const first = opts[0]\n    return typeof first === 'string' ? first : ''\n  }\n  // For unknown/any/dates etc., undefined is the safest starting point.\n  return undefined\n}\n\ntype AnyForm = Form<Record<string, Field<any> | Form<any> | FieldArray<any>>>\n\n// Strip the same wrappers as the runtime `unwrap` helper, at the type level.\ntype UnwrapZod<S> =\n  S extends z.ZodDefault<infer Inner>\n    ? UnwrapZod<Inner>\n    : S extends z.ZodOptional<infer Inner>\n      ? UnwrapZod<Inner>\n      : S extends z.ZodNullable<infer Inner>\n        ? UnwrapZod<Inner>\n        : S\n\n/**\n * Recursively map a Zod schema to its Olas form leaf:\n *  - `ZodObject<S>` → `Form<{ [K]: ZodToLeaf<S[K]> }>`\n *  - `ZodArray<E>`  → `FieldArray<ZodToLeaf<E>>` (when E is object/array)\n *                     or `FieldArray<Field<infer<E>>>` for primitive elements.\n *  - everything else → `Field<infer<S>>`.\n *\n * `ZodToLeaf<S>` matches what `buildLeaf(ctx, s, ...)` returns at runtime,\n * so the public `formFromZod<T>` can publish a precise structural type\n * without the consumer needing a hand-written `CardForm = Form<{...}>` cast.\n */\nexport type ZodToLeaf<S> =\n  UnwrapZod<S> extends z.ZodObject<infer RawShape>\n    ? Form<{ [K in keyof RawShape]: ZodToLeaf<RawShape[K]> }>\n    : UnwrapZod<S> extends z.ZodArray<infer Element>\n      ? FieldArray<ZodToLeaf<Element> extends Form<any> | Field<any> ? ZodToLeaf<Element> : never>\n      : Field<z.infer<UnwrapZod<S> & z.ZodType>>\n\n/**\n * Walk a Zod schema and emit the equivalent Olas Form / FieldArray / Field\n * tree, with validators auto-attached.\n *\n * - `z.object(...)` → `Form`\n * - `z.array(...)`  → `FieldArray` (recurses on the element)\n * - leaf schemas    → `Field` with `zodValidator(...)` attached\n *\n * Each leaf's initial value is the Zod default if present, otherwise an empty\n * value for that type (`''` for strings, `0` for numbers, etc.).\n *\n * The return type is structurally precise — `form.fields.title.value` is\n * `string` (not `string | boolean | …`), `form.fields.subtasks.add(...)`\n * accepts the exact item shape, etc. Consumers do not need to hand-write\n * a `CardForm = Form<{...}>` matching the schema.\n */\n/**\n * Per-leaf extra validators keyed by dotted path. Match the leaf field's\n * position inside the schema:\n *\n * - top-level: `'title'`\n * - nested form: `'address.street'`\n *\n * `FieldArray` items aren't separately addressable — the schema walker\n * generates one factory per array, so a path of `'tags'` matches the\n * `FieldArray` (validators attached there apply to the array as a whole;\n * use Olas's `FieldArrayOptions.validators` shape). Per-element rules\n * already live on the Zod element schema and are attached automatically.\n *\n * Validators run alongside `zodValidator(schema)` — both must pass.\n */\nexport type ExtraValidators = Record<string, Validator<any>>\n\nexport type FormFromZodOptions<T extends z.ZodObject<z.ZodRawShape>> = {\n  initials?: Partial<z.infer<T>>\n  extraValidators?: ExtraValidators\n}\n\nexport function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(\n  ctx: Ctx,\n  schema: T,\n  options?: FormFromZodOptions<T>,\n): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }> {\n  return buildForm(ctx, schema, options?.initials, '', options?.extraValidators, schema) as never\n}\n\nfunction buildForm(\n  ctx: Ctx,\n  schema: z.ZodObject<z.ZodRawShape>,\n  initials: Record<string, unknown> | undefined,\n  path: string,\n  extras: ExtraValidators | undefined,\n  /**\n   * The original top-level schema. Passed only when constructing the ROOT\n   * form — nested `buildForm` calls (from object-typed leaves) pass\n   * `undefined`. Used to attach a root-only Zod validator so\n   * `z.object({...}).refine(fn)` rules surface as form-level errors\n   * without double-reporting leaf issues. See `rootOnlyZodValidator`.\n   */\n  rootSchema?: z.ZodObject<z.ZodRawShape>,\n): AnyForm {\n  const shape = schema.shape\n  const fields: Record<string, Field<unknown> | Form<any> | FieldArray<any>> = {}\n  for (const key of Object.keys(shape)) {\n    const propSchema = shape[key] as AnyZodType\n    const initial = initials?.[key]\n    const leafPath = path === '' ? key : `${path}.${key}`\n    fields[key] = buildLeaf(ctx, propSchema, initial, leafPath, extras)\n  }\n  // Lift root-level `.refine(...)` checks on the top-level object into a\n  // form-level validator. Leaf checks remain owned by leaf-level\n  // `zodValidator(propSchema)`; `rootOnlyZodValidator` filters to issues\n  // whose `path` is empty so leaf issues are not double-reported.\n  if (rootSchema !== undefined) {\n    return ctx.form(fields, {\n      validators: [rootOnlyZodValidator(rootSchema as z.ZodType<unknown>) as never],\n    }) as AnyForm\n  }\n  return ctx.form(fields) as AnyForm\n}\n\nfunction buildLeaf(\n  ctx: Ctx,\n  schema: AnyZodType,\n  initial: unknown,\n  path: string,\n  extras: ExtraValidators | undefined,\n): Field<unknown> | Form<any> | FieldArray<any> {\n  const inner = unwrap(schema)\n\n  if (inner instanceof z.ZodObject) {\n    return buildForm(\n      ctx,\n      inner as z.ZodObject<z.ZodRawShape>,\n      initial as Record<string, unknown> | undefined,\n      path,\n      extras,\n    )\n  }\n\n  if (inner instanceof z.ZodArray) {\n    const elementSchema = (inner as z.ZodArray<AnyZodType>).element as AnyZodType\n    return ctx.fieldArray(\n      // Array items aren't enumerable at schema-build time; we don't extend\n      // the dotted path with an index here. Per-item validators belong on\n      // the Zod element schema (which `buildLeaf` already wraps via\n      // `zodValidator`).\n      (itemInitial) =>\n        buildLeaf(ctx, elementSchema, itemInitial, path, extras) as Field<unknown> | Form<any>,\n      initial !== undefined ? { initial: initial as Array<unknown> } : undefined,\n    )\n  }\n\n  const ini = initial !== undefined ? initial : defaultInitial(schema)\n  const validators: Array<Validator<unknown>> = [zodValidator(schema as z.ZodType<unknown>)]\n  const extra = extras?.[path]\n  if (extra !== undefined) validators.push(extra as Validator<unknown>)\n  return ctx.field(ini, validators)\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -12,6 +12,16 @@ declare function zodValidator<T>(schema: z.ZodType<T>): Validator<T>;
  * Returns a Promise<string | null>.
  */
 declare function zodValidatorAsync<T>(schema: z.ZodType<T>): Validator<T>;
+/**
+ * Run the schema and report only **root-level** issues (those with empty
+ * `path`). Leaf issues are already covered by `zodValidator(propSchema)` on
+ * each leaf field — surfacing them here would double-count.
+ *
+ * Used by `formFromZod` to lift root-level `.refine(...)` rules into a
+ * form-level validator. Returns `null` when every issue belongs to a leaf
+ * (or there are no issues at all).
+ */
+declare function rootOnlyZodValidator<T>(schema: z.ZodType<T>): Validator<T>;
 type UnwrapZod<S> = S extends z.ZodDefault<infer Inner> ? UnwrapZod<Inner> : S extends z.ZodOptional<infer Inner> ? UnwrapZod<Inner> : S extends z.ZodNullable<infer Inner> ? UnwrapZod<Inner> : S;
 /**
  * Recursively map a Zod schema to its Olas form leaf:
@@ -41,9 +51,27 @@ type ZodToLeaf<S> = UnwrapZod<S> extends z.ZodObject<infer RawShape> ? Form<{ [K
  * accepts the exact item shape, etc. Consumers do not need to hand-write
  * a `CardForm = Form<{...}>` matching the schema.
  */
-declare function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(ctx: Ctx, schema: T, options?: {
+/**
+ * Per-leaf extra validators keyed by dotted path. Match the leaf field's
+ * position inside the schema:
+ *
+ * - top-level: `'title'`
+ * - nested form: `'address.street'`
+ *
+ * `FieldArray` items aren't separately addressable — the schema walker
+ * generates one factory per array, so a path of `'tags'` matches the
+ * `FieldArray` (validators attached there apply to the array as a whole;
+ * use Olas's `FieldArrayOptions.validators` shape). Per-element rules
+ * already live on the Zod element schema and are attached automatically.
+ *
+ * Validators run alongside `zodValidator(schema)` — both must pass.
+ */
+type ExtraValidators = Record<string, Validator<any>>;
+type FormFromZodOptions<T extends z.ZodObject<z.ZodRawShape>> = {
   initials?: Partial<z.infer<T>>;
-}): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }>;
+  extraValidators?: ExtraValidators;
+};
+declare function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(ctx: Ctx, schema: T, options?: FormFromZodOptions<T>): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }>;
 //#endregion
-export { ZodToLeaf, formFromZod, zodValidator, zodValidatorAsync };
+export { ExtraValidators, FormFromZodOptions, ZodToLeaf, formFromZod, rootOnlyZodValidator, zodValidator, zodValidatorAsync };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AAOA;;iBAAgB,YAAA,GAAA,CAAgB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;;;;;iBAcjD,iBAAA,GAAA,CAAqB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;AAAA,KA0DjE,SAAA,MACH,CAAA,SAAU,CAAA,CAAE,UAAA,gBACR,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA;;;;;;;;;AA/EwD;AAclE;;KA8EY,SAAA,MACV,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,SAAA,mBACnB,IAAA,eAAmB,QAAA,GAAW,SAAA,CAAU,QAAA,CAAS,CAAA,QACjD,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,QAAA,kBACrB,UAAA,CAAW,SAAA,CAAU,OAAA,UAAiB,IAAA,QAAY,KAAA,QAAa,SAAA,CAAU,OAAA,aACzE,KAAA,CAAM,CAAA,CAAE,KAAA,CAAM,SAAA,CAAU,CAAA,IAAK,CAAA,CAAE,OAAA;;;;;;;;;;;;;AAnFgC;AAOtE;;;iBA8Fe,WAAA,WAAsB,CAAA,CAAE,SAAA,CAAU,CAAA,CAAE,WAAA,EAAA,CAClD,GAAA,EAAK,GAAA,EACL,MAAA,EAAQ,CAAA,EACR,OAAA;EAAY,QAAA,GAAW,OAAA,CAAQ,CAAA,CAAE,KAAA,CAAM,CAAA;AAAA,IACtC,IAAA,eAAmB,CAAA,YAAa,SAAA,CAAU,CAAA,UAAW,CAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AAOA;;iBAAgB,YAAA,GAAA,CAAgB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;;;;;iBAcjD,iBAAA,GAAA,CAAqB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;;;;;;;;;;iBAkBtD,oBAAA,GAAA,CAAwB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;AAAA,KA6DpE,SAAA,MACH,CAAA,SAAU,CAAA,CAAE,UAAA,gBACR,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA;;;;;;;;;;;;KAaE,SAAA,MACV,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,SAAA,mBACnB,IAAA,eAAmB,QAAA,GAAW,SAAA,CAAU,QAAA,CAAS,CAAA,QACjD,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,QAAA,kBACrB,UAAA,CAAW,SAAA,CAAU,OAAA,UAAiB,IAAA,QAAY,KAAA,QAAa,SAAA,CAAU,OAAA,aACzE,KAAA,CAAM,CAAA,CAAE,KAAA,CAAM,SAAA,CAAU,CAAA,IAAK,CAAA,CAAE,OAAA;;;AAxGgC;AAkBvE;;;;;;;;;;;;;;;;;AAA0E;AAUzE;;;;;;;;;;KA6GW,eAAA,GAAkB,MAAM,SAAS,SAAA;AAAA,KAEjC,kBAAA,WAA6B,CAAA,CAAE,SAAA,CAAU,CAAA,CAAE,WAAA;EACrD,QAAA,GAAW,OAAA,CAAQ,CAAA,CAAE,KAAA,CAAM,CAAA;EAC3B,eAAA,GAAkB,eAAA;AAAA;AAAA,iBAGJ,WAAA,WAAsB,CAAA,CAAE,SAAA,CAAU,CAAA,CAAE,WAAA,EAAA,CAClD,GAAA,EAAK,GAAA,EACL,MAAA,EAAQ,CAAA,EACR,OAAA,GAAU,kBAAA,CAAmB,CAAA,IAC5B,IAAA,eAAmB,CAAA,YAAa,SAAA,CAAU,CAAA,UAAW,CAAA"}

package/dist/index.d.mts

@@ -12,6 +12,16 @@ declare function zodValidator<T>(schema: z.ZodType<T>): Validator<T>;
  * Returns a Promise<string | null>.
  */
 declare function zodValidatorAsync<T>(schema: z.ZodType<T>): Validator<T>;
+/**
+ * Run the schema and report only **root-level** issues (those with empty
+ * `path`). Leaf issues are already covered by `zodValidator(propSchema)` on
+ * each leaf field — surfacing them here would double-count.
+ *
+ * Used by `formFromZod` to lift root-level `.refine(...)` rules into a
+ * form-level validator. Returns `null` when every issue belongs to a leaf
+ * (or there are no issues at all).
+ */
+declare function rootOnlyZodValidator<T>(schema: z.ZodType<T>): Validator<T>;
 type UnwrapZod<S> = S extends z.ZodDefault<infer Inner> ? UnwrapZod<Inner> : S extends z.ZodOptional<infer Inner> ? UnwrapZod<Inner> : S extends z.ZodNullable<infer Inner> ? UnwrapZod<Inner> : S;
 /**
  * Recursively map a Zod schema to its Olas form leaf:
@@ -41,9 +51,27 @@ type ZodToLeaf<S> = UnwrapZod<S> extends z.ZodObject<infer RawShape> ? Form<{ [K
  * accepts the exact item shape, etc. Consumers do not need to hand-write
  * a `CardForm = Form<{...}>` matching the schema.
  */
-declare function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(ctx: Ctx, schema: T, options?: {
+/**
+ * Per-leaf extra validators keyed by dotted path. Match the leaf field's
+ * position inside the schema:
+ *
+ * - top-level: `'title'`
+ * - nested form: `'address.street'`
+ *
+ * `FieldArray` items aren't separately addressable — the schema walker
+ * generates one factory per array, so a path of `'tags'` matches the
+ * `FieldArray` (validators attached there apply to the array as a whole;
+ * use Olas's `FieldArrayOptions.validators` shape). Per-element rules
+ * already live on the Zod element schema and are attached automatically.
+ *
+ * Validators run alongside `zodValidator(schema)` — both must pass.
+ */
+type ExtraValidators = Record<string, Validator<any>>;
+type FormFromZodOptions<T extends z.ZodObject<z.ZodRawShape>> = {
   initials?: Partial<z.infer<T>>;
-}): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }>;
+  extraValidators?: ExtraValidators;
+};
+declare function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(ctx: Ctx, schema: T, options?: FormFromZodOptions<T>): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }>;
 //#endregion
-export { ZodToLeaf, formFromZod, zodValidator, zodValidatorAsync };
+export { ExtraValidators, FormFromZodOptions, ZodToLeaf, formFromZod, rootOnlyZodValidator, zodValidator, zodValidatorAsync };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AAOA;;iBAAgB,YAAA,GAAA,CAAgB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;;;;;iBAcjD,iBAAA,GAAA,CAAqB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;AAAA,KA0DjE,SAAA,MACH,CAAA,SAAU,CAAA,CAAE,UAAA,gBACR,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA;;;;;;;;;AA/EwD;AAclE;;KA8EY,SAAA,MACV,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,SAAA,mBACnB,IAAA,eAAmB,QAAA,GAAW,SAAA,CAAU,QAAA,CAAS,CAAA,QACjD,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,QAAA,kBACrB,UAAA,CAAW,SAAA,CAAU,OAAA,UAAiB,IAAA,QAAY,KAAA,QAAa,SAAA,CAAU,OAAA,aACzE,KAAA,CAAM,CAAA,CAAE,KAAA,CAAM,SAAA,CAAU,CAAA,IAAK,CAAA,CAAE,OAAA;;;;;;;;;;;;;AAnFgC;AAOtE;;;iBA8Fe,WAAA,WAAsB,CAAA,CAAE,SAAA,CAAU,CAAA,CAAE,WAAA,EAAA,CAClD,GAAA,EAAK,GAAA,EACL,MAAA,EAAQ,CAAA,EACR,OAAA;EAAY,QAAA,GAAW,OAAA,CAAQ,CAAA,CAAE,KAAA,CAAM,CAAA;AAAA,IACtC,IAAA,eAAmB,CAAA,YAAa,SAAA,CAAU,CAAA,UAAW,CAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AAOA;;iBAAgB,YAAA,GAAA,CAAgB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;;;;;iBAcjD,iBAAA,GAAA,CAAqB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;;;;;;;;;;iBAkBtD,oBAAA,GAAA,CAAwB,MAAA,EAAQ,CAAA,CAAE,OAAA,CAAQ,CAAA,IAAK,SAAA,CAAU,CAAA;AAAA,KA6DpE,SAAA,MACH,CAAA,SAAU,CAAA,CAAE,UAAA,gBACR,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA,SAAU,CAAA,CAAE,WAAA,gBACV,SAAA,CAAU,KAAA,IACV,CAAA;;;;;;;;;;;;KAaE,SAAA,MACV,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,SAAA,mBACnB,IAAA,eAAmB,QAAA,GAAW,SAAA,CAAU,QAAA,CAAS,CAAA,QACjD,SAAA,CAAU,CAAA,UAAW,CAAA,CAAE,QAAA,kBACrB,UAAA,CAAW,SAAA,CAAU,OAAA,UAAiB,IAAA,QAAY,KAAA,QAAa,SAAA,CAAU,OAAA,aACzE,KAAA,CAAM,CAAA,CAAE,KAAA,CAAM,SAAA,CAAU,CAAA,IAAK,CAAA,CAAE,OAAA;;;AAxGgC;AAkBvE;;;;;;;;;;;;;;;;;AAA0E;AAUzE;;;;;;;;;;KA6GW,eAAA,GAAkB,MAAM,SAAS,SAAA;AAAA,KAEjC,kBAAA,WAA6B,CAAA,CAAE,SAAA,CAAU,CAAA,CAAE,WAAA;EACrD,QAAA,GAAW,OAAA,CAAQ,CAAA,CAAE,KAAA,CAAM,CAAA;EAC3B,eAAA,GAAkB,eAAA;AAAA;AAAA,iBAGJ,WAAA,WAAsB,CAAA,CAAE,SAAA,CAAU,CAAA,CAAE,WAAA,EAAA,CAClD,GAAA,EAAK,GAAA,EACL,MAAA,EAAQ,CAAA,EACR,OAAA,GAAU,kBAAA,CAAmB,CAAA,IAC5B,IAAA,eAAmB,CAAA,YAAa,SAAA,CAAU,CAAA,UAAW,CAAA"}

package/dist/index.mjs

@@ -22,6 +22,23 @@ function zodValidatorAsync(schema) {
 		return result.error.issues[0]?.message ?? "Invalid";
 	};
 }
+/**
+* Run the schema and report only **root-level** issues (those with empty
+* `path`). Leaf issues are already covered by `zodValidator(propSchema)` on
+* each leaf field — surfacing them here would double-count.
+*
+* Used by `formFromZod` to lift root-level `.refine(...)` rules into a
+* form-level validator. Returns `null` when every issue belongs to a leaf
+* (or there are no issues at all).
+*/
+function rootOnlyZodValidator(schema) {
+	return (value, signal) => {
+		const result = schema.safeParse(value);
+		if (result.success) return null;
+		for (const issue of result.error.issues) if (issue.path.length === 0) return issue.message;
+		return null;
+	};
+}
 function unwrap(schema) {
 	let s = schema;
 	for (let i = 0; i < 5; i++) if (s instanceof z.ZodDefault) s = s.def.innerType;
@@ -45,49 +62,34 @@ function defaultInitial(schema) {
 		return typeof first === "string" ? first : "";
 	}
 }
-/**
-* 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.).
-*
-* The return type is structurally precise — `form.fields.title.value` is
-* `string` (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.
-*/
 function formFromZod(ctx, schema, options) {
-	return buildForm(ctx, schema, options?.initials);
+	return buildForm(ctx, schema, options?.initials, "", options?.extraValidators, schema);
 }
-function buildForm(ctx, schema, initials) {
+function buildForm(ctx, schema, initials, path, extras, rootSchema) {
 	const shape = schema.shape;
 	const fields = {};
 	for (const key of Object.keys(shape)) {
 		const propSchema = shape[key];
 		const initial = initials?.[key];
-		fields[key] = buildLeaf(ctx, propSchema, initial);
+		fields[key] = buildLeaf(ctx, propSchema, initial, path === "" ? key : `${path}.${key}`, extras);
 	}
-	const formOpts = {};
-	const topLevelValidators = [];
-	if (topLevelValidators.length > 0) formOpts.validators = topLevelValidators;
-	return ctx.form(fields, formOpts);
+	if (rootSchema !== void 0) return ctx.form(fields, { validators: [rootOnlyZodValidator(rootSchema)] });
+	return ctx.form(fields);
 }
-function buildLeaf(ctx, schema, initial) {
+function buildLeaf(ctx, schema, initial, path, extras) {
 	const inner = unwrap(schema);
-	if (inner instanceof z.ZodObject) return buildForm(ctx, inner, initial);
+	if (inner instanceof z.ZodObject) return buildForm(ctx, inner, initial, path, extras);
 	if (inner instanceof z.ZodArray) {
 		const elementSchema = inner.element;
-		return ctx.fieldArray((itemInitial) => buildLeaf(ctx, elementSchema, itemInitial), initial !== void 0 ? { initial } : void 0);
+		return ctx.fieldArray((itemInitial) => buildLeaf(ctx, elementSchema, itemInitial, path, extras), initial !== void 0 ? { initial } : void 0);
 	}
 	const ini = initial !== void 0 ? initial : defaultInitial(schema);
-	return ctx.field(ini, [zodValidator(schema)]);
+	const validators = [zodValidator(schema)];
+	const extra = extras?.[path];
+	if (extra !== void 0) validators.push(extra);
+	return ctx.field(ini, validators);
 }
 //#endregion
-export { formFromZod, zodValidator, zodValidatorAsync };
+export { formFromZod, rootOnlyZodValidator, zodValidator, zodValidatorAsync };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Ctx, Field, FieldArray, Form, FormOptions, Validator } from '@kontsedal/olas-core'\nimport { z } from 'zod'\n\n/**\n * Wrap a Zod schema as an Olas validator. Returns a sync or async Validator\n * depending on whether the schema requires async parsing (e.g. `.refine(async ...)`).\n */\nexport function zodValidator<T>(schema: z.ZodType<T>): Validator<T> {\n  return (value, signal) => {\n    // signal isn't used by Zod (parsing is sync) — kept for interface parity.\n    void signal\n    const result = schema.safeParse(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n/**\n * Async variant for schemas with `.refine(async ...)` or `.transform(async ...)`.\n * Returns a Promise<string | null>.\n */\nexport function zodValidatorAsync<T>(schema: z.ZodType<T>): Validator<T> {\n  return async (value, signal) => {\n    void signal\n    const result = await schema.safeParseAsync(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n// Zod 4 typed every wrapper as `z.ZodType`-compatible; the public unwrap path\n// is `.unwrap()` for optional/nullable and `.def.innerType` for default.\ntype AnyZodType = z.ZodType\n\n// Strip the outer optional/nullable/default wrappers to find the inner schema.\nfunction unwrap(schema: AnyZodType): AnyZodType {\n  let s: AnyZodType = schema\n  // Unwrap default + optional + nullable, in any combination.\n  for (let i = 0; i < 5; i++) {\n    if (s instanceof z.ZodDefault) {\n      // ZodDefault stores the inner schema on `def.innerType`. The runtime\n      // shape is stable across 3.x and 4.x; the public type just shifts.\n      s = (s as unknown as { def: { innerType: AnyZodType } }).def.innerType\n    } else if (s instanceof z.ZodOptional) {\n      s = (s as z.ZodOptional<AnyZodType>).unwrap() as AnyZodType\n    } else if (s instanceof z.ZodNullable) {\n      s = (s as z.ZodNullable<AnyZodType>).unwrap() as AnyZodType\n    } else {\n      return s\n    }\n  }\n  return s\n}\n\nfunction defaultInitial(schema: AnyZodType): unknown {\n  // Honor Zod default if present.\n  if (schema instanceof z.ZodDefault) {\n    const raw = (schema as unknown as { def: { defaultValue: unknown } }).def.defaultValue\n    return typeof raw === 'function' ? (raw as () => unknown)() : raw\n  }\n  const inner = unwrap(schema)\n  if (inner instanceof z.ZodString) return ''\n  if (inner instanceof z.ZodNumber) return 0\n  if (inner instanceof z.ZodBoolean) return false\n  if (inner instanceof z.ZodArray) return []\n  if (inner instanceof z.ZodEnum) {\n    // Zod 4 widened ZodEnum's options to support record-style enums. The\n    // runtime values are still iterable; pick the first.\n    const opts = (inner as unknown as { options: readonly unknown[] }).options\n    const first = opts[0]\n    return typeof first === 'string' ? first : ''\n  }\n  // For unknown/any/dates etc., undefined is the safest starting point.\n  return undefined\n}\n\ntype AnyForm = Form<Record<string, Field<any> | Form<any> | FieldArray<any>>>\n\n// Strip the same wrappers as the runtime `unwrap` helper, at the type level.\ntype UnwrapZod<S> =\n  S extends z.ZodDefault<infer Inner>\n    ? UnwrapZod<Inner>\n    : S extends z.ZodOptional<infer Inner>\n      ? UnwrapZod<Inner>\n      : S extends z.ZodNullable<infer Inner>\n        ? UnwrapZod<Inner>\n        : S\n\n/**\n * Recursively map a Zod schema to its Olas form leaf:\n *  - `ZodObject<S>` → `Form<{ [K]: ZodToLeaf<S[K]> }>`\n *  - `ZodArray<E>`  → `FieldArray<ZodToLeaf<E>>` (when E is object/array)\n *                     or `FieldArray<Field<infer<E>>>` for primitive elements.\n *  - everything else → `Field<infer<S>>`.\n *\n * `ZodToLeaf<S>` matches what `buildLeaf(ctx, s, ...)` returns at runtime,\n * so the public `formFromZod<T>` can publish a precise structural type\n * without the consumer needing a hand-written `CardForm = Form<{...}>` cast.\n */\nexport type ZodToLeaf<S> =\n  UnwrapZod<S> extends z.ZodObject<infer RawShape>\n    ? Form<{ [K in keyof RawShape]: ZodToLeaf<RawShape[K]> }>\n    : UnwrapZod<S> extends z.ZodArray<infer Element>\n      ? FieldArray<ZodToLeaf<Element> extends Form<any> | Field<any> ? ZodToLeaf<Element> : never>\n      : Field<z.infer<UnwrapZod<S> & z.ZodType>>\n\n/**\n * Walk a Zod schema and emit the equivalent Olas Form / FieldArray / Field\n * tree, with validators auto-attached.\n *\n * - `z.object(...)` → `Form`\n * - `z.array(...)`  → `FieldArray` (recurses on the element)\n * - leaf schemas    → `Field` with `zodValidator(...)` attached\n *\n * Each leaf's initial value is the Zod default if present, otherwise an empty\n * value for that type (`''` for strings, `0` for numbers, etc.).\n *\n * The return type is structurally precise — `form.fields.title.value` is\n * `string` (not `string | boolean | …`), `form.fields.subtasks.add(...)`\n * accepts the exact item shape, etc. Consumers do not need to hand-write\n * a `CardForm = Form<{...}>` matching the schema.\n */\nexport function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(\n  ctx: Ctx,\n  schema: T,\n  options?: { initials?: Partial<z.infer<T>> },\n): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }> {\n  return buildForm(ctx, schema, options?.initials) as never\n}\n\nfunction buildForm(\n  ctx: Ctx,\n  schema: z.ZodObject<z.ZodRawShape>,\n  initials?: Record<string, unknown>,\n): AnyForm {\n  const shape = schema.shape\n  const fields: Record<string, Field<unknown> | Form<any> | FieldArray<any>> = {}\n  for (const key of Object.keys(shape)) {\n    const propSchema = shape[key] as AnyZodType\n    const initial = initials?.[key]\n    fields[key] = buildLeaf(ctx, propSchema, initial)\n  }\n  const formOpts: FormOptions<typeof fields> = {}\n  // If the schema has top-level refinements (z.object().refine(...)), Zod\n  // wraps it in ZodEffects. We expose those as form-level validators.\n  const topLevelValidators: Validator<unknown>[] = []\n  // Note: we received an unwrapped ZodObject here, so there's nothing extra.\n  if (topLevelValidators.length > 0) {\n    ;(formOpts as { validators: Validator<unknown>[] }).validators = topLevelValidators\n  }\n  return ctx.form(fields, formOpts) as AnyForm\n}\n\nfunction buildLeaf(\n  ctx: Ctx,\n  schema: AnyZodType,\n  initial: unknown,\n): Field<unknown> | Form<any> | FieldArray<any> {\n  const inner = unwrap(schema)\n\n  if (inner instanceof z.ZodObject) {\n    return buildForm(\n      ctx,\n      inner as z.ZodObject<z.ZodRawShape>,\n      initial as Record<string, unknown> | undefined,\n    )\n  }\n\n  if (inner instanceof z.ZodArray) {\n    const elementSchema = (inner as z.ZodArray<AnyZodType>).element as AnyZodType\n    return ctx.fieldArray(\n      (itemInitial) => buildLeaf(ctx, elementSchema, itemInitial) as Field<unknown> | Form<any>,\n      initial !== undefined ? { initial: initial as Array<unknown> } : undefined,\n    )\n  }\n\n  const ini = initial !== undefined ? initial : defaultInitial(schema)\n  return ctx.field(ini, [zodValidator(schema as z.ZodType<unknown>)])\n}\n"],"mappings":";;;;;;AAOA,SAAgB,aAAgB,QAAoC;CAClE,QAAQ,OAAO,WAAW;EAGxB,MAAM,SAAS,OAAO,UAAU,KAAK;EACrC,IAAI,OAAO,SAAS,OAAO;EAC3B,OAAO,OAAO,MAAM,OAAO,IAAI,WAAW;CAC5C;AACF;;;;;AAMA,SAAgB,kBAAqB,QAAoC;CACvE,OAAO,OAAO,OAAO,WAAW;EAE9B,MAAM,SAAS,MAAM,OAAO,eAAe,KAAK;EAChD,IAAI,OAAO,SAAS,OAAO;EAC3B,OAAO,OAAO,MAAM,OAAO,IAAI,WAAW;CAC5C;AACF;AAOA,SAAS,OAAO,QAAgC;CAC9C,IAAI,IAAgB;CAEpB,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KACrB,IAAI,aAAa,EAAE,YAGjB,IAAK,EAAoD,IAAI;MACxD,IAAI,aAAa,EAAE,aACxB,IAAK,EAAgC,OAAO;MACvC,IAAI,aAAa,EAAE,aACxB,IAAK,EAAgC,OAAO;MAE5C,OAAO;CAGX,OAAO;AACT;AAEA,SAAS,eAAe,QAA6B;CAEnD,IAAI,kBAAkB,EAAE,YAAY;EAClC,MAAM,MAAO,OAAyD,IAAI;EAC1E,OAAO,OAAO,QAAQ,aAAc,IAAsB,IAAI;CAChE;CACA,MAAM,QAAQ,OAAO,MAAM;CAC3B,IAAI,iBAAiB,EAAE,WAAW,OAAO;CACzC,IAAI,iBAAiB,EAAE,WAAW,OAAO;CACzC,IAAI,iBAAiB,EAAE,YAAY,OAAO;CAC1C,IAAI,iBAAiB,EAAE,UAAU,OAAO,CAAC;CACzC,IAAI,iBAAiB,EAAE,SAAS;EAI9B,MAAM,QADQ,MAAqD,QAChD;EACnB,OAAO,OAAO,UAAU,WAAW,QAAQ;CAC7C;AAGF;;;;;;;;;;;;;;;;;AAgDA,SAAgB,YACd,KACA,QACA,SAC6D;CAC7D,OAAO,UAAU,KAAK,QAAQ,SAAS,QAAQ;AACjD;AAEA,SAAS,UACP,KACA,QACA,UACS;CACT,MAAM,QAAQ,OAAO;CACrB,MAAM,SAAuE,CAAC;CAC9E,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GAAG;EACpC,MAAM,aAAa,MAAM;EACzB,MAAM,UAAU,WAAW;EAC3B,OAAO,OAAO,UAAU,KAAK,YAAY,OAAO;CAClD;CACA,MAAM,WAAuC,CAAC;CAG9C,MAAM,qBAA2C,CAAC;CAElD,IAAI,mBAAmB,SAAS,GAC7B,SAAmD,aAAa;CAEnE,OAAO,IAAI,KAAK,QAAQ,QAAQ;AAClC;AAEA,SAAS,UACP,KACA,QACA,SAC8C;CAC9C,MAAM,QAAQ,OAAO,MAAM;CAE3B,IAAI,iBAAiB,EAAE,WACrB,OAAO,UACL,KACA,OACA,OACF;CAGF,IAAI,iBAAiB,EAAE,UAAU;EAC/B,MAAM,gBAAiB,MAAiC;EACxD,OAAO,IAAI,YACR,gBAAgB,UAAU,KAAK,eAAe,WAAW,GAC1D,YAAY,KAAA,IAAY,EAAW,QAA0B,IAAI,KAAA,CACnE;CACF;CAEA,MAAM,MAAM,YAAY,KAAA,IAAY,UAAU,eAAe,MAAM;CACnE,OAAO,IAAI,MAAM,KAAK,CAAC,aAAa,MAA4B,CAAC,CAAC;AACpE"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Ctx, Field, FieldArray, Form, Validator } from '@kontsedal/olas-core'\nimport { z } from 'zod'\n\n/**\n * Wrap a Zod schema as an Olas validator. Returns a sync or async Validator\n * depending on whether the schema requires async parsing (e.g. `.refine(async ...)`).\n */\nexport function zodValidator<T>(schema: z.ZodType<T>): Validator<T> {\n  return (value, signal) => {\n    // signal isn't used by Zod (parsing is sync) — kept for interface parity.\n    void signal\n    const result = schema.safeParse(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n/**\n * Async variant for schemas with `.refine(async ...)` or `.transform(async ...)`.\n * Returns a Promise<string | null>.\n */\nexport function zodValidatorAsync<T>(schema: z.ZodType<T>): Validator<T> {\n  return async (value, signal) => {\n    void signal\n    const result = await schema.safeParseAsync(value)\n    if (result.success) return null\n    return result.error.issues[0]?.message ?? 'Invalid'\n  }\n}\n\n/**\n * Run the schema and report only **root-level** issues (those with empty\n * `path`). Leaf issues are already covered by `zodValidator(propSchema)` on\n * each leaf field — surfacing them here would double-count.\n *\n * Used by `formFromZod` to lift root-level `.refine(...)` rules into a\n * form-level validator. Returns `null` when every issue belongs to a leaf\n * (or there are no issues at all).\n */\nexport function rootOnlyZodValidator<T>(schema: z.ZodType<T>): Validator<T> {\n  return (value, signal) => {\n    void signal\n    const result = schema.safeParse(value)\n    if (result.success) return null\n    for (const issue of result.error.issues) {\n      if (issue.path.length === 0) return issue.message\n    }\n    return null\n  }\n}\n\n// Zod 4 typed every wrapper as `z.ZodType`-compatible; the public unwrap path\n// is `.unwrap()` for optional/nullable and `.def.innerType` for default.\ntype AnyZodType = z.ZodType\n\n// Strip the outer optional/nullable/default wrappers to find the inner schema.\nfunction unwrap(schema: AnyZodType): AnyZodType {\n  let s: AnyZodType = schema\n  // Unwrap default + optional + nullable, in any combination.\n  for (let i = 0; i < 5; i++) {\n    if (s instanceof z.ZodDefault) {\n      // ZodDefault stores the inner schema on `def.innerType`. The runtime\n      // shape is stable across 3.x and 4.x; the public type just shifts.\n      s = (s as unknown as { def: { innerType: AnyZodType } }).def.innerType\n    } else if (s instanceof z.ZodOptional) {\n      s = (s as z.ZodOptional<AnyZodType>).unwrap() as AnyZodType\n    } else if (s instanceof z.ZodNullable) {\n      s = (s as z.ZodNullable<AnyZodType>).unwrap() as AnyZodType\n    } else {\n      return s\n    }\n  }\n  return s\n}\n\nfunction defaultInitial(schema: AnyZodType): unknown {\n  // Honor Zod default if present.\n  if (schema instanceof z.ZodDefault) {\n    const raw = (schema as unknown as { def: { defaultValue: unknown } }).def.defaultValue\n    return typeof raw === 'function' ? (raw as () => unknown)() : raw\n  }\n  const inner = unwrap(schema)\n  if (inner instanceof z.ZodString) return ''\n  if (inner instanceof z.ZodNumber) return 0\n  if (inner instanceof z.ZodBoolean) return false\n  if (inner instanceof z.ZodArray) return []\n  if (inner instanceof z.ZodEnum) {\n    // Zod 4 widened ZodEnum's options to support record-style enums. The\n    // runtime values are still iterable; pick the first.\n    const opts = (inner as unknown as { options: readonly unknown[] }).options\n    const first = opts[0]\n    return typeof first === 'string' ? first : ''\n  }\n  // For unknown/any/dates etc., undefined is the safest starting point.\n  return undefined\n}\n\ntype AnyForm = Form<Record<string, Field<any> | Form<any> | FieldArray<any>>>\n\n// Strip the same wrappers as the runtime `unwrap` helper, at the type level.\ntype UnwrapZod<S> =\n  S extends z.ZodDefault<infer Inner>\n    ? UnwrapZod<Inner>\n    : S extends z.ZodOptional<infer Inner>\n      ? UnwrapZod<Inner>\n      : S extends z.ZodNullable<infer Inner>\n        ? UnwrapZod<Inner>\n        : S\n\n/**\n * Recursively map a Zod schema to its Olas form leaf:\n *  - `ZodObject<S>` → `Form<{ [K]: ZodToLeaf<S[K]> }>`\n *  - `ZodArray<E>`  → `FieldArray<ZodToLeaf<E>>` (when E is object/array)\n *                     or `FieldArray<Field<infer<E>>>` for primitive elements.\n *  - everything else → `Field<infer<S>>`.\n *\n * `ZodToLeaf<S>` matches what `buildLeaf(ctx, s, ...)` returns at runtime,\n * so the public `formFromZod<T>` can publish a precise structural type\n * without the consumer needing a hand-written `CardForm = Form<{...}>` cast.\n */\nexport type ZodToLeaf<S> =\n  UnwrapZod<S> extends z.ZodObject<infer RawShape>\n    ? Form<{ [K in keyof RawShape]: ZodToLeaf<RawShape[K]> }>\n    : UnwrapZod<S> extends z.ZodArray<infer Element>\n      ? FieldArray<ZodToLeaf<Element> extends Form<any> | Field<any> ? ZodToLeaf<Element> : never>\n      : Field<z.infer<UnwrapZod<S> & z.ZodType>>\n\n/**\n * Walk a Zod schema and emit the equivalent Olas Form / FieldArray / Field\n * tree, with validators auto-attached.\n *\n * - `z.object(...)` → `Form`\n * - `z.array(...)`  → `FieldArray` (recurses on the element)\n * - leaf schemas    → `Field` with `zodValidator(...)` attached\n *\n * Each leaf's initial value is the Zod default if present, otherwise an empty\n * value for that type (`''` for strings, `0` for numbers, etc.).\n *\n * The return type is structurally precise — `form.fields.title.value` is\n * `string` (not `string | boolean | …`), `form.fields.subtasks.add(...)`\n * accepts the exact item shape, etc. Consumers do not need to hand-write\n * a `CardForm = Form<{...}>` matching the schema.\n */\n/**\n * Per-leaf extra validators keyed by dotted path. Match the leaf field's\n * position inside the schema:\n *\n * - top-level: `'title'`\n * - nested form: `'address.street'`\n *\n * `FieldArray` items aren't separately addressable — the schema walker\n * generates one factory per array, so a path of `'tags'` matches the\n * `FieldArray` (validators attached there apply to the array as a whole;\n * use Olas's `FieldArrayOptions.validators` shape). Per-element rules\n * already live on the Zod element schema and are attached automatically.\n *\n * Validators run alongside `zodValidator(schema)` — both must pass.\n */\nexport type ExtraValidators = Record<string, Validator<any>>\n\nexport type FormFromZodOptions<T extends z.ZodObject<z.ZodRawShape>> = {\n  initials?: Partial<z.infer<T>>\n  extraValidators?: ExtraValidators\n}\n\nexport function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(\n  ctx: Ctx,\n  schema: T,\n  options?: FormFromZodOptions<T>,\n): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }> {\n  return buildForm(ctx, schema, options?.initials, '', options?.extraValidators, schema) as never\n}\n\nfunction buildForm(\n  ctx: Ctx,\n  schema: z.ZodObject<z.ZodRawShape>,\n  initials: Record<string, unknown> | undefined,\n  path: string,\n  extras: ExtraValidators | undefined,\n  /**\n   * The original top-level schema. Passed only when constructing the ROOT\n   * form — nested `buildForm` calls (from object-typed leaves) pass\n   * `undefined`. Used to attach a root-only Zod validator so\n   * `z.object({...}).refine(fn)` rules surface as form-level errors\n   * without double-reporting leaf issues. See `rootOnlyZodValidator`.\n   */\n  rootSchema?: z.ZodObject<z.ZodRawShape>,\n): AnyForm {\n  const shape = schema.shape\n  const fields: Record<string, Field<unknown> | Form<any> | FieldArray<any>> = {}\n  for (const key of Object.keys(shape)) {\n    const propSchema = shape[key] as AnyZodType\n    const initial = initials?.[key]\n    const leafPath = path === '' ? key : `${path}.${key}`\n    fields[key] = buildLeaf(ctx, propSchema, initial, leafPath, extras)\n  }\n  // Lift root-level `.refine(...)` checks on the top-level object into a\n  // form-level validator. Leaf checks remain owned by leaf-level\n  // `zodValidator(propSchema)`; `rootOnlyZodValidator` filters to issues\n  // whose `path` is empty so leaf issues are not double-reported.\n  if (rootSchema !== undefined) {\n    return ctx.form(fields, {\n      validators: [rootOnlyZodValidator(rootSchema as z.ZodType<unknown>) as never],\n    }) as AnyForm\n  }\n  return ctx.form(fields) as AnyForm\n}\n\nfunction buildLeaf(\n  ctx: Ctx,\n  schema: AnyZodType,\n  initial: unknown,\n  path: string,\n  extras: ExtraValidators | undefined,\n): Field<unknown> | Form<any> | FieldArray<any> {\n  const inner = unwrap(schema)\n\n  if (inner instanceof z.ZodObject) {\n    return buildForm(\n      ctx,\n      inner as z.ZodObject<z.ZodRawShape>,\n      initial as Record<string, unknown> | undefined,\n      path,\n      extras,\n    )\n  }\n\n  if (inner instanceof z.ZodArray) {\n    const elementSchema = (inner as z.ZodArray<AnyZodType>).element as AnyZodType\n    return ctx.fieldArray(\n      // Array items aren't enumerable at schema-build time; we don't extend\n      // the dotted path with an index here. Per-item validators belong on\n      // the Zod element schema (which `buildLeaf` already wraps via\n      // `zodValidator`).\n      (itemInitial) =>\n        buildLeaf(ctx, elementSchema, itemInitial, path, extras) as Field<unknown> | Form<any>,\n      initial !== undefined ? { initial: initial as Array<unknown> } : undefined,\n    )\n  }\n\n  const ini = initial !== undefined ? initial : defaultInitial(schema)\n  const validators: Array<Validator<unknown>> = [zodValidator(schema as z.ZodType<unknown>)]\n  const extra = extras?.[path]\n  if (extra !== undefined) validators.push(extra as Validator<unknown>)\n  return ctx.field(ini, validators)\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontsedal/olas-zod",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1",
   "description": "Olas Zod integration — zodValidator and formFromZod for end-to-end typed forms.",
   "keywords": [
     "olas",
@@ -46,11 +46,11 @@
   "sideEffects": false,
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@kontsedal/olas-core": "^0.0.1-rc.1"
+    "@kontsedal/olas-core": "^0.0.1"
   },
   "devDependencies": {
     "zod": "^4.4.3",
-    "@kontsedal/olas-core": "^0.0.1-rc.1"
+    "@kontsedal/olas-core": "^0.0.1"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { Ctx, Field, FieldArray, Form, FormOptions, Validator } from '@kontsedal/olas-core'
+import type { Ctx, Field, FieldArray, Form, Validator } from '@kontsedal/olas-core'
 import { z } from 'zod'
 
 /**
@@ -28,6 +28,27 @@ export function zodValidatorAsync<T>(schema: z.ZodType<T>): Validator<T> {
   }
 }
 
+/**
+ * Run the schema and report only **root-level** issues (those with empty
+ * `path`). Leaf issues are already covered by `zodValidator(propSchema)` on
+ * each leaf field — surfacing them here would double-count.
+ *
+ * Used by `formFromZod` to lift root-level `.refine(...)` rules into a
+ * form-level validator. Returns `null` when every issue belongs to a leaf
+ * (or there are no issues at all).
+ */
+export function rootOnlyZodValidator<T>(schema: z.ZodType<T>): Validator<T> {
+  return (value, signal) => {
+    void signal
+    const result = schema.safeParse(value)
+    if (result.success) return null
+    for (const issue of result.error.issues) {
+      if (issue.path.length === 0) return issue.message
+    }
+    return null
+  }
+}
+
 // Zod 4 typed every wrapper as `z.ZodType`-compatible; the public unwrap path
 // is `.unwrap()` for optional/nullable and `.def.innerType` for default.
 type AnyZodType = z.ZodType
@@ -120,41 +141,77 @@ export type ZodToLeaf<S> =
  * accepts the exact item shape, etc. Consumers do not need to hand-write
  * a `CardForm = Form<{...}>` matching the schema.
  */
+/**
+ * Per-leaf extra validators keyed by dotted path. Match the leaf field's
+ * position inside the schema:
+ *
+ * - top-level: `'title'`
+ * - nested form: `'address.street'`
+ *
+ * `FieldArray` items aren't separately addressable — the schema walker
+ * generates one factory per array, so a path of `'tags'` matches the
+ * `FieldArray` (validators attached there apply to the array as a whole;
+ * use Olas's `FieldArrayOptions.validators` shape). Per-element rules
+ * already live on the Zod element schema and are attached automatically.
+ *
+ * Validators run alongside `zodValidator(schema)` — both must pass.
+ */
+export type ExtraValidators = Record<string, Validator<any>>
+
+export type FormFromZodOptions<T extends z.ZodObject<z.ZodRawShape>> = {
+  initials?: Partial<z.infer<T>>
+  extraValidators?: ExtraValidators
+}
+
 export function formFromZod<T extends z.ZodObject<z.ZodRawShape>>(
   ctx: Ctx,
   schema: T,
-  options?: { initials?: Partial<z.infer<T>> },
+  options?: FormFromZodOptions<T>,
 ): Form<{ [K in keyof T['shape']]: ZodToLeaf<T['shape'][K]> }> {
-  return buildForm(ctx, schema, options?.initials) as never
+  return buildForm(ctx, schema, options?.initials, '', options?.extraValidators, schema) as never
 }
 
 function buildForm(
   ctx: Ctx,
   schema: z.ZodObject<z.ZodRawShape>,
-  initials?: Record<string, unknown>,
+  initials: Record<string, unknown> | undefined,
+  path: string,
+  extras: ExtraValidators | undefined,
+  /**
+   * The original top-level schema. Passed only when constructing the ROOT
+   * form — nested `buildForm` calls (from object-typed leaves) pass
+   * `undefined`. Used to attach a root-only Zod validator so
+   * `z.object({...}).refine(fn)` rules surface as form-level errors
+   * without double-reporting leaf issues. See `rootOnlyZodValidator`.
+   */
+  rootSchema?: z.ZodObject<z.ZodRawShape>,
 ): AnyForm {
   const shape = schema.shape
   const fields: Record<string, Field<unknown> | Form<any> | FieldArray<any>> = {}
   for (const key of Object.keys(shape)) {
     const propSchema = shape[key] as AnyZodType
     const initial = initials?.[key]
-    fields[key] = buildLeaf(ctx, propSchema, initial)
+    const leafPath = path === '' ? key : `${path}.${key}`
+    fields[key] = buildLeaf(ctx, propSchema, initial, leafPath, extras)
   }
-  const formOpts: FormOptions<typeof fields> = {}
-  // If the schema has top-level refinements (z.object().refine(...)), Zod
-  // wraps it in ZodEffects. We expose those as form-level validators.
-  const topLevelValidators: Validator<unknown>[] = []
-  // Note: we received an unwrapped ZodObject here, so there's nothing extra.
-  if (topLevelValidators.length > 0) {
-    ;(formOpts as { validators: Validator<unknown>[] }).validators = topLevelValidators
+  // Lift root-level `.refine(...)` checks on the top-level object into a
+  // form-level validator. Leaf checks remain owned by leaf-level
+  // `zodValidator(propSchema)`; `rootOnlyZodValidator` filters to issues
+  // whose `path` is empty so leaf issues are not double-reported.
+  if (rootSchema !== undefined) {
+    return ctx.form(fields, {
+      validators: [rootOnlyZodValidator(rootSchema as z.ZodType<unknown>) as never],
+    }) as AnyForm
   }
-  return ctx.form(fields, formOpts) as AnyForm
+  return ctx.form(fields) as AnyForm
 }
 
 function buildLeaf(
   ctx: Ctx,
   schema: AnyZodType,
   initial: unknown,
+  path: string,
+  extras: ExtraValidators | undefined,
 ): Field<unknown> | Form<any> | FieldArray<any> {
   const inner = unwrap(schema)
 
@@ -163,17 +220,27 @@ function buildLeaf(
       ctx,
       inner as z.ZodObject<z.ZodRawShape>,
       initial as Record<string, unknown> | undefined,
+      path,
+      extras,
     )
   }
 
   if (inner instanceof z.ZodArray) {
     const elementSchema = (inner as z.ZodArray<AnyZodType>).element as AnyZodType
     return ctx.fieldArray(
-      (itemInitial) => buildLeaf(ctx, elementSchema, itemInitial) as Field<unknown> | Form<any>,
+      // Array items aren't enumerable at schema-build time; we don't extend
+      // the dotted path with an index here. Per-item validators belong on
+      // the Zod element schema (which `buildLeaf` already wraps via
+      // `zodValidator`).
+      (itemInitial) =>
+        buildLeaf(ctx, elementSchema, itemInitial, path, extras) as Field<unknown> | Form<any>,
       initial !== undefined ? { initial: initial as Array<unknown> } : undefined,
     )
   }
 
   const ini = initial !== undefined ? initial : defaultInitial(schema)
-  return ctx.field(ini, [zodValidator(schema as z.ZodType<unknown>)])
+  const validators: Array<Validator<unknown>> = [zodValidator(schema as z.ZodType<unknown>)]
+  const extra = extras?.[path]
+  if (extra !== undefined) validators.push(extra as Validator<unknown>)
+  return ctx.field(ini, validators)
 }