@form-engine-ts/storage-mongodb 4.0.0 → 4.2.0

package/README.md

@@ -25,7 +25,11 @@ const submissions = await storage.listSubmissions(schema.id, schema.version, {
 });
 ```
 
-The caller owns the MongoDB connection lifecycle. Collection names can be customized in the factory options. `createIndexes()` creates named indexes for form/timestamp range scans and locale queries. Range boundaries are inclusive, and MongoDB sorts by submission time and then ID. `clearResponses(formId)` preserves schemas and other forms; `clear()` removes documents only from the configured collections and does not drop collections or indexes.
+The caller owns the MongoDB connection lifecycle. Collection names can be customized with the legacy flat options or
+with `collectionNames`. `customIndexes` adds application-owned indexes to the configured forms, versions, or response
+collections; `createIndexes()` creates the built-in indexes first and then the custom definitions. Range boundaries are
+inclusive, and MongoDB sorts by submission time and then ID. `clearResponses(formId)` preserves schemas and other forms;
+`clear()` removes documents only from the configured collections and does not drop collections or indexes.
 
 `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.

package/dist/index.cjs

@@ -148,23 +148,56 @@ function collectionName(value, fallback, optionName) {
   if (value.trim().length === 0) throw new TypeError(`${optionName} must be a non-empty string.`);
   return value;
 }
+function normalizeIndexSpecification(spec) {
+  if (typeof spec === "string") return { [spec]: 1 };
+  if (Array.isArray(spec)) return Object.fromEntries(spec.map((field) => [field, 1]));
+  if (spec instanceof Map) return spec;
+  if (!isRecord(spec) || Object.keys(spec).length === 0) throw new TypeError("Index specification must not be empty.");
+  return spec;
+}
+function customIndexDescriptions(definitions) {
+  return (definitions ?? []).map(({ spec, options: indexOptions }) => ({
+    ...indexOptions ?? {},
+    key: normalizeIndexSpecification(spec)
+  }));
+}
+async function createConfiguredIndexes(collection, defaults, custom) {
+  const definitions = custom ?? [];
+  if (definitions.length === 0) {
+    await collection.createIndexes(defaults);
+    return;
+  }
+  if (collection.createIndex === void 0) {
+    await collection.createIndexes([...defaults, ...customIndexDescriptions(definitions)]);
+    return;
+  }
+  await collection.createIndexes(defaults);
+  for (const { spec, options: indexOptions } of definitions) {
+    await collection.createIndex(normalizeIndexSpecification(spec), indexOptions);
+  }
+}
 function createMongoDbStorage(options) {
   if (options?.db === void 0) throw new TypeError("db is required.");
-  const schemasCollectionName = collectionName(options.schemasCollectionName, "form_schemas", "schemasCollectionName");
+  const collectionNames = options.collectionNames;
+  const schemasCollectionName = collectionName(
+    collectionNames?.forms ?? options.schemasCollectionName,
+    collectionNames === void 0 ? "form_schemas" : "forms",
+    collectionNames?.forms === void 0 ? "schemasCollectionName" : "collectionNames.forms"
+  );
   const responsesCollectionName = collectionName(
-    options.responsesCollectionName,
+    collectionNames?.formResponses ?? options.responsesCollectionName,
     "form_responses",
-    "responsesCollectionName"
+    collectionNames?.formResponses === void 0 ? "responsesCollectionName" : "collectionNames.formResponses"
   );
   const versionsCollectionName = collectionName(
-    options.versionsCollectionName,
+    collectionNames?.formVersions ?? options.versionsCollectionName,
     "form_versions",
-    "versionsCollectionName"
+    collectionNames?.formVersions === void 0 ? "versionsCollectionName" : "collectionNames.formVersions"
   );
   const versionStatesCollectionName = collectionName(
-    options.versionStatesCollectionName,
+    collectionNames?.formVersionStates ?? options.versionStatesCollectionName,
     "form_version_states",
-    "versionStatesCollectionName"
+    collectionNames?.formVersionStates === void 0 ? "versionStatesCollectionName" : "collectionNames.formVersionStates"
   );
   const versionEventsCollectionName = "form_version_events";
   const schemas = options.db.collection(schemasCollectionName);
@@ -481,28 +514,37 @@ function createMongoDbStorage(options) {
     },
     async createIndexes() {
       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: "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" }
-          }
-        ]),
+        createConfiguredIndexes(
+          submissions,
+          [
+            { key: { formId: 1, submittedAt: 1, _id: 1 }, name: "form_responses_form_submitted_at_id" },
+            { key: { "submission.locale": 1 }, name: "form_responses_locale" }
+          ],
+          options.customIndexes?.formResponses
+        ),
+        createConfiguredIndexes(
+          versions,
+          [
+            { 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" }
+            }
+          ],
+          options.customIndexes?.formVersions
+        ),
         versionEvents.createIndexes([
           { key: { formId: 1, fromRevision: 1, eventIndex: 1 }, name: "form_version_events_revision" }
-        ])
+        ]),
+        createConfiguredIndexes(schemas, [], options.customIndexes?.forms)
       ]);
     }
   };

