@form-engine-ts/core 2.5.1 → 2.7.0

package/README.md

@@ -76,22 +76,28 @@ 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.
+`cloneVersionToDraft`, asynchronous `publishDraft`, and `deleteDraft` implement revision-checked version transitions as
+pure functions. `createCloneTransitionPlan`, `createPublishTransitionPlan`, and `createDeleteDraftTransitionPlan` produce
+complete persistence plans with the next state, affected records, and immutable audit events.
 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`.
+returned as typed `validation_failed` issues, and successful publishing archives only a supplied actual published record,
+preserving its schema and metadata. `createPublishTransitionPlan` returns complete records plus expected/next revisions for
+storage adapters implementing `VersionedFormStorageAdapter` to commit atomically. Versioned adapters expose state/record
+reads and return a typed `Result` from `commitVersionTransition`, including the actual revision on concurrency conflicts.
 `createResponseAccumulator` incrementally counts choices, answered/unanswered values, and numeric summaries without retaining
 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. Custom getters receive the submission, form version, and schema. Use
+custom `CsvColumnDef` columns. Custom getters may be asynchronous and 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. `metadataFilters`
-and `filter` are applied before page sizing.
+and `filter` are applied before page sizing. `filter` accepts a composable `eq`/`in`/`range`/`exists` and/or AST; adapters
+may push supported nodes to their native query language while preserving identical client-side semantics. Adapters that
+implement `listTextAnswerPage` expose stable cursor pagination over individual text answers.
 
 See the [project documentation](https://github.com/nitta-a/form-engine-ts#readme) for the complete schema and API guide.

package/dist/index.cjs

@@ -30,17 +30,24 @@ __export(index_exports, {
   calculatePageVisibility: () => calculatePageVisibility,
   cloneVersionToDraft: () => cloneVersionToDraft,
   collectSchemaLocales: () => collectSchemaLocales,
+  createCloneTransitionPlan: () => createCloneTransitionPlan,
+  createDeleteDraftTransitionPlan: () => createDeleteDraftTransitionPlan,
+  createPublishTransitionPlan: () => createPublishTransitionPlan,
   createResponseAccumulator: () => createResponseAccumulator,
   createSubmission: () => createSubmission,
   decodeSubmissionCursor: () => decodeSubmissionCursor,
+  decodeTextAnswerCursor: () => decodeTextAnswerCursor,
   deleteDraft: () => deleteDraft,
   dispatchWebhook: () => dispatchWebhook,
   encodeSubmissionCursor: () => encodeSubmissionCursor,
+  encodeTextAnswerCursor: () => encodeTextAnswerCursor,
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
   exportResponsesToCsvStream: () => exportResponsesToCsvStream,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
   isQuestionVisible: () => isQuestionVisible,
+  jsonValuesEqual: () => jsonValuesEqual,
+  matchesSubmissionFilter: () => matchesSubmissionFilter,
   matchesSubmissionPageFilters: () => matchesSubmissionPageFilters,
   normalizeSubmissionPageSize: () => normalizeSubmissionPageSize,
   pipeResponsesToCsvStream: () => pipeResponsesToCsvStream,
@@ -1346,7 +1353,7 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
       formVersion: response.formVersion ?? schema.version,
       schema
     };
-    const customCells = customColumns.map((column) => column.getValue(context));
+    const customCells = await Promise.all(customColumns.map((column) => column.getValue(context)));
     yield `\r
 ${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
   }
@@ -1564,6 +1571,24 @@ function decodeSubmissionCursor(cursor) {
     throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
   }
 }
+function encodeTextAnswerCursor(value) {
+  if (value.responseId.length === 0 || value.fieldId.length === 0) {
+    throw new TypeError("Text answer cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeTextAnswerCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0 || !("fieldId" in parsed) || typeof parsed.fieldId !== "string" || parsed.fieldId.length === 0) {
+      throw new TypeError("text answer cursor payload is invalid.");
+    }
+    return { responseId: parsed.responseId, fieldId: parsed.fieldId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "text answer cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid text answer 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.");
@@ -1588,8 +1613,39 @@ function jsonValuesEqual(left, right) {
   const rightKeys = Object.keys(right);
   return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]));
 }
