Server API

The functions and types that @k8ordo/form/server provides. Call them on the server, which keeps zod out of the browser.

On this page

formFields

Import from @k8ordo/form/server

Derives each field’s attributes, messages and rules from the schema.

Copy code

formFields(input: ZodObject | FormDefinition): FormFields

Parameters

inputZodObject | FormDefinition: A zod object, or a definition made with defineForm.

Returns

FormFields — JSON holding fields, arrays, rules and dropped. Pass it to useForm as it is.

Caveats

Call it in a Server Component or at module scope. The result is JSON, so it crosses to the client as props.
Messages are fixed when it runs. To follow the request’s locale, call it during the render.
It throws, with the reason, on a schema a form cannot express (z.record, tuples, z.number() and so on).
Checks no HTML attribute can express go into dropped. Outside production it also reports them with console.warn.

parseForm

Import from @k8ordo/form/server

Validates a submitted FormData against the schema.

Copy code

parseForm(input: ZodObject | FormDefinition, formData: FormData): ParseResult

Parameters

inputZodObject | FormDefinition: The same schema or definition you passed to formFields.
formDataFormData: The FormData the Server Action received.

Returns

ParseResult — { success: true, data, state } on success, { success: false, state } on failure. data is typed.

Caveats

It gathers unchecked checkboxes and repeated names before handing the values to the schema. Turning strings into numbers is the schema’s job, through z.coerce.
It throws when a field in the schema is missing from the FormData, since that means an input was never spread. Controls that send nothing when left alone (radio buttons, <select>, checkboxes) are the exception.
Passwords and files are never included in state.values.

defineForm

Import from @k8ordo/form/server

Attaches rules that span several fields to a schema.

Copy code

defineForm(schema: ZodObject, rules?: Rule[]): FormDefinition

Parameters

schemaZodObject: A zod object.
rulesRule[]: Rules made with sameAs, minChecked and requiredWhen. Field paths are type-checked.

Returns

FormDefinition — Pass it to formFields and parseForm in place of the schema.

Caveats

Both the browser and the server check the rules with the same evaluator. When several rules break on one field, the message of the one declared first is shown.

sameAs

Import from @k8ordo/form/server

Requires field to equal other. Use it to confirm a password.

Copy code

sameAs(field: FieldPath, other: FieldPath, message: RuleMessage): Rule

Parameters

fieldFieldPath: The path of the field the rule applies to. A breach is reported on it.
otherFieldPath: The path of the field to compare with.
messagestring | (() => string): The message for a breach. A function is called when the breach is reported.

Returns

Rule — List it in defineForm’s second argument.

minChecked

Import from @k8ordo/form/server

Requires at least min of the checkboxes sharing a name to be checked.

Copy code

minChecked(field: FieldPath, min: number, message: RuleMessage): Rule

Parameters

fieldFieldPath: The path of the field the rule applies to. A breach is reported on it.
minnumber: The fewest boxes that must be checked.
messagestring | (() => string): The message for a breach. A function is called when the breach is reported.

Returns

Rule — List it in defineForm’s second argument.

requiredWhen

Import from @k8ordo/form/server

Makes field required only while when holds equals.

Copy code

requiredWhen(field: FieldPath, when: FieldPath, equals: string, message: RuleMessage): Rule

Parameters

fieldFieldPath: The path of the field the rule applies to. A breach is reported on it.
whenFieldPath: The path of the field the condition reads.
equalsstring: The value of when that makes field required.
messagestring | (() => string): The message for a breach. A function is called when the breach is reported.

Returns

Rule — List it in defineForm’s second argument.

FormState

Import from @k8ordo/form/server

What a Server Action hands back to the form. parseForm builds it and useForm reads it.

Copy code

type FormState = {
  errors?: Record<string, string>;
  values?: Record<string, string | string[]>;
  rows?: Record<string, number>;
  formError?: string;
  token?: string;
};

Fields

errorsRecord<string, string>: Errors per field, keyed by path such as items[1].name.
valuesRecord<string, string | string[]>: The submitted values, restored as the fields’ defaults after a failure.
rowsRecord<string, number>: How many rows each array had, so the same rows render again without JavaScript.
formErrorstring: An error that belongs to no field.
tokenstring: Identifies one parse, so two identical failures still read as two responses.