@orion-js/mongodb 4.1.10 → 4.2.1

package/dist/index.d.cts

@@ -73,8 +73,26 @@ type DocumentWithId<TSchema> = EnhancedOmit<TSchema, '_id'> & {
     _id: InferIdType<TSchema>;
 };
 type ModelClassBase = DocumentWithId<MongoDB.Document>;
-interface CollectionIndex {
+/**
+ * Index definition for a MongoDB collection.
+ * Supports flat options (recommended) or nested options object (deprecated).
+ *
+ * @example New format (recommended):
+ * ```ts
+ * { keys: { email: 1 }, unique: true, sparse: true }
+ * ```
+ *
+ * @example Old format (deprecated):
+ * ```ts
+ * { keys: { email: 1 }, options: { unique: true, sparse: true } }
+ * ```
+ */
+interface CollectionIndex extends Partial<MongoDB.CreateIndexesOptions> {
     keys: MongoDB.IndexSpecification;
+    /**
+     * @deprecated Use flat options instead. Example: `{ keys: { email: 1 }, unique: true }`
+     * instead of `{ keys: { email: 1 }, options: { unique: true } }`
+     */
     options?: MongoDB.CreateIndexesOptions;
 }
 declare namespace DataLoader {
@@ -229,6 +247,15 @@ declare class BaseCollection<ModelClass extends ModelClassBase = ModelClassBase>
      */
     createIndexes: () => Promise<string[]>;
     createIndexesPromise: Promise<string[]>;
+    /**
+     * Deletes indexes that exist in MongoDB but are not defined in the collection configuration.
+     * This helps clean up stale indexes that are no longer needed.
+     * Always preserves the _id_ index.
+     */
+    deleteUnusedIndexes: () => Promise<{
+        deletedIndexes: string[];
+        collectionName: string;
+    }>;
     /**
      * @deprecated Use startConnection() instead. This property is not guaranteed to be resolved if the connection is not started.
      * When using async calls startConnection or connectionPromise is no longer needed. Orion will automatically start the connection if it is not already started.
@@ -277,6 +304,58 @@ declare function createCollection<T extends TypedSchemaOnSchema & {
 }>(options: CreateCollectionOptionsWithTypedSchema<T>): Collection<InferSchemaType<T>>;
 declare function createCollection<T extends ModelClassBase>(options: CreateCollectionOptions<T>): Collection<T>;
 
+/**
+ * Result of the deleteUnusedIndexes operation
+ */
+interface DeleteUnusedIndexesResult {
+    /** Names of the indexes that were deleted */
+    deletedIndexes: string[];
+    /** Name of the collection that was cleaned */
+    collectionName: string;
+}
+
+/**
+ * Registry that tracks all collections created via createCollection().
+ * Maps connection name to a map of collection name to collection instance.
+ */
+declare const collectionsRegistry: Map<string, Map<string, Collection<ModelClassBase>>>;
+/**
+ * Registers a collection in the registry.
+ * Called automatically when a collection is created via createCollection().
+ * @param connectionName - The name of the MongoDB connection
+ * @param collection - The collection instance to register
+ */
+declare function registerCollection(connectionName: string, collection: Collection<ModelClassBase>): void;
+/**
+ * Gets all registered collections for a specific connection.
+ * @param connectionName - The name of the MongoDB connection (defaults to 'main')
+ * @returns Array of registered collections for the connection
+ */
+declare function getRegisteredCollections(connectionName?: string): Array<Collection<ModelClassBase>>;
+/**
+ * Deletes unused indexes from all registered collections for a connection.
+ * Iterates over all collections registered via createCollection() and
+ * removes indexes that exist in MongoDB but are not defined in the collection configuration.
+ *
+ * @param connectionName - The name of the MongoDB connection (defaults to 'main')
+ * @returns Array of results for each collection that had indexes deleted
+ *
+ * @example
+ * ```ts
+ * // Delete unused indexes from all collections on the main connection
+ * const results = await deleteAllUnusedIndexes()
+ *
+ * // Delete unused indexes from all collections on a specific connection
+ * const results = await deleteAllUnusedIndexes('secondary')
+ *
+ * // Log results
+ * for (const result of results) {
+ *   console.log(`${result.collectionName}: deleted ${result.deletedIndexes.length} indexes`)
+ * }
+ * ```
+ */
+declare function deleteAllUnusedIndexes(connectionName?: string): Promise<DeleteUnusedIndexesResult[]>;
+
 declare function getOrCreateEncryptionKey({ keyAltName, kmsProvider, masterKey, connectionName, keyVaultDatabase, keyVaultCollection, kmsProviders, }: {
     keyAltName: string;
     kmsProvider: keyof KMSProviders;
@@ -294,4 +373,4 @@ declare const ENCRYPTION_ALGORITHMS: {
     RANDOM: string;
 };
 
-export { BaseCollection, Collection, type CollectionIndex, type CountDocuments, type CreateCollectionOptions, type CreateCollectionOptionsWithSchemaType, type CreateCollectionOptionsWithTypedSchema, DataLoader, type DeleteMany, type DeleteOne, type DistinctDocumentId, type DocumentWithId, ENCRYPTION_ALGORITHMS, type EstimatedDocumentCount, type Find, type FindCursor, type FindOne, type FindOneAndUpdate, type FindOneAndUpdateUpdateOptions, type InferIdType, type InferSchemaTypeWithId, type InitItem, type InsertAndFind, type InsertMany, type InsertManyOptions, type InsertOne, type InsertOptions, type ModelClassBase, type ModelToMongoSelector, MongoCollection, type MongoFilter, type MongoSelector, type OptionalId, Repository, type SchemaWithRequiredId, type TypedId, type UpdateAndFind, type UpdateItem, type UpdateMany, type UpdateOne, type UpdateOptions, type Upsert, allConnectionPromises, configureConnection, connections, createCollection, createIndexesPromises, getDBName, getMongoConnection, getOrCreateEncryptionKey, typedId };
+export { BaseCollection, Collection, type CollectionIndex, type CountDocuments, type CreateCollectionOptions, type CreateCollectionOptionsWithSchemaType, type CreateCollectionOptionsWithTypedSchema, DataLoader, type DeleteMany, type DeleteOne, type DistinctDocumentId, type DocumentWithId, ENCRYPTION_ALGORITHMS, type EstimatedDocumentCount, type Find, type FindCursor, type FindOne, type FindOneAndUpdate, type FindOneAndUpdateUpdateOptions, type InferIdType, type InferSchemaTypeWithId, type InitItem, type InsertAndFind, type InsertMany, type InsertManyOptions, type InsertOne, type InsertOptions, type ModelClassBase, type ModelToMongoSelector, MongoCollection, type MongoFilter, type MongoSelector, type OptionalId, Repository, type SchemaWithRequiredId, type TypedId, type UpdateAndFind, type UpdateItem, type UpdateMany, type UpdateOne, type UpdateOptions, type Upsert, allConnectionPromises, collectionsRegistry, configureConnection, connections, createCollection, createIndexesPromises, deleteAllUnusedIndexes, getDBName, getMongoConnection, getOrCreateEncryptionKey, getRegisteredCollections, registerCollection, typedId };

package/dist/index.d.ts

@@ -73,8 +73,26 @@ type DocumentWithId<TSchema> = EnhancedOmit<TSchema, '_id'> & {
     _id: InferIdType<TSchema>;
 };
 type ModelClassBase = DocumentWithId<MongoDB.Document>;
-interface CollectionIndex {
+/**
+ * Index definition for a MongoDB collection.
+ * Supports flat options (recommended) or nested options object (deprecated).
+ *
+ * @example New format (recommended):
+ * ```ts
+ * { keys: { email: 1 }, unique: true, sparse: true }
+ * ```
+ *
+ * @example Old format (deprecated):
+ * ```ts
+ * { keys: { email: 1 }, options: { unique: true, sparse: true } }
+ * ```
+ */
+interface CollectionIndex extends Partial<MongoDB.CreateIndexesOptions> {
     keys: MongoDB.IndexSpecification;
+    /**
+     * @deprecated Use flat options instead. Example: `{ keys: { email: 1 }, unique: true }`
+     * instead of `{ keys: { email: 1 }, options: { unique: true } }`
+     */
     options?: MongoDB.CreateIndexesOptions;
 }
 declare namespace DataLoader {
@@ -229,6 +247,15 @@ declare class BaseCollection<ModelClass extends ModelClassBase = ModelClassBase>
      */
     createIndexes: () => Promise<string[]>;
     createIndexesPromise: Promise<string[]>;
+    /**
+     * Deletes indexes that exist in MongoDB but are not defined in the collection configuration.
+     * This helps clean up stale indexes that are no longer needed.
+     * Always preserves the _id_ index.
+     */
+    deleteUnusedIndexes: () => Promise<{
+        deletedIndexes: string[];
+        collectionName: string;
+    }>;
     /**
      * @deprecated Use startConnection() instead. This property is not guaranteed to be resolved if the connection is not started.
      * When using async calls startConnection or connectionPromise is no longer needed. Orion will automatically start the connection if it is not already started.
@@ -277,6 +304,58 @@ declare function createCollection<T extends TypedSchemaOnSchema & {
 }>(options: CreateCollectionOptionsWithTypedSchema<T>): Collection<InferSchemaType<T>>;
 declare function createCollection<T extends ModelClassBase>(options: CreateCollectionOptions<T>): Collection<T>;
 
+/**
+ * Result of the deleteUnusedIndexes operation
+ */
+interface DeleteUnusedIndexesResult {
+    /** Names of the indexes that were deleted */
+    deletedIndexes: string[];
+    /** Name of the collection that was cleaned */
+    collectionName: string;
+}
+
+/**
+ * Registry that tracks all collections created via createCollection().
+ * Maps connection name to a map of collection name to collection instance.
+ */
+declare const collectionsRegistry: Map<string, Map<string, Collection<ModelClassBase>>>;
+/**
+ * Registers a collection in the registry.
+ * Called automatically when a collection is created via createCollection().
+ * @param connectionName - The name of the MongoDB connection
+ * @param collection - The collection instance to register
+ */
+declare function registerCollection(connectionName: string, collection: Collection<ModelClassBase>): void;
+/**
+ * Gets all registered collections for a specific connection.
+ * @param connectionName - The name of the MongoDB connection (defaults to 'main')
+ * @returns Array of registered collections for the connection
+ */
+declare function getRegisteredCollections(connectionName?: string): Array<Collection<ModelClassBase>>;
+/**
+ * Deletes unused indexes from all registered collections for a connection.
+ * Iterates over all collections registered via createCollection() and
+ * removes indexes that exist in MongoDB but are not defined in the collection configuration.
+ *
+ * @param connectionName - The name of the MongoDB connection (defaults to 'main')
+ * @returns Array of results for each collection that had indexes deleted
+ *
+ * @example
+ * ```ts
+ * // Delete unused indexes from all collections on the main connection
+ * const results = await deleteAllUnusedIndexes()
+ *
+ * // Delete unused indexes from all collections on a specific connection
+ * const results = await deleteAllUnusedIndexes('secondary')
+ *
+ * // Log results
+ * for (const result of results) {
+ *   console.log(`${result.collectionName}: deleted ${result.deletedIndexes.length} indexes`)
+ * }
+ * ```
+ */
+declare function deleteAllUnusedIndexes(connectionName?: string): Promise<DeleteUnusedIndexesResult[]>;
+
 declare function getOrCreateEncryptionKey({ keyAltName, kmsProvider, masterKey, connectionName, keyVaultDatabase, keyVaultCollection, kmsProviders, }: {
     keyAltName: string;
     kmsProvider: keyof KMSProviders;
@@ -294,4 +373,4 @@ declare const ENCRYPTION_ALGORITHMS: {
     RANDOM: string;
 };
 
-export { BaseCollection, Collection, type CollectionIndex, type CountDocuments, type CreateCollectionOptions, type CreateCollectionOptionsWithSchemaType, type CreateCollectionOptionsWithTypedSchema, DataLoader, type DeleteMany, type DeleteOne, type DistinctDocumentId, type DocumentWithId, ENCRYPTION_ALGORITHMS, type EstimatedDocumentCount, type Find, type FindCursor, type FindOne, type FindOneAndUpdate, type FindOneAndUpdateUpdateOptions, type InferIdType, type InferSchemaTypeWithId, type InitItem, type InsertAndFind, type InsertMany, type InsertManyOptions, type InsertOne, type InsertOptions, type ModelClassBase, type ModelToMongoSelector, MongoCollection, type MongoFilter, type MongoSelector, type OptionalId, Repository, type SchemaWithRequiredId, type TypedId, type UpdateAndFind, type UpdateItem, type UpdateMany, type UpdateOne, type UpdateOptions, type Upsert, allConnectionPromises, configureConnection, connections, createCollection, createIndexesPromises, getDBName, getMongoConnection, getOrCreateEncryptionKey, typedId };
+export { BaseCollection, Collection, type CollectionIndex, type CountDocuments, type CreateCollectionOptions, type CreateCollectionOptionsWithSchemaType, type CreateCollectionOptionsWithTypedSchema, DataLoader, type DeleteMany, type DeleteOne, type DistinctDocumentId, type DocumentWithId, ENCRYPTION_ALGORITHMS, type EstimatedDocumentCount, type Find, type FindCursor, type FindOne, type FindOneAndUpdate, type FindOneAndUpdateUpdateOptions, type InferIdType, type InferSchemaTypeWithId, type InitItem, type InsertAndFind, type InsertMany, type InsertManyOptions, type InsertOne, type InsertOptions, type ModelClassBase, type ModelToMongoSelector, MongoCollection, type MongoFilter, type MongoSelector, type OptionalId, Repository, type SchemaWithRequiredId, type TypedId, type UpdateAndFind, type UpdateItem, type UpdateMany, type UpdateOne, type UpdateOptions, type Upsert, allConnectionPromises, collectionsRegistry, configureConnection, connections, createCollection, createIndexesPromises, deleteAllUnusedIndexes, getDBName, getMongoConnection, getOrCreateEncryptionKey, getRegisteredCollections, registerCollection, typedId };

package/dist/index.js

@@ -248,6 +248,12 @@ var BaseCollection = class {
    */
   createIndexes;
   createIndexesPromise;
+  /**
+   * Deletes indexes that exist in MongoDB but are not defined in the collection configuration.
+   * This helps clean up stale indexes that are no longer needed.
+   * Always preserves the _id_ index.
+   */
+  deleteUnusedIndexes;
   /**
    * @deprecated Use startConnection() instead. This property is not guaranteed to be resolved if the connection is not started.
    * When using async calls startConnection or connectionPromise is no longer needed. Orion will automatically start the connection if it is not already started.
@@ -1140,12 +1146,82 @@ var generateId_default = getIdGenerator;
 
 // src/createCollection/createIndexes.ts
 import { MongoExpiredSessionError, MongoNotConnectedError } from "mongodb";
+import { logger as logger3 } from "@orion-js/logger";
+
+// src/createCollection/deleteUnusedIndexes.ts
 import { logger as logger2 } from "@orion-js/logger";
-function matchingDefinition(defIndex, curIndex) {
-  if (defIndex.options && defIndex.options.name === curIndex.name) return true;
-  const defIndexName = Object.keys(defIndex.keys).map((key) => `${key}_${defIndex.keys[key]}`).join("_");
-  return defIndexName === curIndex.name;
+
+// src/createCollection/getIndexOptions.ts
+function getIndexOptions(indexDef) {
+  const { keys: _keys, options: deprecatedOptions, ...flatOptions } = indexDef;
+  if (deprecatedOptions) {
+    return { ...deprecatedOptions, ...flatOptions };
+  }
+  return Object.keys(flatOptions).length > 0 ? flatOptions : void 0;
+}
+function getIndexName(indexDef) {
+  var _a;
+  if (indexDef.name) {
+    return indexDef.name;
+  }
+  return (_a = indexDef.options) == null ? void 0 : _a.name;
+}
+
+// src/createCollection/deleteUnusedIndexes.ts
+function keysMatch(definitionKeys, currentIndexKey) {
+  const defEntries = Object.entries(definitionKeys);
+  const curEntries = Object.entries(currentIndexKey);
+  if (defEntries.length !== curEntries.length) return false;
+  for (let i = 0; i < defEntries.length; i++) {
+    const [defKey, defValue] = defEntries[i];
+    const [curKey, curValue] = curEntries[i];
+    if (defKey !== curKey || defValue !== curValue) return false;
+  }
+  return true;
+}
+function isIndexDefined(definedIndexes, currentIndex) {
+  return definedIndexes.some((defIndex) => {
+    const customName = getIndexName(defIndex);
+    if (customName && customName === currentIndex.name) return true;
+    return keysMatch(defIndex.keys, currentIndex.key);
+  });
 }
+async function deleteUnusedIndexes(collection) {
+  await collection.connectionPromise;
+  const result = {
+    deletedIndexes: [],
+    collectionName: collection.name
+  };
+  let currentIndexes = [];
+  try {
+    currentIndexes = await collection.rawCollection.indexes();
+  } catch (error) {
+    if (error.codeName === "NamespaceNotFound") {
+      return result;
+    }
+    throw error;
+  }
+  if (!collection.indexes || collection.indexes.length === 0) {
+    return result;
+  }
+  const unusedIndexes = currentIndexes.filter(
+    (index) => index.name !== "_id_" && !isIndexDefined(collection.indexes, index)
+  );
+  for (const index of unusedIndexes) {
+    try {
+      await collection.rawCollection.dropIndex(index.name);
+      result.deletedIndexes.push(index.name);
+      logger2.info(`Deleted unused index "${index.name}" from collection "${collection.name}"`);
+    } catch (error) {
+      logger2.error(`Failed to delete index "${index.name}" from collection "${collection.name}"`, {
+        error
+      });
+    }
+  }
+  return result;
+}
+
+// src/createCollection/createIndexes.ts
 async function checkIndexes(collection) {
   await collection.connectionPromise;
   let currentIndexes = [];
@@ -1153,13 +1229,17 @@ async function checkIndexes(collection) {
     currentIndexes = await collection.rawCollection.indexes();
   } catch (error) {
     if (error.codeName !== "NamespaceNotFound") throw error;
+    return;
   }
-  const indexesToDelete = collection.indexes ? currentIndexes.filter(
-    (index) => index.name !== "_id_" && !collection.indexes.find((definitionIndex) => matchingDefinition(definitionIndex, index))
-  ) : currentIndexes;
-  if (indexesToDelete.length > 0) {
-    logger2.warn(
-      `${indexesToDelete.length} unexpected indexes found in collection "${collection.name}": ${indexesToDelete.map((i) => i.name).join(", ")} | Delete the index or fix the collection definition`
+  if (!collection.indexes || collection.indexes.length === 0) {
+    return;
+  }
+  const unexpectedIndexes = currentIndexes.filter(
+    (index) => index.name !== "_id_" && !isIndexDefined(collection.indexes, index)
+  );
+  if (unexpectedIndexes.length > 0) {
+    logger3.warn(
+      `${unexpectedIndexes.length} unexpected indexes found in collection "${collection.name}": ${unexpectedIndexes.map((i) => i.name).join(", ")} | Delete the index or fix the collection definition`
     );
   }
 }
@@ -1168,7 +1248,9 @@ async function loadIndexes(collection) {
   if (!collection.indexes.length) return;
   await collection.connectionPromise;
   const results = Promise.all(
-    collection.indexes.map(async ({ keys, options }) => {
+    collection.indexes.map(async (indexDef) => {
+      const { keys } = indexDef;
+      const options = getIndexOptions(indexDef);
       try {
         return await collection.rawCollection.createIndex(keys, options);
       } catch (error) {
@@ -1198,6 +1280,43 @@ async function loadIndexes(collection) {
   return results;
 }
 
+// src/createCollection/collectionsRegistry.ts
+import { logger as logger4 } from "@orion-js/logger";
+var collectionsRegistry = /* @__PURE__ */ new Map();
+function registerCollection(connectionName, collection) {
+  if (!collectionsRegistry.has(connectionName)) {
+    collectionsRegistry.set(connectionName, /* @__PURE__ */ new Map());
+  }
+  collectionsRegistry.get(connectionName).set(collection.name, collection);
+}
+function getRegisteredCollections(connectionName = "main") {
+  const connectionCollections = collectionsRegistry.get(connectionName);
+  if (!connectionCollections) {
+    return [];
+  }
+  return Array.from(connectionCollections.values());
+}
+async function deleteAllUnusedIndexes(connectionName = "main") {
+  const collections = getRegisteredCollections(connectionName);
+  if (collections.length === 0) {
+    logger4.warn(`No collections registered for connection "${connectionName}"`);
+    return [];
+  }
+  logger4.info(
+    `Deleting unused indexes from ${collections.length} collections on connection "${connectionName}"`
+  );
+  const results = [];
+  for (const collection of collections) {
+    const result = await collection.deleteUnusedIndexes();
+    if (result.deletedIndexes.length > 0) {
+      results.push(result);
+    }
+  }
+  const totalDeleted = results.reduce((sum, r) => sum + r.deletedIndexes.length, 0);
+  logger4.info(`Deleted ${totalDeleted} unused indexes from ${results.length} collections`);
+  return results;
+}
+
 // src/createCollection/getSchemaAndModel.ts
 import { clone as clone3 } from "@orion-js/helpers";
 Symbol.metadata ?? (Symbol.metadata = Symbol("Symbol.metadata"));
@@ -1230,7 +1349,7 @@ function getSchema(options) {
 }
 
 // src/createCollection/wrapMethods.ts
-import { logger as logger3 } from "@orion-js/logger";
+import { logger as logger5 } from "@orion-js/logger";
 function wrapMethods(collection) {
   const methodsWithPromises = [
     "findOne",
@@ -1266,7 +1385,7 @@ function wrapMethods(collection) {
         collection[methodName2] = (...args) => {
           collection.startConnection();
           if (!collection.rawCollection) {
-            logger3.error("Method called before connection was initialized", {
+            logger5.error("Method called before connection was initialized", {
               collectionName: collection.name,
               connectionName: collection.connectionName,
               methodName: methodName2
@@ -1367,11 +1486,16 @@ function createCollection(options) {
     return createIndexPromise;
   };
   mainCollection.createIndexes = createIndexes;
+  mainCollection.deleteUnusedIndexes = async () => {
+    await orionConnection.startConnection();
+    return deleteUnusedIndexes(mainCollection);
+  };
   if (!process.env.DONT_CREATE_INDEXES_AUTOMATICALLY) {
     createIndexes();
   }
   wrapMethods(mainCollection);
   wrapMethods(encryptedCollection);
+  registerCollection(connectionName, mainCollection);
   return mainCollection;
 }
 
@@ -1402,7 +1526,7 @@ function MongoCollection(options) {
 }
 
 // src/encrypted/getOrCreateEncryptionKey.ts
-import { logger as logger4 } from "@orion-js/logger";
+import { logger as logger6 } from "@orion-js/logger";
 import { ClientEncryption, MongoClient as MongoClient2 } from "mongodb";
 async function getOrCreateEncryptionKey({
   keyAltName,
@@ -1414,7 +1538,7 @@ async function getOrCreateEncryptionKey({
   kmsProviders
 }) {
   const keyVaultNamespace = `${keyVaultDatabase}.${keyVaultCollection}`;
-  logger4.info("Connecting to database to get or create the encryption key", {
+  logger6.info("Connecting to database to get or create the encryption key", {
     keyVaultNamespace,
     keyAltName
   });
@@ -1432,14 +1556,14 @@ async function getOrCreateEncryptionKey({
   });
   const key = await clientEncryption.getKeyByAltName(keyAltName);
   if (key) {
-    logger4.info("Key found on the key vault", {
+    logger6.info("Key found on the key vault", {
       keyVaultNamespace,
       keyAltName,
       UUID: key._id
     });
     return { key: key._id, keyVaultNamespace };
   }
-  logger4.info("Key not found on the key vault, creating a new one", {
+  logger6.info("Key not found on the key vault, creating a new one", {
     keyVaultNamespace,
     keyAltName
   });
@@ -1447,7 +1571,7 @@ async function getOrCreateEncryptionKey({
     keyAltNames: [keyAltName],
     ...masterKey ? { masterKey } : {}
   });
-  logger4.info("New encryption key created", {
+  logger6.info("New encryption key created", {
     keyVaultNamespace,
     keyAltName,
     UUID: newKey
@@ -1466,13 +1590,17 @@ export {
   MongoDB,
   Repository,
   allConnectionPromises,
+  collectionsRegistry,
   configureConnection,
   connections,
   createCollection,
   createIndexesPromises,
+  deleteAllUnusedIndexes,
   getDBName,
   getMongoConnection,
   getOrCreateEncryptionKey,
+  getRegisteredCollections,
+  registerCollection,
   typedId
 };
 //# sourceMappingURL=index.js.map