@form-engine-ts/storage-mongodb 2.7.0 → 2.9.0

package/README.md

@@ -33,8 +33,12 @@ Metadata filters and the generic submission-filter AST are translated to MongoDB
 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. 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.
+Version commits require transaction support and return `transaction_unsupported` before any write when it is unavailable.
+MongoDB duplicate-key failures are mapped to `draft_already_exists` or `revision_conflict` rather than a generic storage
+error.

package/dist/index.cjs

@@ -102,11 +102,29 @@ function parseVersionRecordDocument(document) {
   }
   return cloneJson(document.record);
 }
-function isCasConflict(error) {
+function mongoErrorMessage(error) {
+  return error instanceof Error ? error.message : isRecord(error) ? String(error.message ?? "") : "";
+}
+function isDuplicateKeyError(error) {
+  return isRecord(error) && error.code === 11e3;
+}
+function duplicateIndexName(error) {
+  if (!isDuplicateKeyError(error)) return void 0;
+  return /unique_(?:draft|published|version)_per_form/u.exec(mongoErrorMessage(error))?.[0];
+}
+function isRevisionConflict(error) {
   if (!isRecord(error)) return false;
-  if (error.code === 11e3 || error.code === 112 || error.code === 251) return true;
+  if (error.code === 11e3) return duplicateIndexName(error) !== "unique_draft_per_form";
+  if (error.code === 112 || error.code === 251) return true;
   return typeof error.hasErrorLabel === "function" && error.hasErrorLabel("TransientTransactionError") === true;
 }
+function isTransactionUnsupported(error) {
+  if (!isRecord(error)) return false;
+  if (error.code === 20 || error.code === 263 || error.code === 303) return true;
+  return /transaction numbers are only allowed|transactions? (?:are|is) not supported|replica set member|mongos/iu.test(
+    mongoErrorMessage(error)
+  );
+}
 function parseSchemaDocument(document) {
   try {
     (0, import_core.assertValidFormSchema)(document.schema);
@@ -165,6 +183,18 @@ function createMongoDbStorage(options) {
       }
     };
   };
+  const storageDraftAlreadyExists = async (plan) => {
+    const state = await versionStates.findOne({ _id: plan.formId });
+    const record = await versions.findOne({ formId: plan.formId, status: "draft" });
+    const currentDraftVersion = record?.version ?? state?.draftVersion ?? plan.draftToCreate?.version;
+    return currentDraftVersion === void 0 ? storageRevisionConflict(plan) : { success: false, error: { type: "draft_already_exists", currentDraftVersion } };
+  };
+  const mapCommitError = async (error, plan) => {
+    if (isTransactionUnsupported(error)) return { success: false, error: { type: "transaction_unsupported" } };
+    if (duplicateIndexName(error) === "unique_draft_per_form") return storageDraftAlreadyExists(plan);
+    if (isRevisionConflict(error)) return storageRevisionConflict(plan);
+    return { success: false, error: { type: "storage_error", cause: error } };
+  };
   const upsertVersionRecord = async (record, session) => {
     const stored = cloneJson(record);
     await versions.updateOne(
@@ -217,8 +247,8 @@ 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);
+    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) },
@@ -311,12 +341,16 @@ function createMongoDbStorage(options) {
         ...hasMore && last !== void 0 ? { nextCursor: (0, import_core.encodeSubmissionCursor)({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
       };
     },
-    async listTextAnswerPage(formId, fieldId, options2 = {}) {
-      if (fieldId.trim().length === 0) throw new TypeError("fieldId must not be empty.");
+    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 && cursor.fieldId !== fieldId) {
-        throw new TypeError("Text answer cursor fieldId does not match the query.");
+      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 },
@@ -327,8 +361,8 @@ function createMongoDbStorage(options) {
         ...options2.version === void 0 ? {} : { formVersion: options2.version },
         ...options2.locale === void 0 ? {} : { "submission.locale": options2.locale },
         ...submittedAt === void 0 ? {} : { submittedAt },
-        ...cursor === void 0 ? {} : { _id: { $gt: cursor.responseId } },
-        [`submission.values.${fieldId}`]: { $type: "string" }
+        ...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") {
@@ -339,22 +373,27 @@ function createMongoDbStorage(options) {
       }
       const filter = serverFilters.length === 1 ? baseFilter : { $and: serverFilters };
       const sorted = submissions.find(filter).sort({ _id: 1 });
-      const documents = typeof options2.filter === "function" ? await sorted.toArray() : await sorted.limit(pageSize + 1).toArray();
+      const documents = await sorted.toArray();
       const candidates = documents.map(parseSubmissionDocument).filter((submission) => (0, import_core.matchesSubmissionPageFilters)(submission, options2)).flatMap((submission) => {
-        const text = submission.values[fieldId];
-        if (typeof text !== "string") 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 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);
@@ -362,7 +401,7 @@ function createMongoDbStorage(options) {
       return {
         items,
         hasMore,
-        ...hasMore && last !== void 0 ? { nextCursor: (0, import_core.encodeTextAnswerCursor)({ responseId: last.responseId, fieldId }) } : {}
+        ...hasMore && last !== void 0 ? { nextCursor: (0, import_core.encodeTextAnswerCursor)({ responseId: last.responseId, fieldId: last.fieldId }) } : {}
       };
     },
     async deleteSubmission(submissionId) {
@@ -413,16 +452,18 @@ function createMongoDbStorage(options) {
       }
       const client = options.db.client;
       if (client === void 0 || typeof client.startSession !== "function") {
-        try {
-          return await applyVersionTransition(plan);
-        } catch (error) {
-          if (isCasConflict(error)) {
-            return storageRevisionConflict(plan);
-          }
-          return { success: false, error: { type: "storage_error", cause: error } };
-        }
+        return { success: false, error: { type: "transaction_unsupported" } };
+      }
+      let session;
+      try {
+        session = client.startSession();
+      } catch (error) {
+        return isTransactionUnsupported(error) ? { success: false, error: { type: "transaction_unsupported" } } : { success: false, error: { type: "storage_error", cause: error } };
+      }
+      if (typeof session.withTransaction !== "function") {
+        await session.endSession();
+        return { success: false, error: { type: "transaction_unsupported" } };
       }
-      const session = client.startSession();
       try {
         let result = {
           success: false,
@@ -433,10 +474,7 @@ function createMongoDbStorage(options) {
         });
         return result;
       } catch (error) {
-        if (isCasConflict(error)) {
-          return storageRevisionConflict(plan);
-        }
-        return { success: false, error: { type: "storage_error", cause: error } };
+        return mapCommitError(error, plan);
       } finally {
         await session.endSession();
       }
@@ -448,8 +486,19 @@ 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" }

package/dist/index.js

@@ -85,11 +85,29 @@ function parseVersionRecordDocument(document) {
   }
   return cloneJson(document.record);
 }
-function isCasConflict(error) {
+function mongoErrorMessage(error) {
+  return error instanceof Error ? error.message : isRecord(error) ? String(error.message ?? "") : "";
+}
+function isDuplicateKeyError(error) {
+  return isRecord(error) && error.code === 11e3;
+}
+function duplicateIndexName(error) {
+  if (!isDuplicateKeyError(error)) return void 0;
+  return /unique_(?:draft|published|version)_per_form/u.exec(mongoErrorMessage(error))?.[0];
+}
+function isRevisionConflict(error) {
   if (!isRecord(error)) return false;
-  if (error.code === 11e3 || error.code === 112 || error.code === 251) return true;
+  if (error.code === 11e3) return duplicateIndexName(error) !== "unique_draft_per_form";
+  if (error.code === 112 || error.code === 251) return true;
   return typeof error.hasErrorLabel === "function" && error.hasErrorLabel("TransientTransactionError") === true;
 }
+function isTransactionUnsupported(error) {
+  if (!isRecord(error)) return false;
+  if (error.code === 20 || error.code === 263 || error.code === 303) return true;
+  return /transaction numbers are only allowed|transactions? (?:are|is) not supported|replica set member|mongos/iu.test(
+    mongoErrorMessage(error)
+  );
+}
 function parseSchemaDocument(document) {
   try {
     assertValidFormSchema(document.schema);
@@ -148,6 +166,18 @@ function createMongoDbStorage(options) {
       }
     };
   };
+  const storageDraftAlreadyExists = async (plan) => {
+    const state = await versionStates.findOne({ _id: plan.formId });
+    const record = await versions.findOne({ formId: plan.formId, status: "draft" });
+    const currentDraftVersion = record?.version ?? state?.draftVersion ?? plan.draftToCreate?.version;
+    return currentDraftVersion === void 0 ? storageRevisionConflict(plan) : { success: false, error: { type: "draft_already_exists", currentDraftVersion } };
+  };
+  const mapCommitError = async (error, plan) => {
+    if (isTransactionUnsupported(error)) return { success: false, error: { type: "transaction_unsupported" } };
+    if (duplicateIndexName(error) === "unique_draft_per_form") return storageDraftAlreadyExists(plan);
+    if (isRevisionConflict(error)) return storageRevisionConflict(plan);
+    return { success: false, error: { type: "storage_error", cause: error } };
+  };
   const upsertVersionRecord = async (record, session) => {
     const stored = cloneJson(record);
     await versions.updateOne(
@@ -200,8 +230,8 @@ 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);
+    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) },
@@ -294,12 +324,16 @@ function createMongoDbStorage(options) {
         ...hasMore && last !== void 0 ? { nextCursor: encodeSubmissionCursor({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
       };
     },
-    async listTextAnswerPage(formId, fieldId, options2 = {}) {
-      if (fieldId.trim().length === 0) throw new TypeError("fieldId must not be empty.");
+    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 && cursor.fieldId !== fieldId) {
-        throw new TypeError("Text answer cursor fieldId does not match the query.");
+      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 },
@@ -310,8 +344,8 @@ function createMongoDbStorage(options) {
         ...options2.version === void 0 ? {} : { formVersion: options2.version },
         ...options2.locale === void 0 ? {} : { "submission.locale": options2.locale },
         ...submittedAt === void 0 ? {} : { submittedAt },
-        ...cursor === void 0 ? {} : { _id: { $gt: cursor.responseId } },
-        [`submission.values.${fieldId}`]: { $type: "string" }
+        ...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") {
@@ -322,22 +356,27 @@ function createMongoDbStorage(options) {
       }
       const filter = serverFilters.length === 1 ? baseFilter : { $and: serverFilters };
       const sorted = submissions.find(filter).sort({ _id: 1 });
-      const documents = typeof options2.filter === "function" ? await sorted.toArray() : await sorted.limit(pageSize + 1).toArray();
+      const documents = await sorted.toArray();
       const candidates = documents.map(parseSubmissionDocument).filter((submission) => matchesSubmissionPageFilters(submission, options2)).flatMap((submission) => {
-        const text = submission.values[fieldId];
-        if (typeof text !== "string") 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 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);
@@ -345,7 +384,7 @@ function createMongoDbStorage(options) {
       return {
         items,
         hasMore,
-        ...hasMore && last !== void 0 ? { nextCursor: encodeTextAnswerCursor({ responseId: last.responseId, fieldId }) } : {}
+        ...hasMore && last !== void 0 ? { nextCursor: encodeTextAnswerCursor({ responseId: last.responseId, fieldId: last.fieldId }) } : {}
       };
     },
     async deleteSubmission(submissionId) {
@@ -396,16 +435,18 @@ function createMongoDbStorage(options) {
       }
       const client = options.db.client;
       if (client === void 0 || typeof client.startSession !== "function") {
-        try {
-          return await applyVersionTransition(plan);
-        } catch (error) {
-          if (isCasConflict(error)) {
-            return storageRevisionConflict(plan);
-          }
-          return { success: false, error: { type: "storage_error", cause: error } };
-        }
+        return { success: false, error: { type: "transaction_unsupported" } };
+      }
+      let session;
+      try {
+        session = client.startSession();
+      } catch (error) {
+        return isTransactionUnsupported(error) ? { success: false, error: { type: "transaction_unsupported" } } : { success: false, error: { type: "storage_error", cause: error } };
+      }
+      if (typeof session.withTransaction !== "function") {
+        await session.endSession();
+        return { success: false, error: { type: "transaction_unsupported" } };
       }
-      const session = client.startSession();
       try {
         let result = {
           success: false,
@@ -416,10 +457,7 @@ function createMongoDbStorage(options) {
         });
         return result;
       } catch (error) {
-        if (isCasConflict(error)) {
-          return storageRevisionConflict(plan);
-        }
-        return { success: false, error: { type: "storage_error", cause: error } };
+        return mapCommitError(error, plan);
       } finally {
         await session.endSession();
       }
@@ -431,8 +469,19 @@ 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" }

package/package.json

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