@form-engine-ts/core 2.3.0 → 2.5.0

package/README.md

@@ -74,4 +74,16 @@ const submissions = await storage.listSubmissions("contact", 1, range);
 
 Results are ordered by `submittedAt`, then submission ID. Both boundaries are inclusive.
 
+## Versioning, incremental analytics, and paged storage
+
+`cloneVersionToDraft`, `publishDraft`, and `deleteDraft` implement revision-checked version transitions as pure functions.
+`createResponseAccumulator` incrementally counts choices, answered/unanswered values, and numeric summaries without retaining
+free-text bodies. Independent accumulators for the same schema can be merged, and `finalize()` matches `aggregateResponses`.
+
+`exportResponsesToCsvStream` accepts an `AsyncIterable`, emits the BOM/header and one chunk per response, and supports
+custom `CsvColumnDef` columns. Formula-injection neutralization applies to both default and custom columns.
+
+Adapters implementing `PagedSubmissionStorageAdapter` expose `listSubmissionPage(formId, options)`. The opaque Base64
+cursor combines `submittedAt` and response ID, so equal timestamps do not produce gaps or duplicates.
+
 See the [project documentation](https://github.com/nitta-a/form-engine-ts#readme) for the complete schema and API guide.

package/dist/index.cjs

@@ -22,19 +22,28 @@ var index_exports = {};
 __export(index_exports, {
   aggregateResponses: () => aggregateResponses,
   assertValidFormSchema: () => assertValidFormSchema,
+  assertVersionMutable: () => assertVersionMutable,
   calculateChoiceDistribution: () => calculateChoiceDistribution,
   calculateCrossTabulation: () => calculateCrossTabulation,
   calculateFieldVisibility: () => calculateFieldVisibility,
   calculateNumericSummary: () => calculateNumericSummary,
   calculatePageVisibility: () => calculatePageVisibility,
+  cloneVersionToDraft: () => cloneVersionToDraft,
   collectSchemaLocales: () => collectSchemaLocales,
+  createResponseAccumulator: () => createResponseAccumulator,
   createSubmission: () => createSubmission,
+  decodeSubmissionCursor: () => decodeSubmissionCursor,
+  deleteDraft: () => deleteDraft,
   dispatchWebhook: () => dispatchWebhook,
+  encodeSubmissionCursor: () => encodeSubmissionCursor,
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
+  exportResponsesToCsvStream: () => exportResponsesToCsvStream,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
   isQuestionVisible: () => isQuestionVisible,
+  normalizeSubmissionPageSize: () => normalizeSubmissionPageSize,
   populateSchemaTranslations: () => populateSchemaTranslations,
+  publishDraft: () => publishDraft,
   resolveFormTranslation: () => resolveFormTranslation,
   resolveLocalizedSchema: () => resolveLocalizedSchema,
   sanitizeSchema: () => sanitizeSchema,
@@ -1091,6 +1100,152 @@ function aggregateResponses(schema, submissions) {
     questions: schema.fields.map((field) => aggregateField(schema, field, submissions))
   };
 }
+function responseValues(submission) {
+  return "values" in submission ? submission.values : submission.answers;
+}
+function responseIdentifier(submission) {
+  return "id" in submission ? submission.id : submission.responseId;
+}
+function responseMismatch(schema, submission) {
+  if (submission.formId !== schema.id) {
+    return `Submission ${responseIdentifier(submission)} does not match form ${schema.id}.`;
+  }
+  if ("formVersion" in submission && submission.formVersion !== schema.version) {
+    return `Submission ${responseIdentifier(submission)} does not match ${schema.id}@${schema.version}.`;
+  }
+  return void 0;
+}
+var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
+  #schema;
+  #mode;
+  #fields;
+  #submissionCount = 0;
+  constructor(schema, options) {
+    assertValidFormSchema(schema);
+    this.#schema = JSON.parse(JSON.stringify(schema));
+    this.#mode = options.mode ?? "strict";
+    this.#fields = new Map(
+      schema.fields.map((field) => [
+        field.id,
+        {
+          answeredCount: 0,
+          total: 0,
+          minimum: null,
+          maximum: null,
+          trueCount: 0,
+          falseCount: 0,
+          optionCounts: new Map("options" in field ? field.options.map((option) => [option.id, 0]) : [])
+        }
+      ])
+    );
+  }
+  add(submission) {
+    const mismatch = responseMismatch(this.#schema, submission);
+    if (mismatch !== void 0 && this.#mode === "strict") return { success: false, error: mismatch };
+    const values = responseValues(submission);
+    const visibility = calculateFieldVisibility(this.#schema, values);
+    for (const field of this.#schema.fields) {
+      const accumulator = this.#fields.get(field.id);
+      if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+      const candidate = values[field.id];
+      if (visibility[field.id] !== true || !valueIsValid(field, candidate)) continue;
+      accumulator.answeredCount += 1;
+      if ((field.type === "number" || field.type === "rating") && typeof candidate === "number") {
+        accumulator.total += candidate;
+        accumulator.minimum = accumulator.minimum === null ? candidate : Math.min(accumulator.minimum, candidate);
+        accumulator.maximum = accumulator.maximum === null ? candidate : Math.max(accumulator.maximum, candidate);
+      } else if (field.type === "checkbox") {
+        if (candidate === true) accumulator.trueCount += 1;
+        if (candidate === false) accumulator.falseCount += 1;
+      } else if ("options" in field) {
+        const selections = Array.isArray(candidate) ? candidate : typeof candidate === "string" ? [candidate] : [];
+        for (const selection of selections) {
+          accumulator.optionCounts.set(selection, (accumulator.optionCounts.get(selection) ?? 0) + 1);
+        }
+      }
+    }
+    this.#submissionCount += 1;
+    return { success: true };
+  }
+  addMany(submissions) {
+    for (const submission of submissions) {
+      const result = this.add(submission);
+      if (!result.success) throw new TypeError(result.error ?? "Submission could not be accumulated.");
+    }
+  }
+  merge(other) {
+    if (!(other instanceof _IncrementalResponseAccumulator)) {
+      throw new TypeError("Only form-engine response accumulators can be merged.");
+    }
+    if (other.#schema.id !== this.#schema.id || other.#schema.version !== this.#schema.version || JSON.stringify(other.#schema.fields) !== JSON.stringify(this.#schema.fields)) {
+      throw new TypeError("Response accumulators must use the same schema.");
+    }
+    this.#submissionCount += other.#submissionCount;
+    for (const [fieldId, source] of other.#fields) {
+      const target = this.#fields.get(fieldId);
+      if (target === void 0) throw new Error(`Accumulator for ${fieldId} is unavailable.`);
+      target.answeredCount += source.answeredCount;
+      target.total += source.total;
+      target.minimum = target.minimum === null ? source.minimum : source.minimum === null ? target.minimum : Math.min(target.minimum, source.minimum);
+      target.maximum = target.maximum === null ? source.maximum : source.maximum === null ? target.maximum : Math.max(target.maximum, source.maximum);
+      target.trueCount += source.trueCount;
+      target.falseCount += source.falseCount;
+      for (const [optionId, count] of source.optionCounts) {
+        target.optionCounts.set(optionId, (target.optionCounts.get(optionId) ?? 0) + count);
+      }
+    }
+    return this;
+  }
+  finalize() {
+    return {
+      formId: this.#schema.id,
+      formVersion: this.#schema.version,
+      submissionCount: this.#submissionCount,
+      questions: this.#schema.fields.map((field) => {
+        const accumulator = this.#fields.get(field.id);
+        if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+        const base = {
+          fieldId: field.id,
+          answeredCount: accumulator.answeredCount,
+          unansweredCount: this.#submissionCount - accumulator.answeredCount
+        };
+        if (field.type === "text" || field.type === "textarea") return { ...base, kind: field.type };
+        if (field.type === "number" || field.type === "rating") {
+          return {
+            ...base,
+            kind: field.type,
+            minimum: accumulator.minimum,
+            maximum: accumulator.maximum,
+            average: accumulator.answeredCount === 0 ? null : accumulator.total / accumulator.answeredCount,
+            total: accumulator.total
+          };
+        }
+        if (field.type === "checkbox") {
+          return {
+            ...base,
+            kind: "checkbox",
+            trueCount: accumulator.trueCount,
+            falseCount: accumulator.falseCount,
+            truePercentageOfSubmissions: percentage(accumulator.trueCount, this.#submissionCount),
+            falsePercentageOfSubmissions: percentage(accumulator.falseCount, this.#submissionCount)
+          };
+        }
+        if (!("options" in field)) throw new TypeError(`Field ${field.id} cannot be aggregated.`);
+        return {
+          ...base,
+          kind: field.type,
+          options: field.options.map((option) => {
+            const count = accumulator.optionCounts.get(option.id) ?? 0;
+            return { id: option.id, count, percentageOfSubmissions: percentage(count, this.#submissionCount) };
+          })
+        };
+      })
+    };
+  }
+};
+function createResponseAccumulator(schema, options = {}) {
+  return new IncrementalResponseAccumulator(schema, options);
+}
 function escapeCsvCell(value, neutralizeFormulas = true) {
   if (value === null || value === void 0) return "";
   let stringValue = String(value);
@@ -1106,6 +1261,51 @@ function serializeValue(value) {
   if (value === void 0) return "";
   return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value);
 }
+function asFormResponse(submission) {
+  if (!("values" in submission)) return submission;
+  return {
+    responseId: submission.id,
+    formId: submission.formId,
+    sourceLocale: submission.locale,
+    answers: submission.values,
+    submittedAt: submission.submittedAt,
+    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
+    ...submission.translationMetadata === void 0 ? {} : { translationMetadata: submission.translationMetadata }
+  };
+}
+function serializeUnknown(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  return JSON.stringify(value);
+}
+async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
+  assertValidFormSchema(schema);
+  const includeDefaultColumns = options.includeDefaultColumns ?? true;
+  const customColumns = options.columns ?? [];
+  const headers = [
+    ...includeDefaultColumns ? ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)] : [],
+    ...customColumns.map((column) => column.header)
+  ];
+  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const header = headers.map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",");
+  yield `${options.withBom ?? true ? "\uFEFF" : ""}${header}`;
+  for await (const submission of submissions) {
+    const mismatch = responseMismatch(schema, submission);
+    if (mismatch !== void 0) throw new TypeError(mismatch);
+    const response = asFormResponse(submission);
+    const answers = response.answers;
+    const visible = selectVisibleAnswers(schema, answers);
+    const defaultCells = includeDefaultColumns ? [
+      response.responseId,
+      response.submittedAt,
+      response.sourceLocale ?? "",
+      ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
+    ] : [];
+    const customCells = customColumns.map((column) => column.getValue(response));
+    yield `\r
+${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
+  }
+}
 function exportResponsesToCsv(schema, responses, options = {}) {
   assertValidFormSchema(schema);
   for (const response of responses) {
@@ -1223,6 +1423,61 @@ function transformFieldType(field, nextType) {
   return { ...common, type: nextType, options };
 }
 
+// src/pagination.ts
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function encodeBase64(bytes) {
+  let result = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1] ?? 0;
+    const third = bytes[index + 2] ?? 0;
+    const combined = first << 16 | second << 8 | third;
+    result += BASE64_ALPHABET[combined >> 18 & 63] ?? "";
+    result += BASE64_ALPHABET[combined >> 12 & 63] ?? "";
+    result += index + 1 < bytes.length ? BASE64_ALPHABET[combined >> 6 & 63] ?? "" : "=";
+    result += index + 2 < bytes.length ? BASE64_ALPHABET[combined & 63] ?? "" : "=";
+  }
+  return result;
+}
+function decodeBase64(value) {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new TypeError("cursor must be a valid Base64 token.");
+  }
+  const bytes = [];
+  for (let index = 0; index < value.length; index += 4) {
+    const characters = value.slice(index, index + 4);
+    const sextets = [...characters].map((character) => character === "=" ? 0 : BASE64_ALPHABET.indexOf(character));
+    const combined = (sextets[0] ?? 0) << 18 | (sextets[1] ?? 0) << 12 | (sextets[2] ?? 0) << 6 | (sextets[3] ?? 0);
+    bytes.push(combined >> 16 & 255);
+    if (characters[2] !== "=") bytes.push(combined >> 8 & 255);
+    if (characters[3] !== "=") bytes.push(combined & 255);
+  }
+  return new Uint8Array(bytes);
+}
+function encodeSubmissionCursor(value) {
+  if (value.submittedAt.length === 0 || value.responseId.length === 0) {
+    throw new TypeError("Cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeSubmissionCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("submittedAt" in parsed) || typeof parsed.submittedAt !== "string" || parsed.submittedAt.length === 0 || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0) {
+      throw new TypeError("cursor payload is invalid.");
+    }
+    return { submittedAt: parsed.submittedAt, responseId: parsed.responseId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
+  }
+}
+function normalizeSubmissionPageSize(pageSize, fallback = 100) {
+  const value = pageSize ?? fallback;
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("pageSize must be a positive safe integer.");
+  return value;
+}
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -1658,23 +1913,125 @@ async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocal
   );
   return resolveLocalizedSchema(populated.schema, targetLocale);
 }
+
+// src/versioning.ts
+function validateState(state) {
+  if (state.formId.trim().length === 0) throw new TypeError("formId must not be empty.");
+  if (!Number.isSafeInteger(state.nextVersion) || state.nextVersion < 1) {
+    throw new TypeError("nextVersion must be a positive safe integer.");
+  }
+  if (!Number.isSafeInteger(state.revision) || state.revision < 0) {
+    throw new TypeError("revision must be a non-negative safe integer.");
+  }
+}
+function cloneVersionToDraft(state, sourceSchema, options = {}) {
+  validateState(state);
+  if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
+  if (state.draftVersion !== void 0) {
+    return { success: false, error: { type: "draft_already_exists", currentDraftVersion: state.draftVersion } };
+  }
+  const maxVersions = options.maxVersions ?? Number.MAX_SAFE_INTEGER;
+  if (!Number.isSafeInteger(maxVersions) || maxVersions < 1) {
+    throw new TypeError("maxVersions must be a positive safe integer.");
+  }
+  if (state.nextVersion > maxVersions) {
+    return { success: false, error: { type: "max_version_exceeded", max: maxVersions } };
+  }
+  const version = state.nextVersion;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...state,
+        draftVersion: version,
+        nextVersion: version + 1,
+        revision: state.revision + 1
+      },
+      draftSchema: { ...sourceSchema, version }
+    }
+  };
+}
+function publishDraft(state, draftSchema, options = {}) {
+  validateState(state);
+  if (options.expectedRevision !== void 0 && options.expectedRevision !== state.revision) {
+    return {
+      success: false,
+      error: {
+        type: "revision_conflict",
+        expectedRevision: options.expectedRevision,
+        actualRevision: state.revision
+      }
+    };
+  }
+  if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  if (options.validate?.(draftSchema) === false) throw new TypeError("Draft schema validation failed.");
+  const timestamp = options.timestamp ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("timestamp must be a valid date string.");
+  const archivedVersion = state.publishedVersion;
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...stateWithoutDraft,
+        publishedVersion: draftSchema.version,
+        revision: state.revision + 1
+      },
+      publishedRecord: {
+        formId: state.formId,
+        version: draftSchema.version,
+        status: "published",
+        schema: draftSchema,
+        createdAt: timestamp,
+        publishedAt: timestamp
+      },
+      ...archivedVersion === void 0 ? {} : { archivedVersion }
+    }
+  };
+}
+function deleteDraft(state) {
+  validateState(state);
+  if (state.draftVersion === void 0) return { success: false, error: { type: "draft_not_found" } };
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
+  };
+}
+function assertVersionMutable(status) {
+  if (status !== "draft") {
+    const error = { type: "version_immutable", status };
+    throw new TypeError(`A ${status} form version is immutable.`, { cause: error });
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   aggregateResponses,
   assertValidFormSchema,
+  assertVersionMutable,
   calculateChoiceDistribution,
   calculateCrossTabulation,
   calculateFieldVisibility,
   calculateNumericSummary,
   calculatePageVisibility,
+  cloneVersionToDraft,
   collectSchemaLocales,
+  createResponseAccumulator,
   createSubmission,
+  decodeSubmissionCursor,
+  deleteDraft,
   dispatchWebhook,
+  encodeSubmissionCursor,
   escapeCsvCell,
   exportResponsesToCsv,
+  exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  normalizeSubmissionPageSize,
   populateSchemaTranslations,
+  publishDraft,
   resolveFormTranslation,
   resolveLocalizedSchema,
   sanitizeSchema,

package/dist/index.d.cts

@@ -163,6 +163,22 @@ interface FormStorageAdapter extends StorageAdapter {
     deleteSchema(formId: string, formVersion: number): Promise<void>;
     deleteSubmission(submissionId: string): Promise<void>;
 }
+interface SubmissionPageQueryOptions {
+    readonly version?: number;
+    readonly cursor?: string;
+    readonly pageSize?: number;
+    readonly since?: string;
+    readonly until?: string;
+    readonly locale?: string;
+}
+interface SubmissionPage {
+    readonly items: readonly FormSubmission[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
+}
+interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
+    listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
+}
 interface BaseQuestionAggregate {
     readonly fieldId: string;
     readonly answeredCount: number;
@@ -234,11 +250,34 @@ declare function calculateChoiceDistribution(responses: readonly FormSubmission[
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
+type AccumulatorResponse = FormSubmission | FormResponse;
+interface ResponseAccumulator {
+    add(submission: AccumulatorResponse): {
+        readonly success: boolean;
+        readonly error?: string;
+    };
+    addMany(submissions: Iterable<AccumulatorResponse>): void;
+    merge(other: ResponseAccumulator): ResponseAccumulator;
+    finalize(): FormAnalytics;
+}
+interface ResponseAccumulatorOptions {
+    readonly mode?: "strict" | "lenient";
+}
+declare function createResponseAccumulator(schema: FormSchema, options?: ResponseAccumulatorOptions): ResponseAccumulator;
 declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
 interface CsvExportOptions {
     readonly withBom?: boolean;
     readonly neutralizeFormulas?: boolean;
 }
+interface CsvColumnDef {
+    readonly header: string;
+    readonly getValue: (submission: FormResponse) => string | number | boolean | null | undefined;
+}
+interface StreamCsvOptions extends CsvExportOptions {
+    readonly columns?: readonly CsvColumnDef[];
+    readonly includeDefaultColumns?: boolean;
+}
+declare function exportResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, options?: StreamCsvOptions): AsyncIterable<string>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
 type FormEventType = "response.submitted" | "schema.updated";
@@ -268,6 +307,14 @@ declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig,
  */
 declare function transformFieldType(field: FormField, nextType: QuestionType): FormField;
 
+interface SubmissionCursorValue {
+    readonly submittedAt: string;
+    readonly responseId: string;
+}
+declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
+declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
+declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+
 interface CollectedLocales {
     readonly defaultLocale?: string;
     readonly supportedLocales: readonly string[];
@@ -335,10 +382,73 @@ declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTransl
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
 declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
 
+type Result<T, E> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: E;
+};
+type FormVersionStatus = "draft" | "published" | "archived";
+interface FormVersionRecord {
+    readonly formId: string;
+    readonly version: number;
+    readonly status: FormVersionStatus;
+    readonly schema: FormSchema;
+    readonly createdAt: string;
+    readonly publishedAt?: string;
+    readonly archivedAt?: string;
+}
+interface FormVersionState {
+    readonly formId: string;
+    readonly draftVersion?: number;
+    readonly publishedVersion?: number;
+    readonly nextVersion: number;
+    readonly revision: number;
+}
+type VersionTransitionError = {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "draft_not_found";
+} | {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+} | {
+    readonly type: "version_immutable";
+    readonly status: FormVersionStatus;
+} | {
+    readonly type: "max_version_exceeded";
+    readonly max: number;
+};
+interface CloneVersionOptions {
+    readonly maxVersions?: number;
+}
+interface PublishDraftOptions {
+    readonly expectedRevision?: number;
+    readonly validate?: (schema: FormSchema) => boolean;
+    /** Supplies deterministic record timestamps while keeping the transition pure. */
+    readonly timestamp?: string;
+}
+declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: FormSchema, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly draftSchema: FormSchema;
+}, VersionTransitionError>;
+declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly publishedRecord: FormVersionRecord;
+    readonly archivedVersion?: number;
+}, VersionTransitionError>;
+declare function deleteDraft(state: FormVersionState): Result<{
+    readonly nextState: FormVersionState;
+}, VersionTransitionError>;
+declare function assertVersionMutable(status: FormVersionStatus): void;
+
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, collectSchemaLocales, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorResponse, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnDef, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, normalizeSubmissionPageSize, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -163,6 +163,22 @@ interface FormStorageAdapter extends StorageAdapter {
     deleteSchema(formId: string, formVersion: number): Promise<void>;
     deleteSubmission(submissionId: string): Promise<void>;
 }
+interface SubmissionPageQueryOptions {
+    readonly version?: number;
+    readonly cursor?: string;
+    readonly pageSize?: number;
+    readonly since?: string;
+    readonly until?: string;
+    readonly locale?: string;
+}
+interface SubmissionPage {
+    readonly items: readonly FormSubmission[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
+}
+interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
+    listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
+}
 interface BaseQuestionAggregate {
     readonly fieldId: string;
     readonly answeredCount: number;
@@ -234,11 +250,34 @@ declare function calculateChoiceDistribution(responses: readonly FormSubmission[
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
+type AccumulatorResponse = FormSubmission | FormResponse;
+interface ResponseAccumulator {
+    add(submission: AccumulatorResponse): {
+        readonly success: boolean;
+        readonly error?: string;
+    };
+    addMany(submissions: Iterable<AccumulatorResponse>): void;
+    merge(other: ResponseAccumulator): ResponseAccumulator;
+    finalize(): FormAnalytics;
+}
+interface ResponseAccumulatorOptions {
+    readonly mode?: "strict" | "lenient";
+}
+declare function createResponseAccumulator(schema: FormSchema, options?: ResponseAccumulatorOptions): ResponseAccumulator;
 declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
 interface CsvExportOptions {
     readonly withBom?: boolean;
     readonly neutralizeFormulas?: boolean;
 }
+interface CsvColumnDef {
+    readonly header: string;
+    readonly getValue: (submission: FormResponse) => string | number | boolean | null | undefined;
+}
+interface StreamCsvOptions extends CsvExportOptions {
+    readonly columns?: readonly CsvColumnDef[];
+    readonly includeDefaultColumns?: boolean;
+}
+declare function exportResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, options?: StreamCsvOptions): AsyncIterable<string>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
 type FormEventType = "response.submitted" | "schema.updated";
@@ -268,6 +307,14 @@ declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig,
  */
 declare function transformFieldType(field: FormField, nextType: QuestionType): FormField;
 
+interface SubmissionCursorValue {
+    readonly submittedAt: string;
+    readonly responseId: string;
+}
+declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
+declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
+declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+
 interface CollectedLocales {
     readonly defaultLocale?: string;
     readonly supportedLocales: readonly string[];
@@ -335,10 +382,73 @@ declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTransl
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
 declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
 
+type Result<T, E> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: E;
+};
+type FormVersionStatus = "draft" | "published" | "archived";
+interface FormVersionRecord {
+    readonly formId: string;
+    readonly version: number;
+    readonly status: FormVersionStatus;
+    readonly schema: FormSchema;
+    readonly createdAt: string;
+    readonly publishedAt?: string;
+    readonly archivedAt?: string;
+}
+interface FormVersionState {
+    readonly formId: string;
+    readonly draftVersion?: number;
+    readonly publishedVersion?: number;
+    readonly nextVersion: number;
+    readonly revision: number;
+}
+type VersionTransitionError = {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "draft_not_found";
+} | {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+} | {
+    readonly type: "version_immutable";
+    readonly status: FormVersionStatus;
+} | {
+    readonly type: "max_version_exceeded";
+    readonly max: number;
+};
+interface CloneVersionOptions {
+    readonly maxVersions?: number;
+}
+interface PublishDraftOptions {
+    readonly expectedRevision?: number;
+    readonly validate?: (schema: FormSchema) => boolean;
+    /** Supplies deterministic record timestamps while keeping the transition pure. */
+    readonly timestamp?: string;
+}
+declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: FormSchema, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly draftSchema: FormSchema;
+}, VersionTransitionError>;
+declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly publishedRecord: FormVersionRecord;
+    readonly archivedVersion?: number;
+}, VersionTransitionError>;
+declare function deleteDraft(state: FormVersionState): Result<{
+    readonly nextState: FormVersionState;
+}, VersionTransitionError>;
+declare function assertVersionMutable(status: FormVersionStatus): void;
+
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, collectSchemaLocales, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorResponse, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnDef, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, normalizeSubmissionPageSize, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.js

@@ -1042,6 +1042,152 @@ function aggregateResponses(schema, submissions) {
     questions: schema.fields.map((field) => aggregateField(schema, field, submissions))
   };
 }
+function responseValues(submission) {
+  return "values" in submission ? submission.values : submission.answers;
+}
+function responseIdentifier(submission) {
+  return "id" in submission ? submission.id : submission.responseId;
+}
+function responseMismatch(schema, submission) {
+  if (submission.formId !== schema.id) {
+    return `Submission ${responseIdentifier(submission)} does not match form ${schema.id}.`;
+  }
+  if ("formVersion" in submission && submission.formVersion !== schema.version) {
+    return `Submission ${responseIdentifier(submission)} does not match ${schema.id}@${schema.version}.`;
+  }
+  return void 0;
+}
+var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
+  #schema;
+  #mode;
+  #fields;
+  #submissionCount = 0;
+  constructor(schema, options) {
+    assertValidFormSchema(schema);
+    this.#schema = JSON.parse(JSON.stringify(schema));
+    this.#mode = options.mode ?? "strict";
+    this.#fields = new Map(
+      schema.fields.map((field) => [
+        field.id,
+        {
+          answeredCount: 0,
+          total: 0,
+          minimum: null,
+          maximum: null,
+          trueCount: 0,
+          falseCount: 0,
+          optionCounts: new Map("options" in field ? field.options.map((option) => [option.id, 0]) : [])
+        }
+      ])
+    );
+  }
+  add(submission) {
+    const mismatch = responseMismatch(this.#schema, submission);
+    if (mismatch !== void 0 && this.#mode === "strict") return { success: false, error: mismatch };
+    const values = responseValues(submission);
+    const visibility = calculateFieldVisibility(this.#schema, values);
+    for (const field of this.#schema.fields) {
+      const accumulator = this.#fields.get(field.id);
+      if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+      const candidate = values[field.id];
+      if (visibility[field.id] !== true || !valueIsValid(field, candidate)) continue;
+      accumulator.answeredCount += 1;
+      if ((field.type === "number" || field.type === "rating") && typeof candidate === "number") {
+        accumulator.total += candidate;
+        accumulator.minimum = accumulator.minimum === null ? candidate : Math.min(accumulator.minimum, candidate);
+        accumulator.maximum = accumulator.maximum === null ? candidate : Math.max(accumulator.maximum, candidate);
+      } else if (field.type === "checkbox") {
+        if (candidate === true) accumulator.trueCount += 1;
+        if (candidate === false) accumulator.falseCount += 1;
+      } else if ("options" in field) {
+        const selections = Array.isArray(candidate) ? candidate : typeof candidate === "string" ? [candidate] : [];
+        for (const selection of selections) {
+          accumulator.optionCounts.set(selection, (accumulator.optionCounts.get(selection) ?? 0) + 1);
+        }
+      }
+    }
+    this.#submissionCount += 1;
+    return { success: true };
+  }
+  addMany(submissions) {
+    for (const submission of submissions) {
+      const result = this.add(submission);
+      if (!result.success) throw new TypeError(result.error ?? "Submission could not be accumulated.");
+    }
+  }
+  merge(other) {
+    if (!(other instanceof _IncrementalResponseAccumulator)) {
+      throw new TypeError("Only form-engine response accumulators can be merged.");
+    }
+    if (other.#schema.id !== this.#schema.id || other.#schema.version !== this.#schema.version || JSON.stringify(other.#schema.fields) !== JSON.stringify(this.#schema.fields)) {
+      throw new TypeError("Response accumulators must use the same schema.");
+    }
+    this.#submissionCount += other.#submissionCount;
+    for (const [fieldId, source] of other.#fields) {
+      const target = this.#fields.get(fieldId);
+      if (target === void 0) throw new Error(`Accumulator for ${fieldId} is unavailable.`);
+      target.answeredCount += source.answeredCount;
+      target.total += source.total;
+      target.minimum = target.minimum === null ? source.minimum : source.minimum === null ? target.minimum : Math.min(target.minimum, source.minimum);
+      target.maximum = target.maximum === null ? source.maximum : source.maximum === null ? target.maximum : Math.max(target.maximum, source.maximum);
+      target.trueCount += source.trueCount;
+      target.falseCount += source.falseCount;
+      for (const [optionId, count] of source.optionCounts) {
+        target.optionCounts.set(optionId, (target.optionCounts.get(optionId) ?? 0) + count);
+      }
+    }
+    return this;
+  }
+  finalize() {
+    return {
+      formId: this.#schema.id,
+      formVersion: this.#schema.version,
+      submissionCount: this.#submissionCount,
+      questions: this.#schema.fields.map((field) => {
+        const accumulator = this.#fields.get(field.id);
+        if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+        const base = {
+          fieldId: field.id,
+          answeredCount: accumulator.answeredCount,
+          unansweredCount: this.#submissionCount - accumulator.answeredCount
+        };
+        if (field.type === "text" || field.type === "textarea") return { ...base, kind: field.type };
+        if (field.type === "number" || field.type === "rating") {
+          return {
+            ...base,
+            kind: field.type,
+            minimum: accumulator.minimum,
+            maximum: accumulator.maximum,
+            average: accumulator.answeredCount === 0 ? null : accumulator.total / accumulator.answeredCount,
+            total: accumulator.total
+          };
+        }
+        if (field.type === "checkbox") {
+          return {
+            ...base,
+            kind: "checkbox",
+            trueCount: accumulator.trueCount,
+            falseCount: accumulator.falseCount,
+            truePercentageOfSubmissions: percentage(accumulator.trueCount, this.#submissionCount),
+            falsePercentageOfSubmissions: percentage(accumulator.falseCount, this.#submissionCount)
+          };
+        }
+        if (!("options" in field)) throw new TypeError(`Field ${field.id} cannot be aggregated.`);
+        return {
+          ...base,
+          kind: field.type,
+          options: field.options.map((option) => {
+            const count = accumulator.optionCounts.get(option.id) ?? 0;
+            return { id: option.id, count, percentageOfSubmissions: percentage(count, this.#submissionCount) };
+          })
+        };
+      })
+    };
+  }
+};
+function createResponseAccumulator(schema, options = {}) {
+  return new IncrementalResponseAccumulator(schema, options);
+}
 function escapeCsvCell(value, neutralizeFormulas = true) {
   if (value === null || value === void 0) return "";
   let stringValue = String(value);
@@ -1057,6 +1203,51 @@ function serializeValue(value) {
   if (value === void 0) return "";
   return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value);
 }
+function asFormResponse(submission) {
+  if (!("values" in submission)) return submission;
+  return {
+    responseId: submission.id,
+    formId: submission.formId,
+    sourceLocale: submission.locale,
+    answers: submission.values,
+    submittedAt: submission.submittedAt,
+    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
+    ...submission.translationMetadata === void 0 ? {} : { translationMetadata: submission.translationMetadata }
+  };
+}
+function serializeUnknown(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  return JSON.stringify(value);
+}
+async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
+  assertValidFormSchema(schema);
+  const includeDefaultColumns = options.includeDefaultColumns ?? true;
+  const customColumns = options.columns ?? [];
+  const headers = [
+    ...includeDefaultColumns ? ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)] : [],
+    ...customColumns.map((column) => column.header)
+  ];
+  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const header = headers.map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",");
+  yield `${options.withBom ?? true ? "\uFEFF" : ""}${header}`;
+  for await (const submission of submissions) {
+    const mismatch = responseMismatch(schema, submission);
+    if (mismatch !== void 0) throw new TypeError(mismatch);
+    const response = asFormResponse(submission);
+    const answers = response.answers;
+    const visible = selectVisibleAnswers(schema, answers);
+    const defaultCells = includeDefaultColumns ? [
+      response.responseId,
+      response.submittedAt,
+      response.sourceLocale ?? "",
+      ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
+    ] : [];
+    const customCells = customColumns.map((column) => column.getValue(response));
+    yield `\r
+${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
+  }
+}
 function exportResponsesToCsv(schema, responses, options = {}) {
   assertValidFormSchema(schema);
   for (const response of responses) {
@@ -1174,6 +1365,61 @@ function transformFieldType(field, nextType) {
   return { ...common, type: nextType, options };
 }
 
+// src/pagination.ts
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function encodeBase64(bytes) {
+  let result = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1] ?? 0;
+    const third = bytes[index + 2] ?? 0;
+    const combined = first << 16 | second << 8 | third;
+    result += BASE64_ALPHABET[combined >> 18 & 63] ?? "";
+    result += BASE64_ALPHABET[combined >> 12 & 63] ?? "";
+    result += index + 1 < bytes.length ? BASE64_ALPHABET[combined >> 6 & 63] ?? "" : "=";
+    result += index + 2 < bytes.length ? BASE64_ALPHABET[combined & 63] ?? "" : "=";
+  }
+  return result;
+}
+function decodeBase64(value) {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new TypeError("cursor must be a valid Base64 token.");
+  }
+  const bytes = [];
+  for (let index = 0; index < value.length; index += 4) {
+    const characters = value.slice(index, index + 4);
+    const sextets = [...characters].map((character) => character === "=" ? 0 : BASE64_ALPHABET.indexOf(character));
+    const combined = (sextets[0] ?? 0) << 18 | (sextets[1] ?? 0) << 12 | (sextets[2] ?? 0) << 6 | (sextets[3] ?? 0);
+    bytes.push(combined >> 16 & 255);
+    if (characters[2] !== "=") bytes.push(combined >> 8 & 255);
+    if (characters[3] !== "=") bytes.push(combined & 255);
+  }
+  return new Uint8Array(bytes);
+}
+function encodeSubmissionCursor(value) {
+  if (value.submittedAt.length === 0 || value.responseId.length === 0) {
+    throw new TypeError("Cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeSubmissionCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("submittedAt" in parsed) || typeof parsed.submittedAt !== "string" || parsed.submittedAt.length === 0 || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0) {
+      throw new TypeError("cursor payload is invalid.");
+    }
+    return { submittedAt: parsed.submittedAt, responseId: parsed.responseId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
+  }
+}
+function normalizeSubmissionPageSize(pageSize, fallback = 100) {
+  const value = pageSize ?? fallback;
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("pageSize must be a positive safe integer.");
+  return value;
+}
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -1609,22 +1855,124 @@ async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocal
   );
   return resolveLocalizedSchema(populated.schema, targetLocale);
 }
