Responses
Snapshot definitions, drafts, lifecycle states, and compare-and-swap writes.
startResponse copies the active form into response.definition. Drafts,
visibility rules, and submit validation use that snapshot—not the current live
questionnaire.
Editing a form never changes an in-flight draft or a submitted response.
Lifecycle
| Status | Meaning | Available transitions |
|---|---|---|
draft | Answers may be incomplete | Save, submit, abandon |
submitted | Visible required answers passed | Reopen or delete |
abandoned | Closed without submitting | Reopen or delete |
| Call | Effect |
|---|---|
startResponse | Freezes the definition and applies defaultValue values |
saveDraft | Applies an answer patch; null removes a key |
submitResponse | Replaces answers when provided, validates visible fields, then locks the response |
abandonResponse | Locks an unfinished response |
reopenResponse | Returns a submitted or abandoned response to draft without changing its snapshot |
saveDraft({ answers }) is a patch. submitResponse({ answers }) treats
answers as the complete replacement; omit it to submit the stored draft as
is. Submit strips hidden values before validation and persistence.
Pass { resume: true, respondentId } to startResponse to reuse the latest
draft for that respondent. The server rejects resume: true without a
respondentId. In authenticated applications, resolve that id on the server
rather than accepting it from browser input. See Security.
Concurrent edits
Draft writes and submits accept the updatedAt token from the last read. The
store writes only if it still matches; otherwise the request fails with
STALE_UPDATE. useFormResponse refreshes a session on that conflict.
Do not omit updatedAt unless an intentional last-write-wins update is the
desired behavior.
Stored record
import type { ResponseRecord } from "@dimah-form/react";Prop
Type
List routes can omit the definition and answers:
import type { ResponseSummary } from "@dimah-form/react";Prop
Type
Set respondentId on the server in onStart; never trust a browser-supplied
owner id. See Security.