Forms
Define questionnaires, conditional fields, and typed answers.
Forms are TypeScript definitions passed through forms, or live questionnaire
rows saved with saveForm. Code-authored forms feed $Infer; database forms
are intentionally dynamic. status defaults to "active"; set it explicitly
when a form should begin as a draft or remain archived.
import { defineForm } from "@dimah-form/server";
export const onboarding = defineForm({
title: "Employee onboarding",
slug: "onboarding",
status: "active",
fields: [
{ id: "name", type: "text", label: "Full name", required: true },
{
id: "team",
type: "select",
label: "Team",
required: true,
options: [
{ value: "engineering", label: "Engineering" },
{ value: "design", label: "Design" },
],
},
{
id: "github",
type: "text",
label: "GitHub username",
showWhen: { field: "team", equals: "engineering" },
},
],
});export const form = dimahForm({
database: memoryAdapter(),
forms: { onboarding },
});
export type Form = typeof form;id is the catalog key; slug defaults to it. getForm and
startResponse accept either value. Only an "active" form can start a
response.
Conditional fields
showWhen is sibling visibility. A hidden field is omitted from
visibleFields, and its answer is stripped on submit.
showWhen: { field: "role", equals: "manager" }
showWhen: { field: "role", equals: ["manager", "lead"] }
showWhen: { field: "plan", notEquals: "free" }
showWhen: { field: "stack", includes: "typescript" }
showWhen: { field: "stack", includes: ["typescript", "rust"] }
showWhen: {
all: [
{ field: "level", equals: "senior" },
{ field: "location", equals: "remote" },
],
}Use all or any for nested rules. The referenced field must be a sibling;
cycles, unknown targets, and invalid values are rejected when the definition
is validated. A scalar list on equals or includes is a one-of match;
notEquals is its inverse.
import type { FieldShowWhenCompare } from "@dimah-form/server";Prop
Type
Group rules with all or any. Both can nest a comparison or another group.
Cross-field validation
Use validateAnswers for checks that depend on more than one field. The server
is authoritative; pass the same isomorphic validator to the client when you
also want immediate feedback.
import type { AnswersValidator } from "@dimah-form/core";
export const validateAnswers: AnswersValidator = (_form, answers) => {
if (
typeof answers.email === "string" &&
typeof answers.confirmEmail === "string" &&
answers.email !== answers.confirmEmail
) {
return [
{
field: "confirmEmail",
code: "EMAIL_MISMATCH",
message: "Email addresses must match",
},
];
}
};dimahForm({ database, forms, validateAnswers });
createFormClient<Form>({ validateAnswers });Code forms and live forms
| Concern | forms: {} | saveForm() |
|---|---|---|
| Authoring | TypeScript in your application | A live database row |
| Answer inference | Form["$Infer"]["answers"] | Record<string, unknown> |
| Updating | Edit the source definition | Allowed; existing response snapshots do not change |
| Deleting | Protected from the API | Allowed only when no responses remain |
For a code-authored form, optional fields are optional in $Infer; a required
field behind showWhen is also optional because it may be invisible.
When updating a live form, send the last updatedAt returned by the server.
Concurrent edits fail with STALE_UPDATE instead of overwriting one another.
type OnboardingAnswers = Form["$Infer"]["answers"]["onboarding"];Built-in constraints and answer shapes are in Field types. For validators beyond the built-ins, see Custom fields.