+
+// src/versioning.ts
+function validateState(state) {
+  if (state.formId.trim().length === 0) throw new TypeError("formId must not be empty.");
+  if (!Number.isSafeInteger(state.nextVersion) || state.nextVersion < 1) {
+    throw new TypeError("nextVersion must be a positive safe integer.");
+  }
+  if (!Number.isSafeInteger(state.revision) || state.revision < 0) {
+    throw new TypeError("revision must be a non-negative safe integer.");
+  }
+}
+function cloneVersionToDraft(state, sourceSchema, options = {}) {
+  validateState(state);
+  if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
+  if (state.draftVersion !== void 0) {
+    return { success: false, error: { type: "draft_already_exists", currentDraftVersion: state.draftVersion } };
+  }
+  const maxVersions = options.maxVersions ?? Number.MAX_SAFE_INTEGER;
+  if (!Number.isSafeInteger(maxVersions) || maxVersions < 1) {
+    throw new TypeError("maxVersions must be a positive safe integer.");
+  }
+  if (state.nextVersion > maxVersions) {
+    return { success: false, error: { type: "max_version_exceeded", max: maxVersions } };
+  }
+  const version = state.nextVersion;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...state,
+        draftVersion: version,
+        nextVersion: version + 1,
+        revision: state.revision + 1
+      },
+      draftSchema: { ...sourceSchema, version }
+    }
+  };
+}
+function publishDraft(state, draftSchema, options = {}) {
+  validateState(state);
+  if (options.expectedRevision !== void 0 && options.expectedRevision !== state.revision) {
+    return {
+      success: false,
+      error: {
+        type: "revision_conflict",
+        expectedRevision: options.expectedRevision,
+        actualRevision: state.revision
+      }
+    };
+  }
+  if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  if (options.validate?.(draftSchema) === false) throw new TypeError("Draft schema validation failed.");
+  const timestamp = options.timestamp ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("timestamp must be a valid date string.");
+  const archivedVersion = state.publishedVersion;
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...stateWithoutDraft,
+        publishedVersion: draftSchema.version,
+        revision: state.revision + 1
+      },
+      publishedRecord: {
+        formId: state.formId,
+        version: draftSchema.version,
+        status: "published",
+        schema: draftSchema,
+        createdAt: timestamp,
+        publishedAt: timestamp
+      },
+      ...archivedVersion === void 0 ? {} : { archivedVersion }
+    }
+  };
+}
+function deleteDraft(state) {
+  validateState(state);
+  if (state.draftVersion === void 0) return { success: false, error: { type: "draft_not_found" } };
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
+  };
+}
+function assertVersionMutable(status) {
+  if (status !== "draft") {
+    const error = { type: "version_immutable", status };
+    throw new TypeError(`A ${status} form version is immutable.`, { cause: error });
+  }
+}
 export {
   aggregateResponses,
   assertValidFormSchema,
+  assertVersionMutable,
   calculateChoiceDistribution,
   calculateCrossTabulation,
   calculateFieldVisibility,
   calculateNumericSummary,
   calculatePageVisibility,
+  cloneVersionToDraft,
   collectSchemaLocales,
+  createResponseAccumulator,
   createSubmission,
+  decodeSubmissionCursor,
+  deleteDraft,
   dispatchWebhook,
+  encodeSubmissionCursor,
   escapeCsvCell,
   exportResponsesToCsv,
+  exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  normalizeSubmissionPageSize,
   populateSchemaTranslations,
+  publishDraft,
   resolveFormTranslation,
   resolveLocalizedSchema,
   sanitizeSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/core",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "publishConfig": {
     "access": "public"
   },