@form-engine-ts/storage-mongodb 2.6.0 → 2.8.0

package/README.md

@@ -29,9 +29,13 @@ The caller owns the MongoDB connection lifecycle. Collection names can be custom
 
 `listSubmissionPage(formId, { version, pageSize, cursor, since, until, locale })` performs bounded reads using the
 compound `submittedAt`/response-ID cursor. Run `createIndexes()` after upgrading to create the matching compound index.
-`metadataFilters` and custom `filter` predicates are applied before page sizing.
+Metadata filters and the generic submission-filter AST are translated to MongoDB query operators before page sizing.
+Legacy predicate filters remain supported and are applied client-side. `listTextAnswerPage` returns stable cursor pages
+of individual text/textarea answers without loading every answer body at once.
 
-Version records are stored in `form_versions`, with unique `(formId, version)` and `(formId, status)` indexes. Transition
-state lives in `form_version_states`. `commitVersionTransition(plan)` compares `expectedRevision` atomically and returns
+Version records are stored in `form_versions`, with a unique `(formId, version)` index. Partial unique indexes allow at
+most one Draft and one Published record per form, while any number of Archived records remain available. Transition state
+lives in `form_version_states`. `commitVersionTransition(plan)` compares `expectedRevision` atomically and returns
 `revision_conflict` to losing concurrent publishers; on a real MongoDB client, the state and record changes are committed
-in one transaction.
+in one transaction. Clone, publish, and draft-delete plans persist complete version state, affected records, and audit
+events. State/record/list reads and typed commit errors are exposed through the full `VersionedFormStorageAdapter` API.

