@form-engine-ts/core 2.5.1 → 2.6.0

package/README.md

@@ -76,17 +76,19 @@ 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.
 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.
 `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.
 

package/dist/index.cjs

@@ -30,6 +30,7 @@ __export(index_exports, {
   calculatePageVisibility: () => calculatePageVisibility,
   cloneVersionToDraft: () => cloneVersionToDraft,
   collectSchemaLocales: () => collectSchemaLocales,
+  createPublishTransitionPlan: () => createPublishTransitionPlan,
   createResponseAccumulator: () => createResponseAccumulator,
   createSubmission: () => createSubmission,
   decodeSubmissionCursor: () => decodeSubmissionCursor,
@@ -1346,7 +1347,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(",")}`;
   }
@@ -2091,31 +2092,39 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
     }
   };
 }
-function publishDraft(state, draftSchema, options = {}) {
+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) {
+  const timestamp = options.publishedAt ?? options.timestamp ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("publishedAt must be a valid date string.");
+  return timestamp;
+}
+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 +2142,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 +2152,43 @@ 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,
+        timestamp
+      }
+    }
+  };
+}
 function deleteDraft(state, options = {}) {
   validateState(state);
   const conflict = revisionConflict(state, options.expectedRevision);
@@ -2170,6 +2218,7 @@ function assertVersionMutable(status) {
   calculatePageVisibility,
   cloneVersionToDraft,
   collectSchemaLocales,
+  createPublishTransitionPlan,
   createResponseAccumulator,
   createSubmission,
   decodeSubmissionCursor,

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;
@@ -53,8 +55,10 @@ interface CloneVersionOptions {
 }
 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 {
@@ -71,7 +75,11 @@ 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 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>;
@@ -261,11 +269,14 @@ interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
 }
 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 timestamp: string;
 }
 interface VersionedFormStorageAdapter extends FormStorageAdapter {
     commitVersionTransition(plan: VersionTransitionPlan): Promise<{
@@ -377,7 +388,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;
@@ -509,4 +520,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 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, createPublishTransitionPlan, 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

@@ -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;
@@ -53,8 +55,10 @@ interface CloneVersionOptions {
 }
 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 {
@@ -71,7 +75,11 @@ 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 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>;
@@ -261,11 +269,14 @@ interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
 }
 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 timestamp: string;
 }
 interface VersionedFormStorageAdapter extends FormStorageAdapter {
     commitVersionTransition(plan: VersionTransitionPlan): Promise<{
@@ -377,7 +388,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;
@@ -509,4 +520,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 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, createPublishTransitionPlan, 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

@@ -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(",")}`;
   }
@@ -2031,31 +2031,39 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
     }
   };
 }
-function publishDraft(state, draftSchema, options = {}) {
+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) {
+  const timestamp = options.publishedAt ?? options.timestamp ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("publishedAt must be a valid date string.");
+  return timestamp;
+}
+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 +2081,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 +2091,43 @@ 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,
+        timestamp
+      }
+    }
+  };
+}
 function deleteDraft(state, options = {}) {
   validateState(state);
   const conflict = revisionConflict(state, options.expectedRevision);
@@ -2109,6 +2156,7 @@ export {
   calculatePageVisibility,
   cloneVersionToDraft,
   collectSchemaLocales,
+  createPublishTransitionPlan,
   createResponseAccumulator,
   createSubmission,
   decodeSubmissionCursor,

package/package.json

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