Server API
The functions and types that @k8ordo/form/server provides. All of them are called on the server, so zod never reaches the browser.
On this page
formFields
Import from @k8ordo/form/server
Derives each field’s attributes, messages and rules from the schema.
formFields(input: ZodObject | FormDefinition): FormFieldsParameters
inputZodObject | FormDefinition- A zod object schema, 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 can be passed to a Client Component as props.
- Messages are fixed when it runs. To follow the request’s locale, call it during the render.
- A schema a form cannot express (
z.record, tuples,z.number()and so on) fails with[@k8ordo/form] 'field': reason. - Checks no HTML attribute can express go into
droppedand run on the server only. Outside production they are also reported withconsole.warn.
parseForm
Import from @k8ordo/form/server
Validates a submitted FormData against the schema.
parseForm(input: ZodObject | FormDefinition, formData: FormData): ParseResultParameters
inputZodObject | FormDefinition- The same schema or definition you passed to
formFields. formDataFormData- The
FormDatathe Server Action received.
Returns
ParseResult — { success: true, data, state } on success, { success: false, state } on failure. data has the schema’s output type.
Caveats
- Every submitted value is a string. Converting one to a number is the schema’s job, via
z.coerce. - Before the schema runs,
parseFormturns an unchecked checkbox intofalseand the values sent under one name into an array. - A field in the schema that is missing from the
FormDatafails with[@k8ordo/form] スキーマにあるフィールドが送信されていません: field. It appears wheninputwas never passed to the control. Radio buttons,<select>and checkboxes are exempt, since they send nothing when nothing is chosen. - Passwords and files are never included in
state.values.
defineForm
Import from @k8ordo/form/server
Attaches rules that span several fields to a schema.
defineForm(schema: ZodObject, rules?: Rule[]): FormDefinitionParameters
schemaZodObject- A zod object schema.
rulesRule[]- Rules made with
sameAs,minCheckedandrequiredWhen. Field paths are type-checked.
Returns
FormDefinition — Pass it to formFields and parseForm in place of the schema.
Caveats
- The browser and the server evaluate the rules with the same code. When several rules fail on one field, the message of the rule declared first is shown.
sameAs
Import from @k8ordo/form/server
Requires field to equal other. Use it to confirm a password.
sameAs(field: FieldPath, other: FieldPath, message: RuleMessage): RuleParameters
fieldFieldPath- The path of the field the rule applies to. When the rule fails, the error is shown on this field.
otherFieldPath- The path of the field to compare with.
messagestring | (() => string)- The message shown when the rule fails. A function is called when the error is reported.
Returns
Rule — List it in the second argument of defineForm.
minChecked
Import from @k8ordo/form/server
Requires at least min of the checkboxes sharing a name to be checked.
minChecked(field: FieldPath, min: number, message: RuleMessage): RuleParameters
fieldFieldPath- The path of the field the rule applies to. When the rule fails, the error is shown on this field.
minnumber- The fewest boxes that must be checked.
messagestring | (() => string)- The message shown when the rule fails. A function is called when the error is reported.
Returns
Rule — List it in the second argument of defineForm.
requiredWhen
Import from @k8ordo/form/server
Makes field required only while the value of when is equals.
requiredWhen(field: FieldPath, when: FieldPath, equals: string, message: RuleMessage): RuleParameters
fieldFieldPath- The path of the field the rule applies to. When the rule fails, the error is shown on this field.
whenFieldPath- The path of the field the condition reads.
equalsstring- The value of
whenthat makesfieldrequired. messagestring | (() => string)- The message shown when the rule fails. A function is called when the error is reported.
Returns
Rule — List it in the second argument of defineForm.
FormState
Import from @k8ordo/form/server
What a Server Action returns to the form. parseForm builds it and useForm reads it.
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 a path such as
items[1].name. valuesRecord<string, string | string[]>- The submitted values. After a failed submission they become the fields’ default values.
rowsRecord<string, number>- How many rows each array had, so the form renders the same number of rows without JavaScript.
formErrorstring- An error that belongs to no field.
tokenstring- Identifies one parse, so two identical failures still count as two responses.