package/dist/index.cjs

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createMongoDbStorage: () => createMongoDbStorage
+  createMongoDbStorage: () => createMongoDbStorage,
+  submissionFilterToMongo: () => submissionFilterToMongo
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@form-engine-ts/core");
@@ -45,6 +46,35 @@ function schemaDocumentId(formId, formVersion) {
 function versionDocumentId(formId, formVersion) {
   return `version:${encodeURIComponent(formId)}:${formVersion}`;
 }
+function versionEventDocumentId(formId, fromRevision, eventIndex) {
+  return `event:${encodeURIComponent(formId)}:${fromRevision}:${eventIndex}`;
+}
+function mongoSubmissionPath(path) {
+  if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(path) || path.split(".").some((part) => part.startsWith("$"))) {
+    throw new TypeError(`Invalid submission filter path: ${path}`);
+  }
+  const [root, ...rest] = path.split(".");
+  const suffix = rest.length === 0 ? "" : `.${rest.join(".")}`;
+  if (root === "id" || root === "responseId") return `_id${suffix}`;
+  if (root === "formId" || root === "formVersion" || root === "submittedAt") return `${root}${suffix}`;
+  if (root === "locale") return `submission.locale${suffix}`;
+  return `submission.${path}`;
+}
+function submissionFilterToMongo(filter) {
+  if (filter.op === "and" || filter.op === "or") {
+    return { [filter.op === "and" ? "$and" : "$or"]: filter.filters.map(submissionFilterToMongo) };
+  }
+  const path = mongoSubmissionPath(filter.path);
+  if (filter.op === "eq") return { [path]: filter.value };
+  if (filter.op === "in") return { [path]: { $in: [...filter.values] } };
+  if (filter.op === "exists") return { [path]: { $exists: filter.value } };
+  return {
+    [path]: {
+      ...filter.from === void 0 ? {} : { $gte: filter.from },
+      ...filter.to === void 0 ? {} : { $lte: filter.to }
+    }
+  };
+}
 function assertVersionRecord(record, formId, expectedStatus) {
   if (record.formId !== formId || record.schema.id !== formId || record.schema.version !== record.version || !Number.isSafeInteger(record.version) || record.version < 1 || !Number.isSafeInteger(record.revision) || record.revision < 0 || expectedStatus !== void 0 && record.status !== expectedStatus) {
     throw new TypeError("Version transition record is inconsistent.");
@@ -55,6 +85,7 @@ function assertTransitionPlan(plan) {
   if (plan.formId.trim().length === 0 || !Number.isSafeInteger(plan.expectedRevision) || plan.expectedRevision < 0 || plan.nextRevision !== plan.expectedRevision + 1 || !Number.isFinite(Date.parse(plan.timestamp))) {
     throw new TypeError("Version transition plan is invalid.");
   }
+  if (!Array.isArray(plan.events)) throw new TypeError("Version transition plan events are required.");
   if (plan.draftToCreate !== void 0) assertVersionRecord(plan.draftToCreate, plan.formId, "draft");
   if (plan.publishedRecordToSave !== void 0) {
     assertVersionRecord(plan.publishedRecordToSave, plan.formId, "published");
@@ -64,9 +95,20 @@ function assertTransitionPlan(plan) {
     throw new TypeError("draftToDeleteVersion must be a positive safe integer.");
   }
 }
+function parseVersionRecordDocument(document) {
+  assertVersionRecord(document.record, document.formId);
+  if (document._id !== versionDocumentId(document.formId, document.version) || document.record.version !== document.version || document.record.status !== document.status) {
+    throw new Error(`MongoDB version document "${String(document._id)}" has inconsistent metadata.`);
+  }
+  return cloneJson(document.record);
+}
 function isCasConflict(error) {
   if (!isRecord(error)) return false;
-  if (error.code === 11e3 || error.code === 112 || error.code === 251) return true;
+  if (error.code === 11e3) {
+    const message = error instanceof Error ? error.message : String(error.message ?? "");
+    return !/unique_(?:draft|published|version)_per_form/u.test(message);
+  }
+  if (error.code === 112 || error.code === 251) return true;
   return typeof error.hasErrorLabel === "function" && error.hasErrorLabel("TransientTransactionError") === true;
 }
 function parseSchemaDocument(document) {
@@ -110,10 +152,23 @@ function createMongoDbStorage(options) {
     "form_version_states",
     "versionStatesCollectionName"
   );
+  const versionEventsCollectionName = "form_version_events";
   const schemas = options.db.collection(schemasCollectionName);
   const submissions = options.db.collection(responsesCollectionName);
   const versions = options.db.collection(versionsCollectionName);
   const versionStates = options.db.collection(versionStatesCollectionName);
+  const versionEvents = options.db.collection(versionEventsCollectionName);
+  const storageRevisionConflict = async (plan) => {
+    const actual = await versionStates.findOne({ _id: plan.formId });
+    return {
+      success: false,
+      error: {
+        type: "revision_conflict",
+        expectedRevision: plan.expectedRevision,
+        ...actual === null ? {} : { actualRevision: actual.revision }
+      }
+    };
+  };
   const upsertVersionRecord = async (record, session) => {
     const stored = cloneJson(record);
     await versions.updateOne(
@@ -123,7 +178,17 @@ function createMongoDbStorage(options) {
     );
   };
   const applyVersionTransition = async (plan, session) => {
-    const stateSet = { revision: plan.nextRevision, updatedAt: plan.timestamp };
+    const inferredNextVersion = Math.max(
+      1,
+      (plan.draftToCreate?.version ?? 0) + 1,
+      (plan.draftToDeleteVersion ?? 0) + 1,
+      (plan.publishedRecordToSave?.version ?? 0) + 1
+    );
+    const stateSet = {
+      revision: plan.nextRevision,
+      nextVersion: plan.nextVersion ?? inferredNextVersion,
+      updatedAt: plan.timestamp
+    };
     if (plan.draftToCreate !== void 0) stateSet.draftVersion = plan.draftToCreate.version;
     if (plan.publishedRecordToSave !== void 0) stateSet.publishedVersion = plan.publishedRecordToSave.version;
     const stateUpdate = {
@@ -139,7 +204,15 @@ function createMongoDbStorage(options) {
       }
     );
     if (stateResult.matchedCount === 0 && stateResult.upsertedCount === 0) {
-      return { success: false, error: "revision_conflict" };
+      const actual = await versionStates.findOne({ _id: plan.formId }, session === void 0 ? {} : { session });
+      return {
+        success: false,
+        error: {
+          type: "revision_conflict",
+          expectedRevision: plan.expectedRevision,
+          ...actual === null ? {} : { actualRevision: actual.revision }
+        }
+      };
     }
     if (plan.draftToDeleteVersion !== void 0) {
       await versions.deleteOne(
@@ -148,9 +221,16 @@ function createMongoDbStorage(options) {
       );
     }
     if (plan.draftToCreate !== void 0) await upsertVersionRecord(plan.draftToCreate, session);
-    if (plan.publishedRecordToSave !== void 0) await upsertVersionRecord(plan.publishedRecordToSave, session);
     for (const record of plan.archivedRecordsToSave ?? []) await upsertVersionRecord(record, session);
-    return { success: true };
+    if (plan.publishedRecordToSave !== void 0) await upsertVersionRecord(plan.publishedRecordToSave, session);
+    for (const [eventIndex, event] of plan.events.entries()) {
+      await versionEvents.updateOne(
+        { _id: versionEventDocumentId(plan.formId, plan.expectedRevision, eventIndex) },
+        { $set: { formId: plan.formId, fromRevision: plan.expectedRevision, eventIndex, event: cloneJson(event) } },
+        { upsert: true, ...session === void 0 ? {} : { session } }
+      );
+    }
+    return { success: true, value: { success: true } };
   };
   return {
     async saveSchema(schema) {
@@ -202,7 +282,7 @@ function createMongoDbStorage(options) {
         ...options2.since === void 0 ? {} : { $gte: options2.since },
         ...options2.until === void 0 ? {} : { $lte: options2.until }
       };
-      const filter = {
+      const baseFilter = {
         formId,
         ...options2.version === void 0 ? {} : { formVersion: options2.version },
         ...options2.locale === void 0 ? {} : { "submission.locale": options2.locale },
@@ -214,8 +294,16 @@ function createMongoDbStorage(options) {
           ]
         }
       };
+      const serverFilters = [baseFilter];
+      if (options2.filter !== void 0 && typeof options2.filter !== "function") {
+        serverFilters.push(submissionFilterToMongo(options2.filter));
+      }
+      for (const [key, value] of Object.entries(options2.metadataFilters ?? {})) {
+        serverFilters.push({ [`submission.metadata.${key}`]: value });
+      }
+      const filter = serverFilters.length === 1 ? baseFilter : { $and: serverFilters };
       const sorted = submissions.find(filter).sort({ submittedAt: 1, _id: 1 });
-      const requiresClientFiltering = options2.filter !== void 0 || options2.metadataFilters !== void 0;
+      const requiresClientFiltering = typeof options2.filter === "function";
       const documents = requiresClientFiltering ? await sorted.toArray() : await sorted.limit(pageSize + 1).toArray();
       const candidates = documents.map(parseSubmissionDocument).filter((item) => (0, import_core.matchesSubmissionPageFilters)(item, options2));
       const hasMore = candidates.length > pageSize;
@@ -227,6 +315,69 @@ function createMongoDbStorage(options) {
         ...hasMore && last !== void 0 ? { nextCursor: (0, import_core.encodeSubmissionCursor)({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
       };
     },
+    async listTextAnswerPage(formId, fieldIdOrOptions, providedOptions) {
+      const options2 = typeof fieldIdOrOptions === "string" ? providedOptions ?? {} : fieldIdOrOptions ?? {};
+      const requestedFieldIds = typeof fieldIdOrOptions === "string" ? [fieldIdOrOptions] : options2.fieldIds === void 0 ? void 0 : [...new Set(options2.fieldIds)];
+      if (requestedFieldIds?.some((fieldId) => fieldId.trim().length === 0)) {
+        throw new TypeError("fieldIds must not contain empty values.");
+      }
+      const pageSize = (0, import_core.normalizeSubmissionPageSize)(options2.pageSize);
+      const cursor = options2.cursor === void 0 ? void 0 : (0, import_core.decodeTextAnswerCursor)(options2.cursor);
+      if (cursor !== void 0 && requestedFieldIds !== void 0 && !requestedFieldIds.includes(cursor.fieldId)) {
+        throw new TypeError("Text answer cursor fieldId does not match the query fields.");
+      }
+      const submittedAt = options2.since === void 0 && options2.until === void 0 ? void 0 : {
+        ...options2.since === void 0 ? {} : { $gte: options2.since },
+        ...options2.until === void 0 ? {} : { $lte: options2.until }
+      };
+      const baseFilter = {
+        formId,
+        ...options2.version === void 0 ? {} : { formVersion: options2.version },
+        ...options2.locale === void 0 ? {} : { "submission.locale": options2.locale },
+        ...submittedAt === void 0 ? {} : { submittedAt },
+        ...cursor === void 0 ? {} : { _id: { $gte: cursor.responseId } },
+        ...requestedFieldIds?.length === 1 ? { [`submission.values.${requestedFieldIds[0]}`]: { $type: "string" } } : {}
+      };
+      const serverFilters = [baseFilter];
+      if (options2.filter !== void 0 && typeof options2.filter !== "function") {
+        serverFilters.push(submissionFilterToMongo(options2.filter));
+      }
+      for (const [key, value] of Object.entries(options2.metadataFilters ?? {})) {
+        serverFilters.push({ [`submission.metadata.${key}`]: value });
+      }
+      const filter = serverFilters.length === 1 ? baseFilter : { $and: serverFilters };
+      const sorted = submissions.find(filter).sort({ _id: 1 });
+      const documents = await sorted.toArray();
+      const candidates = documents.map(parseSubmissionDocument).filter((submission) => (0, import_core.matchesSubmissionPageFilters)(submission, options2)).flatMap((submission) => {
+        const entries = requestedFieldIds === void 0 ? Object.entries(submission.values) : requestedFieldIds.map((fieldId) => [fieldId, submission.values[fieldId]]);
+        return entries.flatMap(([fieldId, text]) => {
+          if (typeof text !== "string" || text.length === 0) return [];
+          if (cursor !== void 0 && (submission.id < cursor.responseId || submission.id === cursor.responseId && fieldId <= cursor.fieldId)) {
+            return [];
+          }
+          return [
+            {
+              responseId: submission.id,
+              formId: submission.formId,
+              formVersion: submission.formVersion,
+              fieldId,
+              text,
+              locale: submission.locale,
+              submittedAt: submission.submittedAt,
+              ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+            }
+          ];
+        });
+      });
+      const hasMore = candidates.length > pageSize;
+      const items = candidates.slice(0, pageSize);
+      const last = items.at(-1);
+      return {
+        items,
+        hasMore,
+        ...hasMore && last !== void 0 ? { nextCursor: (0, import_core.encodeTextAnswerCursor)({ responseId: last.responseId, fieldId: last.fieldId }) } : {}
+      };
+    },
     async deleteSubmission(submissionId) {
       await submissions.deleteOne({ _id: submissionId });
     },
@@ -238,33 +389,67 @@ function createMongoDbStorage(options) {
         schemas.deleteMany({}),
         submissions.deleteMany({}),
         versions.deleteMany({}),
-        versionStates.deleteMany({})
+        versionStates.deleteMany({}),
+        versionEvents.deleteMany({})
       ]);
     },
+    async getVersionState(formId) {
+      const document = await versionStates.findOne({ _id: formId });
+      if (document === null) return null;
+      if (!Number.isSafeInteger(document.revision) || document.revision < 0) {
+        throw new Error(`MongoDB version state "${formId}" is invalid.`);
+      }
+      const nextVersion = document.nextVersion ?? Math.max(1, (document.draftVersion ?? 0) + 1, (document.publishedVersion ?? 0) + 1);
+      return {
+        formId,
+        revision: document.revision,
+        nextVersion,
+        ...document.draftVersion === void 0 ? {} : { draftVersion: document.draftVersion },
+        ...document.publishedVersion === void 0 ? {} : { publishedVersion: document.publishedVersion }
+      };
+    },
+    async getVersionRecord(formId, version) {
+      const document = await versions.findOne({ _id: versionDocumentId(formId, version) });
+      return document === null ? null : parseVersionRecordDocument(document);
+    },
+    async listVersionRecords(formId) {
+      return (await versions.find({ formId }).sort({ version: 1 }).toArray()).map(parseVersionRecordDocument);
+    },
     async commitVersionTransition(plan) {
-      assertTransitionPlan(plan);
+      try {
+        assertTransitionPlan(plan);
+      } catch (cause) {
+        return {
+          success: false,
+          error: { type: "invalid_transition", message: cause instanceof Error ? cause.message : String(cause) }
+        };
+      }
       const client = options.db.client;
       if (client === void 0 || typeof client.startSession !== "function") {
         try {
           return await applyVersionTransition(plan);
         } catch (error) {
-          if (isCasConflict(error)) return { success: false, error: "revision_conflict" };
-          throw error;
+          if (isCasConflict(error)) {
+            return storageRevisionConflict(plan);
+          }
+          return { success: false, error: { type: "storage_error", cause: error } };
         }
       }
       const session = client.startSession();
       try {
         let result = {
           success: false,
-          error: "revision_conflict"
+          error: { type: "revision_conflict", expectedRevision: plan.expectedRevision }
         };
         await session.withTransaction(async () => {
           result = await applyVersionTransition(plan, session);
         });
         return result;
       } catch (error) {
-        if (isCasConflict(error)) return { success: false, error: "revision_conflict" };
-        throw error;
+        if (isCasConflict(error)) {
+          return storageRevisionConflict(plan);
+        }
+        return { success: false, error: { type: "storage_error", cause: error } };
       } finally {
         await session.endSession();
       }
@@ -276,8 +461,22 @@ function createMongoDbStorage(options) {
           { key: { "submission.locale": 1 }, name: "form_responses_locale" }
         ]),
         versions.createIndexes([
-          { key: { formId: 1, version: 1 }, name: "form_versions_form_version", unique: true },
-          { key: { formId: 1, status: 1 }, name: "form_versions_form_status" }
+          { key: { formId: 1, version: 1 }, name: "unique_version_per_form", unique: true },
+          {
+            key: { formId: 1 },
+            name: "unique_draft_per_form",
+            unique: true,
+            partialFilterExpression: { status: "draft" }
+          },
+          {
+            key: { formId: 1 },
+            name: "unique_published_per_form",
+            unique: true,
+            partialFilterExpression: { status: "published" }
+          }
+        ]),
+        versionEvents.createIndexes([
+          { key: { formId: 1, fromRevision: 1, eventIndex: 1 }, name: "form_version_events_revision" }
         ])
       ]);
     }
@@ -285,5 +484,6 @@ function createMongoDbStorage(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createMongoDbStorage
+  createMongoDbStorage,
+  submissionFilterToMongo
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter } from '@form-engine-ts/core';
-import { Db } from 'mongodb';
+import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
+import { Db, Document } from 'mongodb';
 
 interface MongoDbStorageOptions {
     readonly db: Db;
@@ -11,6 +11,7 @@ interface MongoDbStorageOptions {
 interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, VersionedFormStorageAdapter {
     createIndexes(): Promise<void>;
 }
+declare function submissionFilterToMongo(filter: SubmissionFilter): Document;
 declare function createMongoDbStorage(options: MongoDbStorageOptions): MongoDbStorageAdapter;
 
-export { type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage };
+export { type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage, submissionFilterToMongo };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter } from '@form-engine-ts/core';
-import { Db } from 'mongodb';
+import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
+import { Db, Document } from 'mongodb';
 
 interface MongoDbStorageOptions {
     readonly db: Db;
@@ -11,6 +11,7 @@ interface MongoDbStorageOptions {
 interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, VersionedFormStorageAdapter {
     createIndexes(): Promise<void>;
 }
+declare function submissionFilterToMongo(filter: SubmissionFilter): Document;
 declare function createMongoDbStorage(options: MongoDbStorageOptions): MongoDbStorageAdapter;
 
-export { type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage };
+export { type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage, submissionFilterToMongo };

package/dist/index.js

@@ -2,7 +2,9 @@
 import {
   assertValidFormSchema,
   decodeSubmissionCursor,
+  decodeTextAnswerCursor,
   encodeSubmissionCursor,
+  encodeTextAnswerCursor,
   matchesSubmissionPageFilters,
   normalizeSubmissionPageSize
 } from "@form-engine-ts/core";
@@ -27,6 +29,35 @@ function schemaDocumentId(formId, formVersion) {
 function versionDocumentId(formId, formVersion) {
   return `version:${encodeURIComponent(formId)}:${formVersion}`;
 }
+function versionEventDocumentId(formId, fromRevision, eventIndex) {
+  return `event:${encodeURIComponent(formId)}:${fromRevision}:${eventIndex}`;
+}
+function mongoSubmissionPath(path) {
+  if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(path) || path.split(".").some((part) => part.startsWith("$"))) {
+    throw new TypeError(`Invalid submission filter path: ${path}`);
+  }
+  const [root, ...rest] = path.split(".");
+  const suffix = rest.length === 0 ? "" : `.${rest.join(".")}`;
+  if (root === "id" || root === "responseId") return `_id${suffix}`;
+  if (root === "formId" || root === "formVersion" || root === "submittedAt") return `${root}${suffix}`;
+  if (root === "locale") return `submission.locale${suffix}`;
+  return `submission.${path}`;
+}
+function submissionFilterToMongo(filter) {
+  if (filter.op === "and" || filter.op === "or") {
+    return { [filter.op === "and" ? "$and" : "$or"]: filter.filters.map(submissionFilterToMongo) };
+  }
+  const path = mongoSubmissionPath(filter.path);
+  if (filter.op === "eq") return { [path]: filter.value };
+  if (filter.op === "in") return { [path]: { $in: [...filter.values] } };
+  if (filter.op === "exists") return { [path]: { $exists: filter.value } };
+  return {
+    [path]: {
+      ...filter.from === void 0 ? {} : { $gte: filter.from },
+      ...filter.to === void 0 ? {} : { $lte: filter.to }
+    }
+  };
+}
 function assertVersionRecord(record, formId, expectedStatus) {
   if (record.formId !== formId || record.schema.id !== formId || record.schema.version !== record.version || !Number.isSafeInteger(record.version) || record.version < 1 || !Number.isSafeInteger(record.revision) || record.revision < 0 || expectedStatus !== void 0 && record.status !== expectedStatus) {
     throw new TypeError("Version transition record is inconsistent.");
@@ -37,6 +68,7 @@ function assertTransitionPlan(plan) {
   if (plan.formId.trim().length === 0 || !Number.isSafeInteger(plan.expectedRevision) || plan.expectedRevision < 0 || plan.nextRevision !== plan.expectedRevision + 1 || !Number.isFinite(Date.parse(plan.timestamp))) {
     throw new TypeError("Version transition plan is invalid.");
   }
+  if (!Array.isArray(plan.events)) throw new TypeError("Version transition plan events are required.");
   if (plan.draftToCreate !== void 0) assertVersionRecord(plan.draftToCreate, plan.formId, "draft");
   if (plan.publishedRecordToSave !== void 0) {
     assertVersionRecord(plan.publishedRecordToSave, plan.formId, "published");
@@ -46,9 +78,20 @@ function assertTransitionPlan(plan) {
     throw new TypeError("draftToDeleteVersion must be a positive safe integer.");
   }
 }
+function parseVersionRecordDocument(document) {
+  assertVersionRecord(document.record, document.formId);
+  if (document._id !== versionDocumentId(document.formId, document.version) || document.record.version !== document.version || document.record.status !== document.status) {
+    throw new Error(`MongoDB version document "${String(document._id)}" has inconsistent metadata.`);
+  }
+  return cloneJson(document.record);
+}
 function isCasConflict(error) {
   if (!isRecord(error)) return false;
-  if (error.code === 11e3 || error.code === 112 || error.code === 251) return true;
+  if (error.code === 11e3) {
+    const message = error instanceof Error ? error.message : String(error.message ?? "");
+    return !/unique_(?:draft|published|version)_per_form/u.test(message);
+  }
+  if (error.code === 112 || error.code === 251) return true;
   return typeof error.hasErrorLabel === "function" && error.hasErrorLabel("TransientTransactionError") === true;
 }
 function parseSchemaDocument(document) {
@@ -92,10 +135,23 @@ function createMongoDbStorage(options) {
     "form_version_states",
     "versionStatesCollectionName"
   );
+  const versionEventsCollectionName = "form_version_events";
   const schemas = options.db.collection(schemasCollectionName);
   const submissions = options.db.collection(responsesCollectionName);
   const versions = options.db.collection(versionsCollectionName);
   const versionStates = options.db.collection(versionStatesCollectionName);
+  const versionEvents = options.db.collection(versionEventsCollectionName);
+  const storageRevisionConflict = async (plan) => {
+    const actual = await versionStates.findOne({ _id: plan.formId });
+    return {
+      success: false,
+      error: {
+        type: "revision_conflict",
+        expectedRevision: plan.expectedRevision,
+        ...actual === null ? {} : { actualRevision: actual.revision }
+      }
+    };
+  };
   const upsertVersionRecord = async (record, session) => {
     const stored = cloneJson(record);
     await versions.updateOne(
@@ -105,7 +161,17 @@ function createMongoDbStorage(options) {
     );
   };
   const applyVersionTransition = async (plan, session) => {
-    const stateSet = { revision: plan.nextRevision, updatedAt: plan.timestamp };
+    const inferredNextVersion = Math.max(
+      1,
+      (plan.draftToCreate?.version ?? 0) + 1,
+      (plan.draftToDeleteVersion ?? 0) + 1,
+      (plan.publishedRecordToSave?.version ?? 0) + 1
+    );
+    const stateSet = {
+      revision: plan.nextRevision,
+      nextVersion: plan.nextVersion ?? inferredNextVersion,
+      updatedAt: plan.timestamp
+    };
     if (plan.draftToCreate !== void 0) stateSet.draftVersion = plan.draftToCreate.version;
     if (plan.publishedRecordToSave !== void 0) stateSet.publishedVersion = plan.publishedRecordToSave.version;
     const stateUpdate = {
@@ -121,7 +187,15 @@ function createMongoDbStorage(options) {
       }
     );
     if (stateResult.matchedCount === 0 && stateResult.upsertedCount === 0) {
-      return { success: false, error: "revision_conflict" };
+      const actual = await versionStates.findOne({ _id: plan.formId }, session === void 0 ? {} : { session });
+      return {
+        success: false,
+        error: {
+          type: "revision_conflict",
+          expectedRevision: plan.expectedRevision,
+          ...actual === null ? {} : { actualRevision: actual.revision }
+        }
+      };
     }
     if (plan.draftToDeleteVersion !== void 0) {
       await versions.deleteOne(
@@ -130,9 +204,16 @@ function createMongoDbStorage(options) {
       );
     }
     if (plan.draftToCreate !== void 0) await upsertVersionRecord(plan.draftToCreate, session);
-    if (plan.publishedRecordToSave !== void 0) await upsertVersionRecord(plan.publishedRecordToSave, session);
     for (const record of plan.archivedRecordsToSave ?? []) await upsertVersionRecord(record, session);
-    return { success: true };
+    if (plan.publishedRecordToSave !== void 0) await upsertVersionRecord(plan.publishedRecordToSave, session);
+    for (const [eventIndex, event] of plan.events.entries()) {
+      await versionEvents.updateOne(
+        { _id: versionEventDocumentId(plan.formId, plan.expectedRevision, eventIndex) },
+        { $set: { formId: plan.formId, fromRevision: plan.expectedRevision, eventIndex, event: cloneJson(event) } },
+        { upsert: true, ...session === void 0 ? {} : { session } }
+      );
+    }
+    return { success: true, value: { success: true } };
   };
   return {
     async saveSchema(schema) {
@@ -184,7 +265,7 @@ function createMongoDbStorage(options) {
         ...options2.since === void 0 ? {} : { $gte: options2.since },
         ...options2.until === void 0 ? {} : { $lte: options2.until }
       };
-      const filter = {
+      const baseFilter = {
         formId,
         ...options2.version === void 0 ? {} : { formVersion: options2.version },
         ...options2.locale === void 0 ? {} : { "submission.locale": options2.locale },
@@ -196,8 +277,16 @@ function createMongoDbStorage(options) {
           ]
         }
       };
+      const serverFilters = [baseFilter];
+      if (options2.filter !== void 0 && typeof options2.filter !== "function") {
+        serverFilters.push(submissionFilterToMongo(options2.filter));
+      }
+      for (const [key, value] of Object.entries(options2.metadataFilters ?? {})) {
+        serverFilters.push({ [`submission.metadata.${key}`]: value });
+      }
+      const filter = serverFilters.length === 1 ? baseFilter : { $and: serverFilters };
       const sorted = submissions.find(filter).sort({ submittedAt: 1, _id: 1 });
-      const requiresClientFiltering = options2.filter !== void 0 || options2.metadataFilters !== void 0;
+      const requiresClientFiltering = typeof options2.filter === "function";
       const documents = requiresClientFiltering ? await sorted.toArray() : await sorted.limit(pageSize + 1).toArray();
       const candidates = documents.map(parseSubmissionDocument).filter((item) => matchesSubmissionPageFilters(item, options2));
       const hasMore = candidates.length > pageSize;
@@ -209,6 +298,69 @@ function createMongoDbStorage(options) {
         ...hasMore && last !== void 0 ? { nextCursor: encodeSubmissionCursor({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
       };
     },
+    async listTextAnswerPage(formId, fieldIdOrOptions, providedOptions) {
+      const options2 = typeof fieldIdOrOptions === "string" ? providedOptions ?? {} : fieldIdOrOptions ?? {};
+      const requestedFieldIds = typeof fieldIdOrOptions === "string" ? [fieldIdOrOptions] : options2.fieldIds === void 0 ? void 0 : [...new Set(options2.fieldIds)];
+      if (requestedFieldIds?.some((fieldId) => fieldId.trim().length === 0)) {
+        throw new TypeError("fieldIds must not contain empty values.");
+      }
+      const pageSize = normalizeSubmissionPageSize(options2.pageSize);
+      const cursor = options2.cursor === void 0 ? void 0 : decodeTextAnswerCursor(options2.cursor);
+      if (cursor !== void 0 && requestedFieldIds !== void 0 && !requestedFieldIds.includes(cursor.fieldId)) {
+        throw new TypeError("Text answer cursor fieldId does not match the query fields.");
+      }
+      const submittedAt = options2.since === void 0 && options2.until === void 0 ? void 0 : {
+        ...options2.since === void 0 ? {} : { $gte: options2.since },
+        ...options2.until === void 0 ? {} : { $lte: options2.until }
+      };
+      const baseFilter = {
+        formId,
+        ...options2.version === void 0 ? {} : { formVersion: options2.version },
+        ...options2.locale === void 0 ? {} : { "submission.locale": options2.locale },
+        ...submittedAt === void 0 ? {} : { submittedAt },
+        ...cursor === void 0 ? {} : { _id: { $gte: cursor.responseId } },
+        ...requestedFieldIds?.length === 1 ? { [`submission.values.${requestedFieldIds[0]}`]: { $type: "string" } } : {}
+      };
+      const serverFilters = [baseFilter];
+      if (options2.filter !== void 0 && typeof options2.filter !== "function") {
+        serverFilters.push(submissionFilterToMongo(options2.filter));
+      }
+      for (const [key, value] of Object.entries(options2.metadataFilters ?? {})) {
+        serverFilters.push({ [`submission.metadata.${key}`]: value });
+      }
+      const filter = serverFilters.length === 1 ? baseFilter : { $and: serverFilters };
+      const sorted = submissions.find(filter).sort({ _id: 1 });
+      const documents = await sorted.toArray();
+      const candidates = documents.map(parseSubmissionDocument).filter((submission) => matchesSubmissionPageFilters(submission, options2)).flatMap((submission) => {
+        const entries = requestedFieldIds === void 0 ? Object.entries(submission.values) : requestedFieldIds.map((fieldId) => [fieldId, submission.values[fieldId]]);
+        return entries.flatMap(([fieldId, text]) => {
+          if (typeof text !== "string" || text.length === 0) return [];
+          if (cursor !== void 0 && (submission.id < cursor.responseId || submission.id === cursor.responseId && fieldId <= cursor.fieldId)) {
+            return [];
+          }
+          return [
+            {
+              responseId: submission.id,
+              formId: submission.formId,
+              formVersion: submission.formVersion,
+              fieldId,
+              text,
+              locale: submission.locale,
+              submittedAt: submission.submittedAt,
+              ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+            }
+          ];
+        });
+      });
+      const hasMore = candidates.length > pageSize;
+      const items = candidates.slice(0, pageSize);
+      const last = items.at(-1);
+      return {
+        items,
+        hasMore,
+        ...hasMore && last !== void 0 ? { nextCursor: encodeTextAnswerCursor({ responseId: last.responseId, fieldId: last.fieldId }) } : {}
+      };
+    },
     async deleteSubmission(submissionId) {
       await submissions.deleteOne({ _id: submissionId });
     },
@@ -220,33 +372,67 @@ function createMongoDbStorage(options) {
         schemas.deleteMany({}),
         submissions.deleteMany({}),
         versions.deleteMany({}),
-        versionStates.deleteMany({})
+        versionStates.deleteMany({}),
+        versionEvents.deleteMany({})
       ]);
     },
+    async getVersionState(formId) {
+      const document = await versionStates.findOne({ _id: formId });
+      if (document === null) return null;
+      if (!Number.isSafeInteger(document.revision) || document.revision < 0) {
+        throw new Error(`MongoDB version state "${formId}" is invalid.`);
+      }
+      const nextVersion = document.nextVersion ?? Math.max(1, (document.draftVersion ?? 0) + 1, (document.publishedVersion ?? 0) + 1);
+      return {
+        formId,
+        revision: document.revision,
+        nextVersion,
+        ...document.draftVersion === void 0 ? {} : { draftVersion: document.draftVersion },
+        ...document.publishedVersion === void 0 ? {} : { publishedVersion: document.publishedVersion }
+      };
+    },
+    async getVersionRecord(formId, version) {
+      const document = await versions.findOne({ _id: versionDocumentId(formId, version) });
+      return document === null ? null : parseVersionRecordDocument(document);
+    },
+    async listVersionRecords(formId) {
+      return (await versions.find({ formId }).sort({ version: 1 }).toArray()).map(parseVersionRecordDocument);
+    },
     async commitVersionTransition(plan) {
-      assertTransitionPlan(plan);
+      try {
+        assertTransitionPlan(plan);
+      } catch (cause) {
+        return {
+          success: false,
+          error: { type: "invalid_transition", message: cause instanceof Error ? cause.message : String(cause) }
+        };
+      }
       const client = options.db.client;
       if (client === void 0 || typeof client.startSession !== "function") {
         try {
           return await applyVersionTransition(plan);
         } catch (error) {
-          if (isCasConflict(error)) return { success: false, error: "revision_conflict" };
-          throw error;
+          if (isCasConflict(error)) {
+            return storageRevisionConflict(plan);
+          }
+          return { success: false, error: { type: "storage_error", cause: error } };
         }
       }
       const session = client.startSession();
       try {
         let result = {
           success: false,
-          error: "revision_conflict"
+          error: { type: "revision_conflict", expectedRevision: plan.expectedRevision }
         };
         await session.withTransaction(async () => {
           result = await applyVersionTransition(plan, session);
         });
         return result;
       } catch (error) {
-        if (isCasConflict(error)) return { success: false, error: "revision_conflict" };
-        throw error;
+        if (isCasConflict(error)) {
+          return storageRevisionConflict(plan);
+        }
+        return { success: false, error: { type: "storage_error", cause: error } };
       } finally {
         await session.endSession();
       }
@@ -258,13 +444,28 @@ function createMongoDbStorage(options) {
           { key: { "submission.locale": 1 }, name: "form_responses_locale" }
         ]),
         versions.createIndexes([
-          { key: { formId: 1, version: 1 }, name: "form_versions_form_version", unique: true },
-          { key: { formId: 1, status: 1 }, name: "form_versions_form_status" }
+          { key: { formId: 1, version: 1 }, name: "unique_version_per_form", unique: true },
+          {
+            key: { formId: 1 },
+            name: "unique_draft_per_form",
+            unique: true,
+            partialFilterExpression: { status: "draft" }
+          },
+          {
+            key: { formId: 1 },
+            name: "unique_published_per_form",
+            unique: true,
+            partialFilterExpression: { status: "published" }
+          }
+        ]),
+        versionEvents.createIndexes([
+          { key: { formId: 1, fromRevision: 1, eventIndex: 1 }, name: "form_version_events_revision" }
         ])
       ]);
     }
   };
 }
 export {
-  createMongoDbStorage
+  createMongoDbStorage,
+  submissionFilterToMongo
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/storage-mongodb",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.6.0"
+    "@form-engine-ts/core": "2.8.0"
   },
   "peerDependencies": {
     "mongodb": "^6.0.0"