+function readSubmissionPath(submission, path) {
+  if (path.length === 0 || path.split(".").some((part) => part.length === 0 || part === "__proto__" || part === "constructor")) {
+    return void 0;
+  }
+  let current = submission;
+  for (const part of path.split(".")) {
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, part)) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function compareRangeValue(value, boundary, direction) {
+  if (typeof value === "number" && typeof boundary === "number") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  if (typeof value === "string" && typeof boundary === "string") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  return false;
+}
+function matchesSubmissionFilter(submission, filter) {
+  if (filter.op === "and") return filter.filters.every((item) => matchesSubmissionFilter(submission, item));
+  if (filter.op === "or") return filter.filters.some((item) => matchesSubmissionFilter(submission, item));
+  const value = readSubmissionPath(submission, filter.path);
+  if (filter.op === "eq") return jsonValuesEqual(value, filter.value);
+  if (filter.op === "in") return filter.values.some((candidate) => jsonValuesEqual(value, candidate));
+  if (filter.op === "exists") return filter.value ? value !== void 0 : value === void 0;
+  return (filter.from === void 0 || compareRangeValue(value, filter.from, "from")) && (filter.to === void 0 || compareRangeValue(value, filter.to, "to"));
+}
 function matchesSubmissionPageFilters(submission, options) {
-  if (options.filter !== void 0 && !options.filter(submission)) return false;
+  if (options.filter !== void 0 && !(typeof options.filter === "function" ? options.filter(submission) : matchesSubmissionFilter(submission, options.filter))) {
+    return false;
+  }
   if (options.metadataFilters === void 0) return true;
   return Object.entries(options.metadataFilters).every(
     ([key, value]) => jsonValuesEqual(submission.metadata?.[key], value)
@@ -2048,6 +2104,21 @@ function validateState(state) {
     throw new TypeError("revision must be a non-negative safe integer.");
   }
 }
+function requireTimestamp(value, name) {
+  const timestamp = value ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError(`${name} must be a valid date string.`);
+  return timestamp;
+}
+function transitionEvent(type, state, nextState, affectedVersions, occurredAt) {
+  return {
+    type,
+    formId: state.formId,
+    fromRevision: state.revision,
+    toRevision: nextState.revision,
+    affectedVersions,
+    occurredAt
+  };
+}
 function cloneVersionToDraft(state, sourceSchema, options = {}) {
   validateState(state);
   if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
@@ -2091,31 +2162,77 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
     }
   };
 }