package/dist/index.d.cts

@@ -1,12 +1,27 @@
 import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
-import { Db, Document } from 'mongodb';
+import { IndexSpecification, CreateIndexesOptions, Db, Document } from 'mongodb';
 
+interface MongoCustomIndexDefinition {
+    readonly spec: IndexSpecification;
+    readonly options?: CreateIndexesOptions;
+}
 interface MongoDbStorageOptions {
     readonly db: Db;
     readonly schemasCollectionName?: string;
     readonly responsesCollectionName?: string;
     readonly versionsCollectionName?: string;
     readonly versionStatesCollectionName?: string;
+    readonly collectionNames?: {
+        readonly forms?: string;
+        readonly formVersions?: string;
+        readonly formVersionStates?: string;
+        readonly formResponses?: string;
+    };
+    readonly customIndexes?: {
+        readonly forms?: readonly MongoCustomIndexDefinition[];
+        readonly formVersions?: readonly MongoCustomIndexDefinition[];
+        readonly formResponses?: readonly MongoCustomIndexDefinition[];
+    };
 }
 interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, VersionedFormStorageAdapter {
     createIndexes(): Promise<void>;
@@ -14,4 +29,4 @@ interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, Versioned
 declare function submissionFilterToMongo(filter: SubmissionFilter): Document;
 declare function createMongoDbStorage(options: MongoDbStorageOptions): MongoDbStorageAdapter;
 
-export { type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage, submissionFilterToMongo };
+export { type MongoCustomIndexDefinition, type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage, submissionFilterToMongo };

package/dist/index.d.ts

@@ -1,12 +1,27 @@
 import { PagedSubmissionStorageAdapter, VersionedFormStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
-import { Db, Document } from 'mongodb';
+import { IndexSpecification, CreateIndexesOptions, Db, Document } from 'mongodb';
 
+interface MongoCustomIndexDefinition {
+    readonly spec: IndexSpecification;
+    readonly options?: CreateIndexesOptions;
+}
 interface MongoDbStorageOptions {
     readonly db: Db;
     readonly schemasCollectionName?: string;
     readonly responsesCollectionName?: string;
     readonly versionsCollectionName?: string;
     readonly versionStatesCollectionName?: string;
+    readonly collectionNames?: {
+        readonly forms?: string;
+        readonly formVersions?: string;
+        readonly formVersionStates?: string;
+        readonly formResponses?: string;
+    };
+    readonly customIndexes?: {
+        readonly forms?: readonly MongoCustomIndexDefinition[];
+        readonly formVersions?: readonly MongoCustomIndexDefinition[];
+        readonly formResponses?: readonly MongoCustomIndexDefinition[];
+    };
 }
 interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, VersionedFormStorageAdapter {
     createIndexes(): Promise<void>;
@@ -14,4 +29,4 @@ interface MongoDbStorageAdapter extends PagedSubmissionStorageAdapter, Versioned
 declare function submissionFilterToMongo(filter: SubmissionFilter): Document;
 declare function createMongoDbStorage(options: MongoDbStorageOptions): MongoDbStorageAdapter;
 
-export { type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage, submissionFilterToMongo };
+export { type MongoCustomIndexDefinition, type MongoDbStorageAdapter, type MongoDbStorageOptions, createMongoDbStorage, submissionFilterToMongo };

package/dist/index.js

@@ -131,23 +131,56 @@ function collectionName(value, fallback, optionName) {
   if (value.trim().length === 0) throw new TypeError(`${optionName} must be a non-empty string.`);
   return value;
 }
+function normalizeIndexSpecification(spec) {
+  if (typeof spec === "string") return { [spec]: 1 };
+  if (Array.isArray(spec)) return Object.fromEntries(spec.map((field) => [field, 1]));
+  if (spec instanceof Map) return spec;
+  if (!isRecord(spec) || Object.keys(spec).length === 0) throw new TypeError("Index specification must not be empty.");
+  return spec;
+}
+function customIndexDescriptions(definitions) {
+  return (definitions ?? []).map(({ spec, options: indexOptions }) => ({
+    ...indexOptions ?? {},
+    key: normalizeIndexSpecification(spec)
+  }));
+}
+async function createConfiguredIndexes(collection, defaults, custom) {
+  const definitions = custom ?? [];
+  if (definitions.length === 0) {
+    await collection.createIndexes(defaults);
+    return;
+  }
+  if (collection.createIndex === void 0) {
+    await collection.createIndexes([...defaults, ...customIndexDescriptions(definitions)]);
+    return;
+  }
+  await collection.createIndexes(defaults);
+  for (const { spec, options: indexOptions } of definitions) {
+    await collection.createIndex(normalizeIndexSpecification(spec), indexOptions);
+  }
+}
 function createMongoDbStorage(options) {
   if (options?.db === void 0) throw new TypeError("db is required.");
-  const schemasCollectionName = collectionName(options.schemasCollectionName, "form_schemas", "schemasCollectionName");
+  const collectionNames = options.collectionNames;
+  const schemasCollectionName = collectionName(
+    collectionNames?.forms ?? options.schemasCollectionName,
+    collectionNames === void 0 ? "form_schemas" : "forms",
+    collectionNames?.forms === void 0 ? "schemasCollectionName" : "collectionNames.forms"
+  );
   const responsesCollectionName = collectionName(
-    options.responsesCollectionName,
+    collectionNames?.formResponses ?? options.responsesCollectionName,
     "form_responses",
-    "responsesCollectionName"
+    collectionNames?.formResponses === void 0 ? "responsesCollectionName" : "collectionNames.formResponses"
   );
   const versionsCollectionName = collectionName(
-    options.versionsCollectionName,
+    collectionNames?.formVersions ?? options.versionsCollectionName,
     "form_versions",
-    "versionsCollectionName"
+    collectionNames?.formVersions === void 0 ? "versionsCollectionName" : "collectionNames.formVersions"
   );
   const versionStatesCollectionName = collectionName(
-    options.versionStatesCollectionName,
+    collectionNames?.formVersionStates ?? options.versionStatesCollectionName,
     "form_version_states",
-    "versionStatesCollectionName"
+    collectionNames?.formVersionStates === void 0 ? "versionStatesCollectionName" : "collectionNames.formVersionStates"
   );
   const versionEventsCollectionName = "form_version_events";
   const schemas = options.db.collection(schemasCollectionName);
@@ -464,28 +497,37 @@ function createMongoDbStorage(options) {
     },
     async createIndexes() {
       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: "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" }
-          }
-        ]),
+        createConfiguredIndexes(
+          submissions,
+          [
+            { key: { formId: 1, submittedAt: 1, _id: 1 }, name: "form_responses_form_submitted_at_id" },
+            { key: { "submission.locale": 1 }, name: "form_responses_locale" }
+          ],
+          options.customIndexes?.formResponses
+        ),
+        createConfiguredIndexes(
+          versions,
+          [
+            { 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" }
+            }
+          ],
+          options.customIndexes?.formVersions
+        ),
         versionEvents.createIndexes([
           { key: { formId: 1, fromRevision: 1, eventIndex: 1 }, name: "form_version_events_revision" }
-        ])
+        ]),
+        createConfiguredIndexes(schemas, [], options.customIndexes?.forms)
       ]);
     }
   };

package/package.json

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