dimah-formv0.6.1
Questionnaires

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.

lib/forms/onboarding.ts
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" },
    },
  ],
});
lib/form.ts
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.

lib/validate-answers.ts
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

Concernforms: {}saveForm()
AuthoringTypeScript in your applicationA live database row
Answer inferenceForm["$Infer"]["answers"]Record<string, unknown>
UpdatingEdit the source definitionAllowed; existing response snapshots do not change
DeletingProtected from the APIAllowed 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.

Next

On this page