@form-engine-ts/core 2.5.0 → 2.5.1

package/README.md

@@ -77,13 +77,21 @@ Results are ordered by `submittedAt`, then submission ID. Both boundaries are in
 ## Versioning, incremental analytics, and paged storage
 
 `cloneVersionToDraft`, `publishDraft`, and `deleteDraft` implement revision-checked version transitions as pure functions.
+Clone/delete operations accept `expectedRevision`; cloning rejects non-published sources, publish validation failures are
+returned as typed `validation_failed` issues, and successful publishing reports every archived record. Storage adapters
+that can commit the resulting changes atomically implement `VersionedFormStorageAdapter` and `VersionTransitionPlan`.
 `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`.
+free-text bodies. In lenient mode, mismatched responses are skipped and exposed by `addMany()` and `getReport()` instead of
+being included silently. 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.
+custom `CsvColumnDef` columns. Custom getters receive the submission, form version, and schema. Use
+`pipeResponsesToCsvStream` to write to a Web `WritableStream` or Node-compatible writable while honoring backpressure.
+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.
+cursor combines `submittedAt` and response ID, so equal timestamps do not produce gaps or duplicates. `metadataFilters`
+and `filter` are applied before page sizing.
 
 See the [project documentation](https://github.com/nitta-a/form-engine-ts#readme) for the complete schema and API guide.

package/dist/index.cjs

@@ -41,7 +41,9 @@ __export(index_exports, {
   exportResponsesToCsvStream: () => exportResponsesToCsvStream,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
   isQuestionVisible: () => isQuestionVisible,
+  matchesSubmissionPageFilters: () => matchesSubmissionPageFilters,
   normalizeSubmissionPageSize: () => normalizeSubmissionPageSize,
+  pipeResponsesToCsvStream: () => pipeResponsesToCsvStream,
   populateSchemaTranslations: () => populateSchemaTranslations,
   publishDraft: () => publishDraft,
   resolveFormTranslation: () => resolveFormTranslation,
@@ -1101,17 +1103,38 @@ function aggregateResponses(schema, submissions) {
   };
 }
 function responseValues(submission) {
-  return "values" in submission ? submission.values : submission.answers;
+  if (typeof submission !== "object" || submission === null) return void 0;
+  if ("values" in submission) return submission.values;
+  return "answers" in submission ? submission.answers : void 0;
 }
 function responseIdentifier(submission) {
-  return "id" in submission ? submission.id : submission.responseId;
+  if (typeof submission !== "object" || submission === null) return "<unknown>";
+  if ("id" in submission && typeof submission.id === "string" && submission.id.length > 0) return submission.id;
+  if ("responseId" in submission && typeof submission.responseId === "string" && submission.responseId.length > 0) {
+    return submission.responseId;
+  }
+  return "<unknown>";
+}
+function isAnswerRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function responseMismatch(schema, submission) {
+function responseProblem(schema, submission) {
+  if (typeof submission !== "object" || submission === null) {
+    return { reason: "invalid_structure", error: "Submission structure is invalid." };
+  }
+  const identifier = responseIdentifier(submission);
+  const values = responseValues(submission);
+  if (typeof identifier !== "string" || identifier.length === 0 || typeof submission.formId !== "string" || typeof submission.submittedAt !== "string" || !isAnswerRecord(values)) {
+    return { reason: "invalid_structure", error: `Submission ${String(identifier)} structure is invalid.` };
+  }
   if (submission.formId !== schema.id) {
-    return `Submission ${responseIdentifier(submission)} does not match form ${schema.id}.`;
+    return { reason: "form_id_mismatch", error: `Submission ${identifier} 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}.`;
+  if ("formVersion" in submission && submission.formVersion !== void 0 && submission.formVersion !== schema.version) {
+    return {
+      reason: "version_mismatch",
+      error: `Submission ${identifier} does not match ${schema.id}@${schema.version}.`
+    };
   }
   return void 0;
 }
@@ -1119,6 +1142,7 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
   #schema;
   #mode;
   #fields;
+  #skipReasons = [];
   #submissionCount = 0;
   constructor(schema, options) {
     assertValidFormSchema(schema);
@@ -1140,9 +1164,14 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
     );
   }
   add(submission) {
-    const mismatch = responseMismatch(this.#schema, submission);
-    if (mismatch !== void 0 && this.#mode === "strict") return { success: false, error: mismatch };
+    const problem = responseProblem(this.#schema, submission);
+    if (problem !== void 0) {
+      if (this.#mode === "strict") return { success: false, error: problem.error };
+      this.#skipReasons.push({ responseId: responseIdentifier(submission), reason: problem.reason });
+      return { success: true, skipped: true };
+    }
     const values = responseValues(submission);
+    if (!isAnswerRecord(values)) throw new Error("Validated response answers are unavailable.");
     const visibility = calculateFieldVisibility(this.#schema, values);
     for (const field of this.#schema.fields) {
       const accumulator = this.#fields.get(field.id);
@@ -1172,6 +1201,7 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
       const result = this.add(submission);
       if (!result.success) throw new TypeError(result.error ?? "Submission could not be accumulated.");
     }
+    return this.getReport();
   }
   merge(other) {
     if (!(other instanceof _IncrementalResponseAccumulator)) {
@@ -1181,6 +1211,7 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
       throw new TypeError("Response accumulators must use the same schema.");
     }
     this.#submissionCount += other.#submissionCount;
+    this.#skipReasons.push(...other.#skipReasons);
     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.`);
@@ -1196,6 +1227,13 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
     }
     return this;
   }
+  getReport() {
+    return {
+      processedCount: this.#submissionCount,
+      skippedCount: this.#skipReasons.length,
+      skipReasons: this.#skipReasons.map((reason) => ({ ...reason }))
+    };
+  }
   finalize() {
     return {
       formId: this.#schema.id,
@@ -1267,6 +1305,7 @@ function asFormResponse(submission) {
     responseId: submission.id,
     formId: submission.formId,
     sourceLocale: submission.locale,
+    formVersion: submission.formVersion,
     answers: submission.values,
     submittedAt: submission.submittedAt,
     ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
@@ -1290,8 +1329,8 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
   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 problem = responseProblem(schema, submission);
+    if (problem !== void 0) throw new TypeError(problem.error);
     const response = asFormResponse(submission);
     const answers = response.answers;
     const visible = selectVisibleAnswers(schema, answers);
@@ -1301,11 +1340,64 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
       response.sourceLocale ?? "",
       ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
     ] : [];
-    const customCells = customColumns.map((column) => column.getValue(response));
+    const context = {
+      ...response,
+      submission: response,
+      formVersion: response.formVersion ?? schema.version,
+      schema
+    };
+    const customCells = customColumns.map((column) => column.getValue(context));
     yield `\r
 ${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
   }
 }
+function isWebWritableStream(writable) {
+  return "getWriter" in writable && typeof writable.getWriter === "function";
+}
+async function writeNodeChunk(writable, chunk, streamError) {
+  if (writable.write(chunk)) return;
+  let onDrain;
+  const drain = new Promise((resolve) => {
+    onDrain = resolve;
+    writable.once("drain", resolve);
+  });
+  try {
+    await Promise.race([drain, streamError]);
+  } finally {
+    if (onDrain !== void 0) writable.removeListener("drain", onDrain);
+  }
+}
+async function pipeResponsesToCsvStream(schema, submissions, writable, options = {}) {
+  const encoder = new TextEncoder();
+  if (isWebWritableStream(writable)) {
+    const writer = writable.getWriter();
+    try {
+      for await (const chunk of exportResponsesToCsvStream(schema, submissions, options)) {
+        await writer.write(encoder.encode(chunk));
+      }
+      await writer.close();
+    } catch (cause) {
+      await writer.abort(cause);
+      throw cause;
+    } finally {
+      writer.releaseLock();
+    }
+    return;
+  }
+  let onStreamError;
+  const streamError = new Promise((_resolve, reject) => {
+    onStreamError = reject;
+    writable.once("error", reject);
+  });
+  try {
+    for await (const chunk of exportResponsesToCsvStream(schema, submissions, options)) {
+      await writeNodeChunk(writable, encoder.encode(chunk), streamError);
+    }
+    await Promise.race([new Promise((resolve) => writable.end(resolve)), streamError]);
+  } finally {
+    if (onStreamError !== void 0) writable.removeListener("error", onStreamError);
+  }
+}
 function exportResponsesToCsv(schema, responses, options = {}) {
   assertValidFormSchema(schema);
   for (const response of responses) {
@@ -1477,6 +1569,32 @@ function normalizeSubmissionPageSize(pageSize, fallback = 100) {
   if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("pageSize must be a positive safe integer.");
   return value;
 }
+function isJsonArray(value) {
+  return Array.isArray(value);
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !isJsonArray(value);
+}
+function jsonValuesEqual(left, right) {
+  if (left === right) return true;
+  if (left === void 0 || left === null || right === void 0 || right === null || typeof left !== typeof right) {
+    return false;
+  }
+  if (isJsonArray(left) || isJsonArray(right)) {
+    return isJsonArray(left) && isJsonArray(right) && left.length === right.length && left.every((value, index) => jsonValuesEqual(value, right[index]));
+  }
+  if (!isJsonObject(left) || !isJsonObject(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]));
+}
+function matchesSubmissionPageFilters(submission, options) {
+  if (options.filter !== void 0 && !options.filter(submission)) return false;
+  if (options.metadataFilters === void 0) return true;
+  return Object.entries(options.metadataFilters).every(
+    ([key, value]) => jsonValuesEqual(submission.metadata?.[key], value)
+  );
+}
 
 // src/validation.ts
 var DEFAULT_MESSAGES = {
@@ -1915,6 +2033,12 @@ async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocal
 }
 
 // src/versioning.ts
+function revisionConflict(state, expectedRevision) {
+  return expectedRevision === void 0 || expectedRevision === state.revision ? void 0 : {
+    success: false,
+    error: { type: "revision_conflict", expectedRevision, actualRevision: state.revision }
+  };
+}
 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) {
@@ -1927,9 +2051,25 @@ function validateState(state) {
 function cloneVersionToDraft(state, sourceSchema, options = {}) {
   validateState(state);
   if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
   if (state.draftVersion !== void 0) {
     return { success: false, error: { type: "draft_already_exists", currentDraftVersion: state.draftVersion } };
   }
+  const allowedSourceVersions = /* @__PURE__ */ new Set([
+    ...state.publishedVersion === void 0 ? [] : [state.publishedVersion],
+    ...options.allowedSourceVersions ?? []
+  ]);
+  if (!allowedSourceVersions.has(sourceSchema.version)) {
+    return {
+      success: false,
+      error: {
+        type: "invalid_source_version",
+        requestedVersion: sourceSchema.version,
+        ...state.publishedVersion === void 0 ? {} : { publishedVersion: state.publishedVersion }
+      }
+    };
+  }
   const maxVersions = options.maxVersions ?? Number.MAX_SAFE_INTEGER;
   if (!Number.isSafeInteger(maxVersions) || maxVersions < 1) {
     throw new TypeError("maxVersions must be a positive safe integer.");
@@ -1953,23 +2093,32 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
 }
 function publishDraft(state, draftSchema, options = {}) {
   validateState(state);
-  if (options.expectedRevision !== void 0 && options.expectedRevision !== state.revision) {
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
+  if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  const validation = options.validate?.(draftSchema);
+  if (validation === false || Array.isArray(validation) && validation.length > 0) {
     return {
       success: false,
-      error: {
-        type: "revision_conflict",
-        expectedRevision: options.expectedRevision,
-        actualRevision: state.revision
-      }
+      error: { type: "validation_failed", issues: Array.isArray(validation) ? validation : [] }
     };
   }
-  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 archivedRecords = archivedVersion === void 0 ? [] : [
+    {
+      formId: state.formId,
+      version: archivedVersion,
+      status: "archived",
+      schema: { ...draftSchema, version: archivedVersion },
+      createdAt: timestamp,
+      publishedAt: timestamp,
+      archivedAt: timestamp
+    }
+  ];
   const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
   return {
     success: true,
@@ -1987,12 +2136,15 @@ function publishDraft(state, draftSchema, options = {}) {
         createdAt: timestamp,
         publishedAt: timestamp
       },
+      archivedRecords,
       ...archivedVersion === void 0 ? {} : { archivedVersion }
     }
   };
 }
-function deleteDraft(state) {
+function deleteDraft(state, options = {}) {
   validateState(state);
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
   if (state.draftVersion === void 0) return { success: false, error: { type: "draft_not_found" } };
   const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
   return {
@@ -2029,7 +2181,9 @@ function assertVersionMutable(status) {
   exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  matchesSubmissionPageFilters,
   normalizeSubmissionPageSize,
+  pipeResponsesToCsvStream,
   populateSchemaTranslations,
   publishDraft,
   resolveFormTranslation,

package/dist/index.d.cts

@@ -1,3 +1,82 @@
+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: "invalid_source_version";
+    readonly requestedVersion: number;
+    readonly publishedVersion?: number;
+} | {
+    readonly type: "version_immutable";
+    readonly status: FormVersionStatus;
+} | {
+    readonly type: "max_version_exceeded";
+    readonly max: number;
+} | {
+    readonly type: "validation_failed";
+    readonly issues: readonly SchemaIssue[];
+};
+interface CloneVersionOptions {
+    readonly maxVersions?: number;
+    readonly expectedRevision?: number;
+    /** Additional known published versions that may be used as a clone source. */
+    readonly allowedSourceVersions?: readonly number[];
+}
+interface PublishDraftOptions {
+    readonly expectedRevision?: number;
+    readonly validate?: (schema: FormSchema) => boolean | readonly SchemaIssue[];
+    /** Supplies deterministic record timestamps while keeping the transition pure. */
+    readonly timestamp?: string;
+}
+interface DeleteDraftOptions {
+    readonly expectedRevision?: number;
+}
+interface PublishDraftResult {
+    readonly nextState: FormVersionState;
+    readonly publishedRecord: FormVersionRecord;
+    readonly archivedRecords: readonly FormVersionRecord[];
+    /** @deprecated Read archivedRecords instead. */
+    readonly archivedVersion?: number;
+}
+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<PublishDraftResult, VersionTransitionError>;
+declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+}, VersionTransitionError>;
+declare function assertVersionMutable(status: FormVersionStatus): void;
+
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
 interface FormPolicy {
     readonly allowedFieldTypes?: readonly FieldType[];
@@ -170,6 +249,8 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
+    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
@@ -179,6 +260,19 @@ interface SubmissionPage {
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
 }
+interface VersionTransitionPlan {
+    readonly state: FormVersionState;
+    readonly expectedRevision: number;
+    readonly draftToPublish?: FormSchema;
+    readonly versionsToArchive: readonly number[];
+    readonly versionsToDelete: readonly number[];
+}
+interface VersionedFormStorageAdapter extends FormStorageAdapter {
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
+}
 interface BaseQuestionAggregate {
     readonly fieldId: string;
     readonly answeredCount: number;
@@ -223,6 +317,7 @@ type ChoiceOption = FieldOption;
 interface FormResponse extends ExtensibleNode {
     readonly responseId: string;
     readonly formId: string;
+    readonly formVersion?: number;
     readonly sourceLocale?: string;
     readonly answers: Readonly<Record<string, unknown>>;
     readonly submittedAt: string;
@@ -251,14 +346,25 @@ declare function calculateNumericSummary(responses: readonly FormSubmission[], q
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
 type AccumulatorResponse = FormSubmission | FormResponse;
+type AccumulatorSkipReason = "form_id_mismatch" | "version_mismatch" | "invalid_structure";
+interface AccumulatorReport {
+    readonly processedCount: number;
+    readonly skippedCount: number;
+    readonly skipReasons: readonly {
+        readonly responseId: string;
+        readonly reason: AccumulatorSkipReason;
+    }[];
+}
 interface ResponseAccumulator {
     add(submission: AccumulatorResponse): {
         readonly success: boolean;
+        readonly skipped?: boolean;
         readonly error?: string;
     };
-    addMany(submissions: Iterable<AccumulatorResponse>): void;
+    addMany(submissions: Iterable<AccumulatorResponse>): AccumulatorReport;
     merge(other: ResponseAccumulator): ResponseAccumulator;
     finalize(): FormAnalytics;
+    getReport(): AccumulatorReport;
 }
 interface ResponseAccumulatorOptions {
     readonly mode?: "strict" | "lenient";
@@ -271,13 +377,27 @@ interface CsvExportOptions {
 }
 interface CsvColumnDef {
     readonly header: string;
-    readonly getValue: (submission: FormResponse) => string | number | boolean | null | undefined;
+    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined;
+}
+interface CsvColumnContext extends FormResponse {
+    readonly submission: FormResponse;
+    readonly formVersion: number;
+    readonly schema: FormSchema;
 }
 interface StreamCsvOptions extends CsvExportOptions {
     readonly columns?: readonly CsvColumnDef[];
     readonly includeDefaultColumns?: boolean;
 }
 declare function exportResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, options?: StreamCsvOptions): AsyncIterable<string>;
+interface NodeWritableStream {
+    write(chunk: Uint8Array): boolean;
+    once(event: "drain", listener: () => void): unknown;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    removeListener(event: "drain", listener: () => void): unknown;
+    removeListener(event: "error", listener: (error: Error) => void): unknown;
+    end(callback: () => void): unknown;
+}
+declare function pipeResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, writable: WritableStream<Uint8Array> | NodeWritableStream, options?: StreamCsvOptions): Promise<void>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
 type FormEventType = "response.submitted" | "schema.updated";
@@ -314,6 +434,7 @@ interface SubmissionCursorValue {
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
     readonly defaultLocale?: string;
@@ -382,73 +503,10 @@ 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 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 };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, 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 CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, 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 NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, 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 VersionTransitionPlan, type VersionedFormStorageAdapter, 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, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -1,3 +1,82 @@
+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: "invalid_source_version";
+    readonly requestedVersion: number;
+    readonly publishedVersion?: number;
+} | {
+    readonly type: "version_immutable";
+    readonly status: FormVersionStatus;
+} | {
+    readonly type: "max_version_exceeded";
+    readonly max: number;
+} | {
+    readonly type: "validation_failed";
+    readonly issues: readonly SchemaIssue[];
+};
+interface CloneVersionOptions {
+    readonly maxVersions?: number;
+    readonly expectedRevision?: number;
+    /** Additional known published versions that may be used as a clone source. */
+    readonly allowedSourceVersions?: readonly number[];
+}
+interface PublishDraftOptions {
+    readonly expectedRevision?: number;
+    readonly validate?: (schema: FormSchema) => boolean | readonly SchemaIssue[];
+    /** Supplies deterministic record timestamps while keeping the transition pure. */
+    readonly timestamp?: string;
+}
+interface DeleteDraftOptions {
+    readonly expectedRevision?: number;
+}
+interface PublishDraftResult {
+    readonly nextState: FormVersionState;
+    readonly publishedRecord: FormVersionRecord;
+    readonly archivedRecords: readonly FormVersionRecord[];
+    /** @deprecated Read archivedRecords instead. */
+    readonly archivedVersion?: number;
+}
+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<PublishDraftResult, VersionTransitionError>;
+declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+}, VersionTransitionError>;
+declare function assertVersionMutable(status: FormVersionStatus): void;
+
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
 interface FormPolicy {
     readonly allowedFieldTypes?: readonly FieldType[];
@@ -170,6 +249,8 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
+    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
@@ -179,6 +260,19 @@ interface SubmissionPage {
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
 }
+interface VersionTransitionPlan {
+    readonly state: FormVersionState;
+    readonly expectedRevision: number;
+    readonly draftToPublish?: FormSchema;
+    readonly versionsToArchive: readonly number[];
+    readonly versionsToDelete: readonly number[];
+}
+interface VersionedFormStorageAdapter extends FormStorageAdapter {
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
+}
 interface BaseQuestionAggregate {
     readonly fieldId: string;
     readonly answeredCount: number;
@@ -223,6 +317,7 @@ type ChoiceOption = FieldOption;
 interface FormResponse extends ExtensibleNode {
     readonly responseId: string;
     readonly formId: string;
+    readonly formVersion?: number;
     readonly sourceLocale?: string;
     readonly answers: Readonly<Record<string, unknown>>;
     readonly submittedAt: string;
@@ -251,14 +346,25 @@ declare function calculateNumericSummary(responses: readonly FormSubmission[], q
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
 type AccumulatorResponse = FormSubmission | FormResponse;
+type AccumulatorSkipReason = "form_id_mismatch" | "version_mismatch" | "invalid_structure";
+interface AccumulatorReport {
+    readonly processedCount: number;
+    readonly skippedCount: number;
+    readonly skipReasons: readonly {
+        readonly responseId: string;
+        readonly reason: AccumulatorSkipReason;
+    }[];
+}
 interface ResponseAccumulator {
     add(submission: AccumulatorResponse): {
         readonly success: boolean;
+        readonly skipped?: boolean;
         readonly error?: string;
     };
-    addMany(submissions: Iterable<AccumulatorResponse>): void;
+    addMany(submissions: Iterable<AccumulatorResponse>): AccumulatorReport;
     merge(other: ResponseAccumulator): ResponseAccumulator;
     finalize(): FormAnalytics;
+    getReport(): AccumulatorReport;
 }
 interface ResponseAccumulatorOptions {
     readonly mode?: "strict" | "lenient";
@@ -271,13 +377,27 @@ interface CsvExportOptions {
 }
 interface CsvColumnDef {
     readonly header: string;
-    readonly getValue: (submission: FormResponse) => string | number | boolean | null | undefined;
+    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined;
+}
+interface CsvColumnContext extends FormResponse {
+    readonly submission: FormResponse;
+    readonly formVersion: number;
+    readonly schema: FormSchema;
 }
 interface StreamCsvOptions extends CsvExportOptions {
     readonly columns?: readonly CsvColumnDef[];
     readonly includeDefaultColumns?: boolean;
 }
 declare function exportResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, options?: StreamCsvOptions): AsyncIterable<string>;
+interface NodeWritableStream {
+    write(chunk: Uint8Array): boolean;
+    once(event: "drain", listener: () => void): unknown;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    removeListener(event: "drain", listener: () => void): unknown;
+    removeListener(event: "error", listener: (error: Error) => void): unknown;
+    end(callback: () => void): unknown;
+}
+declare function pipeResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, writable: WritableStream<Uint8Array> | NodeWritableStream, options?: StreamCsvOptions): Promise<void>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
 type FormEventType = "response.submitted" | "schema.updated";
@@ -314,6 +434,7 @@ interface SubmissionCursorValue {
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
     readonly defaultLocale?: string;
@@ -382,73 +503,10 @@ 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 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 };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, 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 CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, 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 NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, 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 VersionTransitionPlan, type VersionedFormStorageAdapter, 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, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.js

@@ -1043,17 +1043,38 @@ function aggregateResponses(schema, submissions) {
   };
 }
 function responseValues(submission) {
-  return "values" in submission ? submission.values : submission.answers;
+  if (typeof submission !== "object" || submission === null) return void 0;
+  if ("values" in submission) return submission.values;
+  return "answers" in submission ? submission.answers : void 0;
 }
 function responseIdentifier(submission) {
-  return "id" in submission ? submission.id : submission.responseId;
+  if (typeof submission !== "object" || submission === null) return "<unknown>";
+  if ("id" in submission && typeof submission.id === "string" && submission.id.length > 0) return submission.id;
+  if ("responseId" in submission && typeof submission.responseId === "string" && submission.responseId.length > 0) {
+    return submission.responseId;
+  }
+  return "<unknown>";
+}
+function isAnswerRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function responseMismatch(schema, submission) {
+function responseProblem(schema, submission) {
+  if (typeof submission !== "object" || submission === null) {
+    return { reason: "invalid_structure", error: "Submission structure is invalid." };
+  }
+  const identifier = responseIdentifier(submission);
+  const values = responseValues(submission);
+  if (typeof identifier !== "string" || identifier.length === 0 || typeof submission.formId !== "string" || typeof submission.submittedAt !== "string" || !isAnswerRecord(values)) {
+    return { reason: "invalid_structure", error: `Submission ${String(identifier)} structure is invalid.` };
+  }
   if (submission.formId !== schema.id) {
-    return `Submission ${responseIdentifier(submission)} does not match form ${schema.id}.`;
+    return { reason: "form_id_mismatch", error: `Submission ${identifier} 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}.`;
+  if ("formVersion" in submission && submission.formVersion !== void 0 && submission.formVersion !== schema.version) {
+    return {
+      reason: "version_mismatch",
+      error: `Submission ${identifier} does not match ${schema.id}@${schema.version}.`
+    };
   }
   return void 0;
 }
@@ -1061,6 +1082,7 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
   #schema;
   #mode;
   #fields;
+  #skipReasons = [];
   #submissionCount = 0;
   constructor(schema, options) {
     assertValidFormSchema(schema);
@@ -1082,9 +1104,14 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
     );
   }
   add(submission) {
-    const mismatch = responseMismatch(this.#schema, submission);
-    if (mismatch !== void 0 && this.#mode === "strict") return { success: false, error: mismatch };
+    const problem = responseProblem(this.#schema, submission);
+    if (problem !== void 0) {
+      if (this.#mode === "strict") return { success: false, error: problem.error };
+      this.#skipReasons.push({ responseId: responseIdentifier(submission), reason: problem.reason });
+      return { success: true, skipped: true };
+    }
     const values = responseValues(submission);
+    if (!isAnswerRecord(values)) throw new Error("Validated response answers are unavailable.");
     const visibility = calculateFieldVisibility(this.#schema, values);
     for (const field of this.#schema.fields) {
       const accumulator = this.#fields.get(field.id);
@@ -1114,6 +1141,7 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
       const result = this.add(submission);
       if (!result.success) throw new TypeError(result.error ?? "Submission could not be accumulated.");
     }
+    return this.getReport();
   }
   merge(other) {
     if (!(other instanceof _IncrementalResponseAccumulator)) {
@@ -1123,6 +1151,7 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
       throw new TypeError("Response accumulators must use the same schema.");
     }
     this.#submissionCount += other.#submissionCount;
+    this.#skipReasons.push(...other.#skipReasons);
     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.`);
@@ -1138,6 +1167,13 @@ var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
     }
     return this;
   }
+  getReport() {
+    return {
+      processedCount: this.#submissionCount,
+      skippedCount: this.#skipReasons.length,
+      skipReasons: this.#skipReasons.map((reason) => ({ ...reason }))
+    };
+  }
   finalize() {
     return {
       formId: this.#schema.id,
@@ -1209,6 +1245,7 @@ function asFormResponse(submission) {
     responseId: submission.id,
     formId: submission.formId,
     sourceLocale: submission.locale,
+    formVersion: submission.formVersion,
     answers: submission.values,
     submittedAt: submission.submittedAt,
     ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
@@ -1232,8 +1269,8 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
   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 problem = responseProblem(schema, submission);
+    if (problem !== void 0) throw new TypeError(problem.error);
     const response = asFormResponse(submission);
     const answers = response.answers;
     const visible = selectVisibleAnswers(schema, answers);
@@ -1243,11 +1280,64 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
       response.sourceLocale ?? "",
       ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
     ] : [];
-    const customCells = customColumns.map((column) => column.getValue(response));
+    const context = {
+      ...response,
+      submission: response,
+      formVersion: response.formVersion ?? schema.version,
+      schema
+    };
+    const customCells = customColumns.map((column) => column.getValue(context));
     yield `\r
 ${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
   }
 }
+function isWebWritableStream(writable) {
+  return "getWriter" in writable && typeof writable.getWriter === "function";
+}
+async function writeNodeChunk(writable, chunk, streamError) {
+  if (writable.write(chunk)) return;
+  let onDrain;
+  const drain = new Promise((resolve) => {
+    onDrain = resolve;
+    writable.once("drain", resolve);
+  });
+  try {
+    await Promise.race([drain, streamError]);
+  } finally {
+    if (onDrain !== void 0) writable.removeListener("drain", onDrain);
+  }
+}
+async function pipeResponsesToCsvStream(schema, submissions, writable, options = {}) {
+  const encoder = new TextEncoder();
+  if (isWebWritableStream(writable)) {
+    const writer = writable.getWriter();
+    try {
+      for await (const chunk of exportResponsesToCsvStream(schema, submissions, options)) {
+        await writer.write(encoder.encode(chunk));
+      }
+      await writer.close();
+    } catch (cause) {
+      await writer.abort(cause);
+      throw cause;
+    } finally {
+      writer.releaseLock();
+    }
+    return;
+  }
+  let onStreamError;
+  const streamError = new Promise((_resolve, reject) => {
+    onStreamError = reject;
+    writable.once("error", reject);
+  });
+  try {
+    for await (const chunk of exportResponsesToCsvStream(schema, submissions, options)) {
+      await writeNodeChunk(writable, encoder.encode(chunk), streamError);
+    }
+    await Promise.race([new Promise((resolve) => writable.end(resolve)), streamError]);
+  } finally {
+    if (onStreamError !== void 0) writable.removeListener("error", onStreamError);
+  }
+}
 function exportResponsesToCsv(schema, responses, options = {}) {
   assertValidFormSchema(schema);
   for (const response of responses) {
@@ -1419,6 +1509,32 @@ function normalizeSubmissionPageSize(pageSize, fallback = 100) {
   if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("pageSize must be a positive safe integer.");
   return value;
 }
+function isJsonArray(value) {
+  return Array.isArray(value);
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !isJsonArray(value);
+}
+function jsonValuesEqual(left, right) {
+  if (left === right) return true;
+  if (left === void 0 || left === null || right === void 0 || right === null || typeof left !== typeof right) {
+    return false;
+  }
+  if (isJsonArray(left) || isJsonArray(right)) {
+    return isJsonArray(left) && isJsonArray(right) && left.length === right.length && left.every((value, index) => jsonValuesEqual(value, right[index]));
+  }
+  if (!isJsonObject(left) || !isJsonObject(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]));
+}
+function matchesSubmissionPageFilters(submission, options) {
+  if (options.filter !== void 0 && !options.filter(submission)) return false;
+  if (options.metadataFilters === void 0) return true;
+  return Object.entries(options.metadataFilters).every(
+    ([key, value]) => jsonValuesEqual(submission.metadata?.[key], value)
+  );
+}
 
 // src/validation.ts
 var DEFAULT_MESSAGES = {
@@ -1857,6 +1973,12 @@ async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocal
 }
 
 // src/versioning.ts
+function revisionConflict(state, expectedRevision) {
+  return expectedRevision === void 0 || expectedRevision === state.revision ? void 0 : {
+    success: false,
+    error: { type: "revision_conflict", expectedRevision, actualRevision: state.revision }
+  };
+}
 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) {
@@ -1869,9 +1991,25 @@ function validateState(state) {
 function cloneVersionToDraft(state, sourceSchema, options = {}) {
   validateState(state);
   if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
   if (state.draftVersion !== void 0) {
     return { success: false, error: { type: "draft_already_exists", currentDraftVersion: state.draftVersion } };
   }
+  const allowedSourceVersions = /* @__PURE__ */ new Set([
+    ...state.publishedVersion === void 0 ? [] : [state.publishedVersion],
+    ...options.allowedSourceVersions ?? []
+  ]);
+  if (!allowedSourceVersions.has(sourceSchema.version)) {
+    return {
+      success: false,
+      error: {
+        type: "invalid_source_version",
+        requestedVersion: sourceSchema.version,
+        ...state.publishedVersion === void 0 ? {} : { publishedVersion: state.publishedVersion }
+      }
+    };
+  }
   const maxVersions = options.maxVersions ?? Number.MAX_SAFE_INTEGER;
   if (!Number.isSafeInteger(maxVersions) || maxVersions < 1) {
     throw new TypeError("maxVersions must be a positive safe integer.");
@@ -1895,23 +2033,32 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
 }
 function publishDraft(state, draftSchema, options = {}) {
   validateState(state);
-  if (options.expectedRevision !== void 0 && options.expectedRevision !== state.revision) {
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
+  if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  const validation = options.validate?.(draftSchema);
+  if (validation === false || Array.isArray(validation) && validation.length > 0) {
     return {
       success: false,
-      error: {
-        type: "revision_conflict",
-        expectedRevision: options.expectedRevision,
-        actualRevision: state.revision
-      }
+      error: { type: "validation_failed", issues: Array.isArray(validation) ? validation : [] }
     };
   }
-  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 archivedRecords = archivedVersion === void 0 ? [] : [
+    {
+      formId: state.formId,
+      version: archivedVersion,
+      status: "archived",
+      schema: { ...draftSchema, version: archivedVersion },
+      createdAt: timestamp,
+      publishedAt: timestamp,
+      archivedAt: timestamp
+    }
+  ];
   const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
   return {
     success: true,
@@ -1929,12 +2076,15 @@ function publishDraft(state, draftSchema, options = {}) {
         createdAt: timestamp,
         publishedAt: timestamp
       },
+      archivedRecords,
       ...archivedVersion === void 0 ? {} : { archivedVersion }
     }
   };
 }
-function deleteDraft(state) {
+function deleteDraft(state, options = {}) {
   validateState(state);
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
   if (state.draftVersion === void 0) return { success: false, error: { type: "draft_not_found" } };
   const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
   return {
@@ -1970,7 +2120,9 @@ export {
   exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  matchesSubmissionPageFilters,
   normalizeSubmissionPageSize,
+  pipeResponsesToCsvStream,
   populateSchemaTranslations,
   publishDraft,
   resolveFormTranslation,

package/package.json

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