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

package/README.md

@@ -30,3 +30,8 @@ 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.
+
+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
+`revision_conflict` to losing concurrent publishers; on a real MongoDB client, the state and record changes are committed
+in one transaction.

package/dist/index.cjs

@@ -42,6 +42,33 @@ function parseSubmission(value, location) {
 function schemaDocumentId(formId, formVersion) {
   return `schema:${encodeURIComponent(formId)}:${formVersion}`;
 }
+function versionDocumentId(formId, formVersion) {
+  return `version:${encodeURIComponent(formId)}:${formVersion}`;
+}
+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.");
+  }
+  (0, import_core.assertValidFormSchema)(record.schema);
+}
+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 (plan.draftToCreate !== void 0) assertVersionRecord(plan.draftToCreate, plan.formId, "draft");
+  if (plan.publishedRecordToSave !== void 0) {
+    assertVersionRecord(plan.publishedRecordToSave, plan.formId, "published");
+  }
+  for (const record of plan.archivedRecordsToSave ?? []) assertVersionRecord(record, plan.formId, "archived");
+  if (plan.draftToDeleteVersion !== void 0 && (!Number.isSafeInteger(plan.draftToDeleteVersion) || plan.draftToDeleteVersion < 1)) {
+    throw new TypeError("draftToDeleteVersion must be a positive safe integer.");
+  }
+}
+function isCasConflict(error) {
+  if (!isRecord(error)) return false;
+  if (error.code === 11e3 || error.code === 112 || error.code === 251) return true;
+  return typeof error.hasErrorLabel === "function" && error.hasErrorLabel("TransientTransactionError") === true;
+}
 function parseSchemaDocument(document) {
   try {
     (0, import_core.assertValidFormSchema)(document.schema);
@@ -73,8 +100,58 @@ function createMongoDbStorage(options) {
     "form_responses",
     "responsesCollectionName"
   );
+  const versionsCollectionName = collectionName(
+    options.versionsCollectionName,
+    "form_versions",
+    "versionsCollectionName"
+  );
+  const versionStatesCollectionName = collectionName(
+    options.versionStatesCollectionName,
+    "form_version_states",
+    "versionStatesCollectionName"
+  );
   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 upsertVersionRecord = async (record, session) => {
+    const stored = cloneJson(record);
+    await versions.updateOne(
+      { _id: versionDocumentId(record.formId, record.version) },
+      { $set: { formId: record.formId, version: record.version, status: record.status, record: stored } },
+      { upsert: true, ...session === void 0 ? {} : { session } }
+    );
+  };
+  const applyVersionTransition = async (plan, session) => {
+    const stateSet = { revision: plan.nextRevision, 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 = {
+      $set: stateSet,
+      ...plan.draftToDeleteVersion === void 0 ? {} : { $unset: { draftVersion: "" } }
+    };
+    const stateResult = await versionStates.updateOne(
+      { _id: plan.formId, revision: plan.expectedRevision },
+      stateUpdate,
+      {
+        upsert: plan.expectedRevision === 0,
+        ...session === void 0 ? {} : { session }
+      }
+    );
+    if (stateResult.matchedCount === 0 && stateResult.upsertedCount === 0) {
+      return { success: false, error: "revision_conflict" };
+    }
+    if (plan.draftToDeleteVersion !== void 0) {
+      await versions.deleteOne(
+        { _id: versionDocumentId(plan.formId, plan.draftToDeleteVersion) },
+        session === void 0 ? {} : { session }
+      );
+    }
+    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 };
+  };
   return {
     async saveSchema(schema) {
       (0, import_core.assertValidFormSchema)(schema);
@@ -157,12 +234,51 @@ function createMongoDbStorage(options) {
       await submissions.deleteMany({ formId });
     },
     async clear() {
-      await Promise.all([schemas.deleteMany({}), submissions.deleteMany({})]);
+      await Promise.all([
+        schemas.deleteMany({}),
+        submissions.deleteMany({}),
+        versions.deleteMany({}),
+        versionStates.deleteMany({})
+      ]);
+    },
+    async commitVersionTransition(plan) {
+      assertTransitionPlan(plan);
+      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;
+        }
+      }
+      const session = client.startSession();
+      try {
+        let result = {
+          success: false,
+          error: "revision_conflict"
+        };
+        await session.withTransaction(async () => {
+          result = await applyVersionTransition(plan, session);
+        });
+        return result;
+      } catch (error) {
+        if (isCasConflict(error)) return { success: false, error: "revision_conflict" };
+        throw error;
+      } finally {
+        await session.endSession();
+      }
     },
     async createIndexes() {
-      await submissions.createIndexes([
-        { key: { formId: 1, submittedAt: 1, _id: 1 }, name: "form_responses_form_submitted_at_id" },
-        { key: { "submission.locale": 1 }, name: "form_responses_locale" }
+      await Promise.all([
+        submissions.createIndexes([
+          { key: { formId: 1, submittedAt: 1, _id: 1 }, name: "form_responses_form_submitted_at_id" },
+          { 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" }
+        ])
       ]);
     }
   };

package/dist/index.d.cts

@@ -1,12 +1,14 @@
-import { PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
+import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter } from '@form-engine-ts/core';
 import { Db } from 'mongodb';
 
 interface MongoDbStorageOptions {
     readonly db: Db;
     readonly schemasCollectionName?: string;
     readonly responsesCollectionName?: string;
+    readonly versionsCollectionName?: string;
+    readonly versionStatesCollectionName?: string;
 }
-interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter {
+interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, VersionedFormStorageAdapter {
     createIndexes(): Promise<void>;
 }
 declare function createMongoDbStorage(options: MongoDbStorageOptions): MongoDbStorageAdapter;

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-import { PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
+import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter } from '@form-engine-ts/core';
 import { Db } from 'mongodb';
 
 interface MongoDbStorageOptions {
     readonly db: Db;
     readonly schemasCollectionName?: string;
     readonly responsesCollectionName?: string;
+    readonly versionsCollectionName?: string;
+    readonly versionStatesCollectionName?: string;
 }
-interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter {
+interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, VersionedFormStorageAdapter {
     createIndexes(): Promise<void>;
 }
 declare function createMongoDbStorage(options: MongoDbStorageOptions): MongoDbStorageAdapter;

package/dist/index.js

@@ -24,6 +24,33 @@ function parseSubmission(value, location) {
 function schemaDocumentId(formId, formVersion) {
   return `schema:${encodeURIComponent(formId)}:${formVersion}`;
 }
+function versionDocumentId(formId, formVersion) {
+  return `version:${encodeURIComponent(formId)}:${formVersion}`;
+}
+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.");
+  }
+  assertValidFormSchema(record.schema);
+}
+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 (plan.draftToCreate !== void 0) assertVersionRecord(plan.draftToCreate, plan.formId, "draft");
+  if (plan.publishedRecordToSave !== void 0) {
+    assertVersionRecord(plan.publishedRecordToSave, plan.formId, "published");
+  }
+  for (const record of plan.archivedRecordsToSave ?? []) assertVersionRecord(record, plan.formId, "archived");
+  if (plan.draftToDeleteVersion !== void 0 && (!Number.isSafeInteger(plan.draftToDeleteVersion) || plan.draftToDeleteVersion < 1)) {
+    throw new TypeError("draftToDeleteVersion must be a positive safe integer.");
+  }
+}
+function isCasConflict(error) {
+  if (!isRecord(error)) return false;
+  if (error.code === 11e3 || error.code === 112 || error.code === 251) return true;
+  return typeof error.hasErrorLabel === "function" && error.hasErrorLabel("TransientTransactionError") === true;
+}
 function parseSchemaDocument(document) {
   try {
     assertValidFormSchema(document.schema);
@@ -55,8 +82,58 @@ function createMongoDbStorage(options) {
     "form_responses",
     "responsesCollectionName"
   );
+  const versionsCollectionName = collectionName(
+    options.versionsCollectionName,
+    "form_versions",
+    "versionsCollectionName"
+  );
+  const versionStatesCollectionName = collectionName(
+    options.versionStatesCollectionName,
+    "form_version_states",
+    "versionStatesCollectionName"
+  );
   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 upsertVersionRecord = async (record, session) => {
+    const stored = cloneJson(record);
+    await versions.updateOne(
+      { _id: versionDocumentId(record.formId, record.version) },
+      { $set: { formId: record.formId, version: record.version, status: record.status, record: stored } },
+      { upsert: true, ...session === void 0 ? {} : { session } }
+    );
+  };
+  const applyVersionTransition = async (plan, session) => {
+    const stateSet = { revision: plan.nextRevision, 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 = {
+      $set: stateSet,
+      ...plan.draftToDeleteVersion === void 0 ? {} : { $unset: { draftVersion: "" } }
+    };
+    const stateResult = await versionStates.updateOne(
+      { _id: plan.formId, revision: plan.expectedRevision },
+      stateUpdate,
+      {
+        upsert: plan.expectedRevision === 0,
+        ...session === void 0 ? {} : { session }
+      }
+    );
+    if (stateResult.matchedCount === 0 && stateResult.upsertedCount === 0) {
+      return { success: false, error: "revision_conflict" };
+    }
+    if (plan.draftToDeleteVersion !== void 0) {
+      await versions.deleteOne(
+        { _id: versionDocumentId(plan.formId, plan.draftToDeleteVersion) },
+        session === void 0 ? {} : { session }
+      );
+    }
+    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 };
+  };
   return {
     async saveSchema(schema) {
       assertValidFormSchema(schema);
@@ -139,12 +216,51 @@ function createMongoDbStorage(options) {
       await submissions.deleteMany({ formId });
     },
     async clear() {
-      await Promise.all([schemas.deleteMany({}), submissions.deleteMany({})]);
+      await Promise.all([
+        schemas.deleteMany({}),
+        submissions.deleteMany({}),
+        versions.deleteMany({}),
+        versionStates.deleteMany({})
+      ]);
+    },
+    async commitVersionTransition(plan) {
+      assertTransitionPlan(plan);
+      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;
+        }
+      }
+      const session = client.startSession();
+      try {
+        let result = {
+          success: false,
+          error: "revision_conflict"
+        };
+        await session.withTransaction(async () => {
+          result = await applyVersionTransition(plan, session);
+        });
+        return result;
+      } catch (error) {
+        if (isCasConflict(error)) return { success: false, error: "revision_conflict" };
+        throw error;
+      } finally {
+        await session.endSession();
+      }
     },
     async createIndexes() {
-      await submissions.createIndexes([
-        { key: { formId: 1, submittedAt: 1, _id: 1 }, name: "form_responses_form_submitted_at_id" },
-        { key: { "submission.locale": 1 }, name: "form_responses_locale" }
+      await Promise.all([
+        submissions.createIndexes([
+          { key: { formId: 1, submittedAt: 1, _id: 1 }, name: "form_responses_form_submitted_at_id" },
+          { 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" }
+        ])
       ]);
     }
   };

package/package.json

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