-function publishDraft(state, draftSchema, options = {}) {
+function createCloneTransitionPlan(state, sourceRecord, options = {}) {
+  if (sourceRecord.formId !== state.formId || sourceRecord.schema.id !== sourceRecord.formId || sourceRecord.schema.version !== sourceRecord.version || sourceRecord.status !== "published" && !options.allowedSourceVersions?.includes(sourceRecord.version)) {
+    return {
+      success: false,
+      error: {
+        type: "invalid_source_version",
+        requestedVersion: sourceRecord.version,
+        ...state.publishedVersion === void 0 ? {} : { publishedVersion: state.publishedVersion }
+      }
+    };
+  }
+  const result = cloneVersionToDraft(state, sourceRecord.schema, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.clonedAt, "clonedAt");
+  const draftRecord = {
+    formId: state.formId,
+    version: result.value.draftSchema.version,
+    status: "draft",
+    schema: result.value.draftSchema,
+    revision: 1,
+    createdFromVersion: sourceRecord.version,
+    createdAt: timestamp,
+    ...options.metadata === void 0 ? {} : { metadata: options.metadata }
+  };
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToCreate: draftRecord,
+        events: [transitionEvent("draft.created", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
+function validatePublishedRecord(state, record) {
+  if (record === void 0) return;
+  if (record.formId !== state.formId || record.version !== state.publishedVersion || record.status !== "published" || record.schema.id !== record.formId || record.schema.version !== record.version) {
+    throw new TypeError("currentPublishedRecord must match the state's published version.");
+  }
+}
+function transitionTimestamp(options) {
+  return requireTimestamp(options.publishedAt ?? options.timestamp, "publishedAt");
+}
+async function publishDraft(state, draftSchema, options = {}) {
   validateState(state);
   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);
+  validatePublishedRecord(state, options.currentPublishedRecord);
+  const validation = await options.validate?.(draftSchema);
   if (validation === false || Array.isArray(validation) && validation.length > 0) {
     return {
       success: false,
       error: { type: "validation_failed", issues: Array.isArray(validation) ? validation : [] }
     };
   }
-  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 timestamp = transitionTimestamp(options);
   const archivedVersion = state.publishedVersion;
-  const archivedRecords = archivedVersion === void 0 ? [] : [
+  const archivedRecords = options.currentPublishedRecord === void 0 ? [] : [
     {
-      formId: state.formId,
-      version: archivedVersion,
+      ...options.currentPublishedRecord,
       status: "archived",
-      schema: { ...draftSchema, version: archivedVersion },
-      createdAt: timestamp,
-      publishedAt: timestamp,
+      revision: options.currentPublishedRecord.revision + 1,
       archivedAt: timestamp
     }
   ];
@@ -2133,6 +2250,8 @@ function publishDraft(state, draftSchema, options = {}) {
         version: draftSchema.version,
         status: "published",
         schema: draftSchema,
+        revision: 1,
+        ...archivedVersion === void 0 ? {} : { createdFromVersion: archivedVersion },
         createdAt: timestamp,
         publishedAt: timestamp
       },
@@ -2141,6 +2260,56 @@ function publishDraft(state, draftSchema, options = {}) {
     }
   };
 }
+async function createPublishTransitionPlan(state, draftRecord, options = {}) {
+  if (draftRecord.formId !== state.formId || draftRecord.version !== state.draftVersion || draftRecord.schema.id !== draftRecord.formId || draftRecord.schema.version !== draftRecord.version) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  if (draftRecord.status !== "draft") {
+    return { success: false, error: { type: "version_immutable", status: draftRecord.status } };
+  }
+  const expectedRevision = options.expectedRevision ?? state.revision;
+  const timestamp = transitionTimestamp(options);
+  const result = await publishDraft(state, draftRecord.schema, {
+    ...options,
+    expectedRevision,
+    publishedAt: timestamp
+  });
+  if (!result.success) return result;
+  const publishedRecordToSave = {
+    ...draftRecord,
+    status: "published",
+    revision: draftRecord.revision + 1,
+    publishedAt: timestamp
+  };
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision,
+        nextRevision: result.value.nextState.revision,
+        draftToDeleteVersion: draftRecord.version,
+        publishedRecordToSave,
+        archivedRecordsToSave: result.value.archivedRecords,
+        events: [
+          ...result.value.archivedRecords.length === 0 ? [] : [
+            transitionEvent(
+              "version.archived",
+              state,
+              result.value.nextState,
+              result.value.archivedRecords.map((record) => record.version),
+              timestamp
+            )
+          ],
+          transitionEvent("version.published", state, result.value.nextState, [draftRecord.version], timestamp)
+        ],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function deleteDraft(state, options = {}) {
   validateState(state);
   const conflict = revisionConflict(state, options.expectedRevision);
@@ -2152,6 +2321,29 @@ function deleteDraft(state, options = {}) {
     value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
   };
 }
+function createDeleteDraftTransitionPlan(state, draftRecord, options = {}) {
+  if (draftRecord.formId !== state.formId || draftRecord.version !== state.draftVersion || draftRecord.status !== "draft" || draftRecord.schema.id !== state.formId || draftRecord.schema.version !== draftRecord.version) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  const result = deleteDraft(state, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.deletedAt, "deletedAt");
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToDeleteVersion: draftRecord.version,
+        events: [transitionEvent("draft.deleted", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function assertVersionMutable(status) {
   if (status !== "draft") {
     const error = { type: "version_immutable", status };
@@ -2170,17 +2362,24 @@ function assertVersionMutable(status) {
   calculatePageVisibility,
   cloneVersionToDraft,
   collectSchemaLocales,
+  createCloneTransitionPlan,
+  createDeleteDraftTransitionPlan,
+  createPublishTransitionPlan,
   createResponseAccumulator,
   createSubmission,
   decodeSubmissionCursor,
+  decodeTextAnswerCursor,
   deleteDraft,
   dispatchWebhook,
   encodeSubmissionCursor,
+  encodeTextAnswerCursor,
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  jsonValuesEqual,
+  matchesSubmissionFilter,
   matchesSubmissionPageFilters,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,

package/dist/index.d.cts

@@ -6,11 +6,13 @@ type Result<T, E> = {
     readonly error: E;
 };
 type FormVersionStatus = "draft" | "published" | "archived";
-interface FormVersionRecord {
+interface FormVersionRecord extends ExtensibleNode {
     readonly formId: string;
     readonly version: number;
     readonly status: FormVersionStatus;
     readonly schema: FormSchema;
+    readonly revision: number;
+    readonly createdFromVersion?: number;
     readonly createdAt: string;
     readonly publishedAt?: string;
     readonly archivedAt?: string;
@@ -22,6 +24,14 @@ interface FormVersionState {
     readonly nextVersion: number;
     readonly revision: number;
 }
+interface VersionTransitionEvent {
+    readonly type: "draft.created" | "draft.deleted" | "version.published" | "version.archived";
+    readonly formId: string;
+    readonly fromRevision: number;
+    readonly toRevision: number;
+    readonly affectedVersions: readonly number[];
+    readonly occurredAt: string;
+}
 type VersionTransitionError = {
     readonly type: "draft_already_exists";
     readonly currentDraftVersion: number;
@@ -48,17 +58,22 @@ type VersionTransitionError = {
 interface CloneVersionOptions {
     readonly maxVersions?: number;
     readonly expectedRevision?: number;
+    readonly clonedAt?: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
     /** 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 currentPublishedRecord?: FormVersionRecord;
+    readonly validate?: (schema: FormSchema) => boolean | Promise<boolean> | readonly SchemaIssue[] | Promise<readonly SchemaIssue[]>;
+    readonly publishedAt?: string;
+    /** @deprecated Use publishedAt. */
     readonly timestamp?: string;
 }
 interface DeleteDraftOptions {
     readonly expectedRevision?: number;
+    readonly deletedAt?: string;
 }
 interface PublishDraftResult {
     readonly nextState: FormVersionState;
@@ -71,10 +86,22 @@ declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: Form
     readonly nextState: FormVersionState;
     readonly draftSchema: FormSchema;
 }, VersionTransitionError>;
-declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Result<PublishDraftResult, VersionTransitionError>;
+declare function createCloneTransitionPlan(state: FormVersionState, sourceRecord: FormVersionRecord, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
+declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Promise<Result<PublishDraftResult, VersionTransitionError>>;
+declare function createPublishTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: PublishDraftOptions): Promise<Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>>;
 declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
     readonly nextState: FormVersionState;
 }, VersionTransitionError>;
+declare function createDeleteDraftTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
 declare function assertVersionMutable(status: FormVersionStatus): void;
 
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
@@ -249,9 +276,34 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
-    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly filter?: SubmissionFilter | ((submission: FormSubmission) => boolean);
+    /** @deprecated Prefer the generic filter AST. */
     readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
+type SubmissionFilter = {
+    readonly op: "eq";
+    readonly path: string;
+    readonly value: JsonValue;
+} | {
+    readonly op: "in";
+    readonly path: string;
+    readonly values: readonly JsonValue[];
+} | {
+    readonly op: "range";
+    readonly path: string;
+    readonly from?: JsonValue;
+    readonly to?: JsonValue;
+} | {
+    readonly op: "exists";
+    readonly path: string;
+    readonly value: boolean;
+} | {
+    readonly op: "and";
+    readonly filters: readonly SubmissionFilter[];
+} | {
+    readonly op: "or";
+    readonly filters: readonly SubmissionFilter[];
+};
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
     readonly nextCursor?: string;
@@ -259,19 +311,57 @@ interface SubmissionPage {
 }
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
+    listTextAnswerPage?(formId: string, fieldId: string, options?: SubmissionPageQueryOptions): Promise<TextAnswerPage>;
+}
+interface TextAnswerItem {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly fieldId: string;
+    readonly text: string;
+    readonly locale?: string;
+    readonly submittedAt: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface TextAnswerPage {
+    readonly items: readonly TextAnswerItem[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
 }
 interface VersionTransitionPlan {
-    readonly state: FormVersionState;
+    readonly formId: string;
     readonly expectedRevision: number;
-    readonly draftToPublish?: FormSchema;
-    readonly versionsToArchive: readonly number[];
-    readonly versionsToDelete: readonly number[];
+    readonly nextRevision: number;
+    readonly draftToCreate?: FormVersionRecord;
+    readonly draftToDeleteVersion?: number;
+    readonly publishedRecordToSave?: FormVersionRecord;
+    readonly archivedRecordsToSave?: readonly FormVersionRecord[];
+    readonly events: readonly VersionTransitionEvent[];
+    /** The complete next state value used by persistent adapters. */
+    readonly nextVersion?: number;
+    readonly timestamp: string;
 }
+type StorageCommitError = {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision?: number;
+} | {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "invalid_transition";
+    readonly message: string;
+} | {
+    readonly type: "storage_error";
+    readonly cause: unknown;
+};
 interface VersionedFormStorageAdapter extends FormStorageAdapter {
-    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
-        readonly success: boolean;
-        readonly error?: string;
-    }>;
+    getVersionState(formId: string): Promise<FormVersionState | null>;
+    getVersionRecord(formId: string, version: number): Promise<FormVersionRecord | null>;
+    listVersionRecords(formId: string): Promise<readonly FormVersionRecord[]>;
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<Result<{
+        readonly success: true;
+    }, StorageCommitError>>;
 }
 interface BaseQuestionAggregate {
     readonly fieldId: string;
@@ -377,7 +467,7 @@ interface CsvExportOptions {
 }
 interface CsvColumnDef {
     readonly header: string;
-    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined;
+    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined | Promise<string | number | boolean | null | undefined>;
 }
 interface CsvColumnContext extends FormResponse {
     readonly submission: FormResponse;
@@ -431,9 +521,17 @@ interface SubmissionCursorValue {
     readonly submittedAt: string;
     readonly responseId: string;
 }
+interface TextAnswerCursorValue {
+    readonly responseId: string;
+    readonly fieldId: string;
+}
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
+declare function encodeTextAnswerCursor(value: TextAnswerCursorValue): string;
+declare function decodeTextAnswerCursor(cursor: string): TextAnswerCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function jsonValuesEqual(left: JsonValue | undefined, right: JsonValue | undefined): boolean;
+declare function matchesSubmissionFilter(submission: FormSubmission, filter: SubmissionFilter): boolean;
 declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
@@ -509,4 +607,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-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 };
+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 StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -6,11 +6,13 @@ type Result<T, E> = {
     readonly error: E;
 };
 type FormVersionStatus = "draft" | "published" | "archived";
-interface FormVersionRecord {
+interface FormVersionRecord extends ExtensibleNode {
     readonly formId: string;
     readonly version: number;
     readonly status: FormVersionStatus;
     readonly schema: FormSchema;
+    readonly revision: number;
+    readonly createdFromVersion?: number;
     readonly createdAt: string;
     readonly publishedAt?: string;
     readonly archivedAt?: string;
@@ -22,6 +24,14 @@ interface FormVersionState {
     readonly nextVersion: number;
     readonly revision: number;
 }
+interface VersionTransitionEvent {
+    readonly type: "draft.created" | "draft.deleted" | "version.published" | "version.archived";
+    readonly formId: string;
+    readonly fromRevision: number;
+    readonly toRevision: number;
+    readonly affectedVersions: readonly number[];
+    readonly occurredAt: string;
+}
 type VersionTransitionError = {
     readonly type: "draft_already_exists";
     readonly currentDraftVersion: number;
@@ -48,17 +58,22 @@ type VersionTransitionError = {
 interface CloneVersionOptions {
     readonly maxVersions?: number;
     readonly expectedRevision?: number;
+    readonly clonedAt?: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
     /** 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 currentPublishedRecord?: FormVersionRecord;
+    readonly validate?: (schema: FormSchema) => boolean | Promise<boolean> | readonly SchemaIssue[] | Promise<readonly SchemaIssue[]>;
+    readonly publishedAt?: string;
+    /** @deprecated Use publishedAt. */
     readonly timestamp?: string;
 }
 interface DeleteDraftOptions {
     readonly expectedRevision?: number;
+    readonly deletedAt?: string;
 }
 interface PublishDraftResult {
     readonly nextState: FormVersionState;
@@ -71,10 +86,22 @@ declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: Form
     readonly nextState: FormVersionState;
     readonly draftSchema: FormSchema;
 }, VersionTransitionError>;
-declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Result<PublishDraftResult, VersionTransitionError>;
+declare function createCloneTransitionPlan(state: FormVersionState, sourceRecord: FormVersionRecord, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
+declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Promise<Result<PublishDraftResult, VersionTransitionError>>;
+declare function createPublishTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: PublishDraftOptions): Promise<Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>>;
 declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
     readonly nextState: FormVersionState;
 }, VersionTransitionError>;
+declare function createDeleteDraftTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
 declare function assertVersionMutable(status: FormVersionStatus): void;
 
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
@@ -249,9 +276,34 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
-    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly filter?: SubmissionFilter | ((submission: FormSubmission) => boolean);
+    /** @deprecated Prefer the generic filter AST. */
     readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
+type SubmissionFilter = {
+    readonly op: "eq";
+    readonly path: string;
+    readonly value: JsonValue;
+} | {
+    readonly op: "in";
+    readonly path: string;
+    readonly values: readonly JsonValue[];
+} | {
+    readonly op: "range";
+    readonly path: string;
+    readonly from?: JsonValue;
+    readonly to?: JsonValue;
+} | {
+    readonly op: "exists";
+    readonly path: string;
+    readonly value: boolean;
+} | {
+    readonly op: "and";
+    readonly filters: readonly SubmissionFilter[];
+} | {
+    readonly op: "or";
+    readonly filters: readonly SubmissionFilter[];
+};
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
     readonly nextCursor?: string;
@@ -259,19 +311,57 @@ interface SubmissionPage {
 }
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
+    listTextAnswerPage?(formId: string, fieldId: string, options?: SubmissionPageQueryOptions): Promise<TextAnswerPage>;
+}
+interface TextAnswerItem {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly fieldId: string;
+    readonly text: string;
+    readonly locale?: string;
+    readonly submittedAt: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface TextAnswerPage {
+    readonly items: readonly TextAnswerItem[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
 }
 interface VersionTransitionPlan {
-    readonly state: FormVersionState;
+    readonly formId: string;
     readonly expectedRevision: number;
-    readonly draftToPublish?: FormSchema;
-    readonly versionsToArchive: readonly number[];
-    readonly versionsToDelete: readonly number[];
+    readonly nextRevision: number;
+    readonly draftToCreate?: FormVersionRecord;
+    readonly draftToDeleteVersion?: number;
+    readonly publishedRecordToSave?: FormVersionRecord;
+    readonly archivedRecordsToSave?: readonly FormVersionRecord[];
+    readonly events: readonly VersionTransitionEvent[];
+    /** The complete next state value used by persistent adapters. */
+    readonly nextVersion?: number;
+    readonly timestamp: string;
 }
+type StorageCommitError = {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision?: number;
+} | {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "invalid_transition";
+    readonly message: string;
+} | {
+    readonly type: "storage_error";
+    readonly cause: unknown;
+};
 interface VersionedFormStorageAdapter extends FormStorageAdapter {
-    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
-        readonly success: boolean;
-        readonly error?: string;
-    }>;
+    getVersionState(formId: string): Promise<FormVersionState | null>;
+    getVersionRecord(formId: string, version: number): Promise<FormVersionRecord | null>;
+    listVersionRecords(formId: string): Promise<readonly FormVersionRecord[]>;
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<Result<{
+        readonly success: true;
+    }, StorageCommitError>>;
 }
 interface BaseQuestionAggregate {
     readonly fieldId: string;
@@ -377,7 +467,7 @@ interface CsvExportOptions {
 }
 interface CsvColumnDef {
     readonly header: string;
-    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined;
+    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined | Promise<string | number | boolean | null | undefined>;
 }
 interface CsvColumnContext extends FormResponse {
     readonly submission: FormResponse;
@@ -431,9 +521,17 @@ interface SubmissionCursorValue {
     readonly submittedAt: string;
     readonly responseId: string;
 }
+interface TextAnswerCursorValue {
+    readonly responseId: string;
+    readonly fieldId: string;
+}
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
+declare function encodeTextAnswerCursor(value: TextAnswerCursorValue): string;
+declare function decodeTextAnswerCursor(cursor: string): TextAnswerCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function jsonValuesEqual(left: JsonValue | undefined, right: JsonValue | undefined): boolean;
+declare function matchesSubmissionFilter(submission: FormSubmission, filter: SubmissionFilter): boolean;
 declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
@@ -509,4 +607,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-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 };
+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 StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.js

@@ -1286,7 +1286,7 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
       formVersion: response.formVersion ?? schema.version,
       schema
     };
-    const customCells = customColumns.map((column) => column.getValue(context));
+    const customCells = await Promise.all(customColumns.map((column) => column.getValue(context)));
     yield `\r
 ${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
   }
@@ -1504,6 +1504,24 @@ function decodeSubmissionCursor(cursor) {
     throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
   }
 }
+function encodeTextAnswerCursor(value) {
+  if (value.responseId.length === 0 || value.fieldId.length === 0) {
+    throw new TypeError("Text answer cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeTextAnswerCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0 || !("fieldId" in parsed) || typeof parsed.fieldId !== "string" || parsed.fieldId.length === 0) {
+      throw new TypeError("text answer cursor payload is invalid.");
+    }
+    return { responseId: parsed.responseId, fieldId: parsed.fieldId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "text answer cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid text answer 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.");
@@ -1528,8 +1546,39 @@ function jsonValuesEqual(left, right) {
   const rightKeys = Object.keys(right);
   return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]));
 }
+function readSubmissionPath(submission, path) {
+  if (path.length === 0 || path.split(".").some((part) => part.length === 0 || part === "__proto__" || part === "constructor")) {
+    return void 0;
+  }
+  let current = submission;
+  for (const part of path.split(".")) {
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, part)) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function compareRangeValue(value, boundary, direction) {
+  if (typeof value === "number" && typeof boundary === "number") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  if (typeof value === "string" && typeof boundary === "string") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  return false;
+}
+function matchesSubmissionFilter(submission, filter) {
+  if (filter.op === "and") return filter.filters.every((item) => matchesSubmissionFilter(submission, item));
+  if (filter.op === "or") return filter.filters.some((item) => matchesSubmissionFilter(submission, item));
+  const value = readSubmissionPath(submission, filter.path);
+  if (filter.op === "eq") return jsonValuesEqual(value, filter.value);
+  if (filter.op === "in") return filter.values.some((candidate) => jsonValuesEqual(value, candidate));
+  if (filter.op === "exists") return filter.value ? value !== void 0 : value === void 0;
+  return (filter.from === void 0 || compareRangeValue(value, filter.from, "from")) && (filter.to === void 0 || compareRangeValue(value, filter.to, "to"));
+}
 function matchesSubmissionPageFilters(submission, options) {
-  if (options.filter !== void 0 && !options.filter(submission)) return false;
+  if (options.filter !== void 0 && !(typeof options.filter === "function" ? options.filter(submission) : matchesSubmissionFilter(submission, options.filter))) {
+    return false;
+  }
   if (options.metadataFilters === void 0) return true;
   return Object.entries(options.metadataFilters).every(
     ([key, value]) => jsonValuesEqual(submission.metadata?.[key], value)
@@ -1988,6 +2037,21 @@ function validateState(state) {
     throw new TypeError("revision must be a non-negative safe integer.");
   }
 }
+function requireTimestamp(value, name) {
+  const timestamp = value ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError(`${name} must be a valid date string.`);
+  return timestamp;
+}
+function transitionEvent(type, state, nextState, affectedVersions, occurredAt) {
+  return {
+    type,
+    formId: state.formId,
+    fromRevision: state.revision,
+    toRevision: nextState.revision,
+    affectedVersions,
+    occurredAt
+  };
+}
 function cloneVersionToDraft(state, sourceSchema, options = {}) {
   validateState(state);
   if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
@@ -2031,31 +2095,77 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
     }
   };
 }
-function publishDraft(state, draftSchema, options = {}) {
+function createCloneTransitionPlan(state, sourceRecord, options = {}) {
+  if (sourceRecord.formId !== state.formId || sourceRecord.schema.id !== sourceRecord.formId || sourceRecord.schema.version !== sourceRecord.version || sourceRecord.status !== "published" && !options.allowedSourceVersions?.includes(sourceRecord.version)) {
+    return {
+      success: false,
+      error: {
+        type: "invalid_source_version",
+        requestedVersion: sourceRecord.version,
+        ...state.publishedVersion === void 0 ? {} : { publishedVersion: state.publishedVersion }
+      }
+    };
+  }
+  const result = cloneVersionToDraft(state, sourceRecord.schema, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.clonedAt, "clonedAt");
+  const draftRecord = {
+    formId: state.formId,
+    version: result.value.draftSchema.version,
+    status: "draft",
+    schema: result.value.draftSchema,
+    revision: 1,
+    createdFromVersion: sourceRecord.version,
+    createdAt: timestamp,
+    ...options.metadata === void 0 ? {} : { metadata: options.metadata }
+  };
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToCreate: draftRecord,
+        events: [transitionEvent("draft.created", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
+function validatePublishedRecord(state, record) {
+  if (record === void 0) return;
+  if (record.formId !== state.formId || record.version !== state.publishedVersion || record.status !== "published" || record.schema.id !== record.formId || record.schema.version !== record.version) {
+    throw new TypeError("currentPublishedRecord must match the state's published version.");
+  }
+}
+function transitionTimestamp(options) {
+  return requireTimestamp(options.publishedAt ?? options.timestamp, "publishedAt");
+}
+async function publishDraft(state, draftSchema, options = {}) {
   validateState(state);
   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);
+  validatePublishedRecord(state, options.currentPublishedRecord);
+  const validation = await options.validate?.(draftSchema);
   if (validation === false || Array.isArray(validation) && validation.length > 0) {
     return {
       success: false,
       error: { type: "validation_failed", issues: Array.isArray(validation) ? validation : [] }
     };
   }
-  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 timestamp = transitionTimestamp(options);
   const archivedVersion = state.publishedVersion;
-  const archivedRecords = archivedVersion === void 0 ? [] : [
+  const archivedRecords = options.currentPublishedRecord === void 0 ? [] : [
     {
-      formId: state.formId,
-      version: archivedVersion,
+      ...options.currentPublishedRecord,
       status: "archived",
-      schema: { ...draftSchema, version: archivedVersion },
-      createdAt: timestamp,
-      publishedAt: timestamp,
+      revision: options.currentPublishedRecord.revision + 1,
       archivedAt: timestamp
     }
   ];
@@ -2073,6 +2183,8 @@ function publishDraft(state, draftSchema, options = {}) {
         version: draftSchema.version,
         status: "published",
         schema: draftSchema,
+        revision: 1,
+        ...archivedVersion === void 0 ? {} : { createdFromVersion: archivedVersion },
         createdAt: timestamp,
         publishedAt: timestamp
       },
@@ -2081,6 +2193,56 @@ function publishDraft(state, draftSchema, options = {}) {
     }
   };
 }
+async function createPublishTransitionPlan(state, draftRecord, options = {}) {
+  if (draftRecord.formId !== state.formId || draftRecord.version !== state.draftVersion || draftRecord.schema.id !== draftRecord.formId || draftRecord.schema.version !== draftRecord.version) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  if (draftRecord.status !== "draft") {
+    return { success: false, error: { type: "version_immutable", status: draftRecord.status } };
+  }
+  const expectedRevision = options.expectedRevision ?? state.revision;
+  const timestamp = transitionTimestamp(options);
+  const result = await publishDraft(state, draftRecord.schema, {
+    ...options,
+    expectedRevision,
+    publishedAt: timestamp
+  });
+  if (!result.success) return result;
+  const publishedRecordToSave = {
+    ...draftRecord,
+    status: "published",
+    revision: draftRecord.revision + 1,
+    publishedAt: timestamp
+  };
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision,
+        nextRevision: result.value.nextState.revision,
+        draftToDeleteVersion: draftRecord.version,
+        publishedRecordToSave,
+        archivedRecordsToSave: result.value.archivedRecords,
+        events: [
+          ...result.value.archivedRecords.length === 0 ? [] : [
+            transitionEvent(
+              "version.archived",
+              state,
+              result.value.nextState,
+              result.value.archivedRecords.map((record) => record.version),
+              timestamp
+            )
+          ],
+          transitionEvent("version.published", state, result.value.nextState, [draftRecord.version], timestamp)
+        ],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function deleteDraft(state, options = {}) {
   validateState(state);
   const conflict = revisionConflict(state, options.expectedRevision);
@@ -2092,6 +2254,29 @@ function deleteDraft(state, options = {}) {
     value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
   };
 }
+function createDeleteDraftTransitionPlan(state, draftRecord, options = {}) {
+  if (draftRecord.formId !== state.formId || draftRecord.version !== state.draftVersion || draftRecord.status !== "draft" || draftRecord.schema.id !== state.formId || draftRecord.schema.version !== draftRecord.version) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  const result = deleteDraft(state, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.deletedAt, "deletedAt");
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToDeleteVersion: draftRecord.version,
+        events: [transitionEvent("draft.deleted", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function assertVersionMutable(status) {
   if (status !== "draft") {
     const error = { type: "version_immutable", status };
@@ -2109,17 +2294,24 @@ export {
   calculatePageVisibility,
   cloneVersionToDraft,
   collectSchemaLocales,
+  createCloneTransitionPlan,
+  createDeleteDraftTransitionPlan,
+  createPublishTransitionPlan,
   createResponseAccumulator,
   createSubmission,
   decodeSubmissionCursor,
+  decodeTextAnswerCursor,
   deleteDraft,
   dispatchWebhook,
   encodeSubmissionCursor,
+  encodeTextAnswerCursor,
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  jsonValuesEqual,
+  matchesSubmissionFilter,
   matchesSubmissionPageFilters,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,

package/package.json

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