createSchema() API

Field-level rules (required, min, email, matches, etc.) already run through the builder chain on each individual field. That covers most forms until you need a rule that depends on *multiple* fields at once:

• "Provide at least an email or a phone number."
• "Return date must be on or after departure date."
• "If you supply a billing address, all billing fields must be filled."
• "Password must match confirmation, and must not contain the email handle."
• "If role === 'admin', then managerApproval is required."
• etc.

Without createSchema() you would either scatter these checks across ad-hoc useEffect hooks, duplicate them in onSubmit handlers, or pull in an external bridge library (Zod, Yup, Joi, Valibot) just to express a handful of rules. createSchema() gives you a first-class, chainable place for those rules that runs through the same validation pipeline as every other field errors land in state.errors, touch/dirty tracking still works, and form-level errors surface under state.formLevelError.

The design goal is stated plainly: FormBridge should be self-sufficient. Built-in validation is the complete path, not a stepping stone to an external bridge.

Use createSchema() whenever any of the following apply:

• You need cross-field validation (one field's validity depends on another's value).
• You want form-level errors that are not attached to a specific field - createSchema() surfaces these under state.formLevelError.
• You want to parse the submitted values to a fully-typed object via safeParse / validate ideal inside server actions, tRPC procedures, or standalone utilities where you do not have a mounted form.
• You want async refinements (e.g. username availability, server-side uniqueness checks) wired into the same validation pass as synchronous rules.
• You want to customise error messages globally via errorMap instead of overriding each field.

If your form has only independent field rules, the plain object form with satisfies FormSchema is enough. Wrap it in createSchema() the moment you need any of the behaviours above the two forms are interchangeable at the useFormBridge call site.

The wrapped schema is used exactly like a plain shape. Hand it to useFormBridge, render via fields.*, and chain cross-field rules on the result of createSchema(). Declare the schema at module scope (outside the component) so its identity stays stable across renders. If that schema module is reused outside React, move the schema authoring imports to @runilib/react-formbridge/schema.

If a schema file is imported by both React code and server-side code, define that file with the server-safe @runilib/react-formbridge/schema subpath. That keeps schema authoring and parsing available without pulling hooks or UI helpers into the server module graph.

Keep React-only APIs such as useFormBridge imported from the main @runilib/react-formbridge entry inside your client component files.

The parse surface runs every field-level validator plus every refinement and returns a structured result. It never throws - the caller inspects result.success to decide what to do.

Signature

Returned shape

When to use which

• safeParse is synchronous. Any async refinement in the chain will throw a loud error telling you to use safeParseAsync.
• safeParseAsync runs both sync and async refinements in order. Always reach for it on the server side, where you typically have async checks.

Typical uses

• Server actions / tRPC handlers that want to reuse the same schema they render with.
• Standalone utility functions that validate persisted drafts before writing to the database.
• Tests you can assert directly on errorsByField without mounting React.

The strict variants of safeParse / safeParseAsync. They return the typed, parsed data on success and throw FormBridgeSchemaValidationError on failure. The thrown error carries the full ValidationResult on its .result property.

Signature

Use these when you want to bail early on invalid input for example, inside a try / catch at a request boundary and do not want to hand-unwrap the result.success discriminated union on every call site. safeParse is usually the safer default inside React components.

Attach a boolean predicate as a cross-field rule. Returns true if the values are valid, false to raise an issue. The message argument becomes the issue message; omit it to use the default "Invalid form.".

Signature

Notes

• A bare string message creates a form-level error (no path), so it surfaces under state.formLevelError.
• Pass an object to pin the error to a specific field: refine(p, { path: 'email', message: 'Taken' }).
• refineAsync only runs inside safeParseAsync / validateAsync. Running it through the synchronous path throws.
• Chain as many .refine() calls as you like each returns the same wrapped schema so the chain is fluent.

The most flexible refinement primitive. Instead of returning a boolean, you receive a ctx object with an addIssue method and can raise multiple issues each routed to its own field in a single pass.

Signature

When to pick superRefine over refine

• You need to raise errors on several fields from one cross-check.
• You want to set a custom code and params for downstream logging or i18n.
• You want to short-circuit further work inside the refinement based on shape (e.g. skip the check if a value is empty).

atLeastOne, exactlyOne, and allOrNone are all implemented internally as superRefine calls, so anything they can do, you can write by hand if you need custom behaviour.

Register a global transformer for validation messages. The mapper receives the raw issue and can return a new string (or null to use the default). This is the FormBridge-native equivalent of Zod's errorMap ideal for i18n or for standardising error copy across a large form.

Signature

The mapper runs against every issue produced by field validators and refinements, so you can centralise message rewriting in one place.

Built-in helper: require that at least one of the listed fields has a "provided" value. A value is considered provided when it is a non-empty string, a true boolean, a non-empty array, or any other non-nullish value.

Signature

Default message

"At least one of <field1>, <field2>, ... is required."? You can override it by passing your own string.

Error routing

The error has no path, so it surfaces as a form-level error under state.formLevelError. Render it below the group of fields it governs.

Accepted field identifiers

• 'email' string key on the root schema
• ref('profile.phone') nested or dynamic path via the ref() helper

Built-in helper: require that exactly one of the listed fields is provided. Raises an issue if zero or more than one are filled in. Useful for "pick your delivery method" or "choose a contact channel" style forms where the rest of the pipeline assumes a single winner.

Signature

Default message

"Exactly one of <field1>, <field2>, ... must be provided."

Built-in helper: either all of the listed fields are provided, or none of them are. Triggers when the user has filled in some but not all of the group. Perfect for optional-but-atomic sections like "billing address" or "emergency contact".

Signature

Default message

"Provide either all or none of <field1>, <field2>, ..."

ref(path) produces a typed pointer to a field. It exists for two reasons:

1. Nested paths. Plain string keys only work for top-level fields. ref('profile.phone') walks into a nested object during cross-field checks.
2. Self-documenting intent. ref('profile.phone') inside an atLeastOne or exactlyOne call reads unambiguously as "this field path", while a bare string can look like ordinary text.

You can mix ref() and plain string keys freely inside atLeastOne, exactlyOne, allOrNone, and other custom validation logic. Under the hood the bridge uses getValueAtPath with dot-notation, so deeply nested schemas work transparently.

Every issue produced by createSchema() whether it comes from a field builder, a manual refine, a superRefine, or one of the built-in helpers flows through the same pipeline:

1. Normalised into a ValidationIssue with { path, code, message, params }.
2. Optionally rewritten by your errorMap mapper, if one is registered.
3. Bucketed into errorsByField (keyed by path) and formLevelErrors (no path).
4. Merged into the React form state, where errorsByField lands in state.errors and the first formLevelErrors entry lands in state.formLevelError.

Practical consequences:

• Field-level UI (<fields.email />) automatically displays path-keyed issues you do nothing.
• To show form-level errors, read state.formLevelError and render it wherever makes sense (below the form, in a toast, etc.).
• Duplicate issues on the same field are preserved in issues but errorsByField only keeps the first one, mirroring the usual "one message per field" convention.

If your form needs only field-level rules, keep the object form and annotate it with satisfies FormSchema so TypeScript preserves each field's precise type:

The moment you need cross-field rules, a parse surface, or form-level errors, wrap it in createSchema() nothing else in the call site has to change:

useFormBridge(profileSchema) accepts either form and SchemaValues<typeof profileSchema> resolves to the same typed object in both cases.