@k8ordo/form

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.

ts
formFields(input: ZodObject | FormDefinition): FormFields

Parameters

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 dropped and run on the server only. Outside production they are also reported with console.warn.

parseForm

Import from @k8ordo/form/server

Validates a submitted FormData against the schema.

ts
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 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, parseForm turns an unchecked checkbox into false and the values sent under one name into an array.
  • A field in the schema that is missing from the FormData fails with [@k8ordo/form] スキーマにあるフィールドが送信されていません: field. It appears when input was 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.

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

Parameters

schemaZodObject
A zod object schema.
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

  • 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.

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

Parameters

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.

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

Parameters

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.

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

Parameters

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 when that makes field required.
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.

ts
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.
k8ordo

React libraries that use Baseline features without holding back.