@warlock.js/cascade 4.0.174 → 4.1.1

package/esm/drivers/mongodb/mongodb-driver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb-driver.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/mongodb/mongodb-driver.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\r\nimport { log } from \"@warlock.js/logger\";\r\nimport type {\r\n  BulkWriteOptions,\r\n  ClientSession,\r\n  Db,\r\n  DeleteOptions,\r\n  FindOneAndDeleteOptions,\r\n  FindOneAndUpdateOptions,\r\n  InsertManyResult,\r\n  InsertOneOptions,\r\n  MongoClient,\r\n  MongoClientOptions,\r\n  TransactionOptions,\r\n  UpdateFilter,\r\n  UpdateOptions,\r\n} from \"mongodb\";\r\nimport { EventEmitter } from \"node:events\";\r\nimport { databaseTransactionContext } from \"../../context/database-transaction-context\";\r\nimport type {\r\n  DriverBlueprintContract,\r\n  DriverContract,\r\n  DriverEvent,\r\n  DriverEventListener,\r\n  DriverTransactionContract,\r\n  IdGeneratorContract,\r\n  InsertResult,\r\n  MigrationDriverContract,\r\n  QueryBuilderContract,\r\n  SyncAdapterContract,\r\n  TransactionContext,\r\n  UpdateOperations,\r\n  UpdateResult,\r\n} from \"../../contracts\";\r\nimport { dataSourceRegistry } from \"../../data-source/data-source-registry\";\r\nimport { DatabaseDirtyTracker } from \"../../database-dirty-tracker\";\r\nimport { TransactionRollbackError } from \"../../errors/transaction-rollback.error\";\r\nimport { type SQLSerializer } from \"../../migration/sql-serializer\";\r\nimport type { ModelDefaults } from \"../../types\";\r\nimport { isValidDateValue } from \"../../utils/is-valid-date-value\";\r\nimport { MongoDBBlueprint } from \"./mongodb-blueprint\";\r\nimport { MongoIdGenerator } from \"./mongodb-id-generator\";\r\nimport { MongoMigrationDriver } from \"./mongodb-migration-driver\";\r\nimport { MongoQueryBuilder } from \"./mongodb-query-builder\";\r\nimport { MongoSyncAdapter } from \"./mongodb-sync-adapter\";\r\nimport type { MongoDriverOptions } from \"./types\";\r\n\r\nconst DEFAULT_TRANSACTION_OPTIONS: TransactionOptions = {\r\n  readPreference: \"primary\",\r\n  readConcern: { level: \"local\" },\r\n  writeConcern: { w: \"majority\" },\r\n};\r\n\r\n// ============================================================\r\n// Lazy-loaded MongoDB SDK Types\r\n// ============================================================\r\n\r\n/**\r\n * Cached MongoDB module (loaded once, reused)\r\n */\r\nlet MongoDBClient: typeof import(\"mongodb\");\r\n\r\nlet ObjectId: typeof import(\"mongodb\").ObjectId;\r\n\r\nlet isModuleExists: boolean | null = null;\r\n\r\nlet loadingPromise: Promise<any>;\r\n\r\n/**\r\n * Installation instructions for MongoDB package\r\n */\r\nconst MONGODB_INSTALL_INSTRUCTIONS = `\r\nMongoDB driver requires the mongodb package.\r\nInstall it with:\r\n\r\n  npm install mongodb\r\n\r\nOr with your preferred package manager:\r\n\r\n  pnpm add mongodb\r\n  yarn add mongodb\r\n`.trim();\r\n\r\n/**\r\n * Load MongoDB module\r\n */\r\nasync function loadMongoDB() {\r\n  try {\r\n    loadingPromise = import(\"mongodb\");\r\n    MongoDBClient = await loadingPromise;\r\n    ObjectId = MongoDBClient.ObjectId;\r\n    isModuleExists = true;\r\n  } catch {\r\n    isModuleExists = false;\r\n  }\r\n}\r\n\r\nloadMongoDB();\r\n\r\nexport function isMongoDBDriverLoaded() {\r\n  return isModuleExists;\r\n}\r\n\r\nasync function assertModuleIsLoaded() {\r\n  if (isModuleExists === false) {\r\n    throw new Error(MONGODB_INSTALL_INSTRUCTIONS);\r\n  }\r\n\r\n  if (isModuleExists === null) {\r\n    await loadingPromise;\r\n\r\n    return await assertModuleIsLoaded();\r\n  }\r\n}\r\n\r\n/**\r\n * MongoDB driver implementation that fulfils the Cascade driver contract.\r\n *\r\n * It encapsulates the native Mongo client, exposes lifecycle events, and\r\n * provides helpers for CRUD, transactions, atomic updates, and sync adapters.\r\n */\r\nexport class MongoDbDriver implements DriverContract {\r\n  private readonly events = new EventEmitter();\r\n  public client?: MongoClient;\r\n  public database?: Db;\r\n  private connected = false;\r\n  private syncAdapterInstance?: MongoSyncAdapter;\r\n  private migrationDriverInstance?: MigrationDriverContract;\r\n  private readonly transactionOptions: TransactionOptions;\r\n  private idGeneratorInstance?: IdGeneratorContract;\r\n  private _blueprint?: DriverBlueprintContract;\r\n\r\n  public get blueprint(): DriverBlueprintContract {\r\n    if (!this._blueprint) {\r\n      this._blueprint = new MongoDBBlueprint(this.database!);\r\n    }\r\n\r\n    return this._blueprint!;\r\n  }\r\n\r\n  /**\r\n   * The name of this driver.\r\n   */\r\n  public readonly name = \"mongodb\";\r\n\r\n  /**\r\n   * Current database name\r\n   */\r\n  protected _databaseName?: string;\r\n\r\n  /**\r\n   * MongoDB driver model defaults.\r\n   *\r\n   * MongoDB follows NoSQL conventions:\r\n   * - camelCase naming for fields (createdAt, updatedAt, deletedAt)\r\n   * - Manual ID generation (auto-increment id field separate from _id)\r\n   * - Timestamps enabled by default\r\n   * - Trash delete strategy with per-collection trash tables\r\n   */\r\n  public readonly modelDefaults: Partial<ModelDefaults> = {\r\n    namingConvention: \"camelCase\",\r\n    createdAtColumn: \"createdAt\",\r\n    updatedAtColumn: \"updatedAt\",\r\n    deletedAtColumn: \"deletedAt\",\r\n    timestamps: true,\r\n    autoGenerateId: true, // MongoDB needs manual ID generation\r\n    strictMode: \"strip\",\r\n    deleteStrategy: \"trash\",\r\n    trashTable: (table) => `${table}Trash`, // Per-collection trash (usersTrash, productsTrash)\r\n  };\r\n\r\n  /**\r\n   * Create a new MongoDB driver using the supplied connection options.\r\n   *\r\n   * @param config - Connection configuration\r\n   * @param driverOptions - Driver-specific options\r\n   */\r\n  public constructor(\r\n    private readonly config: {\r\n      database: string;\r\n      uri?: string;\r\n      host?: string;\r\n      port?: number;\r\n      username?: string;\r\n      password?: string;\r\n      authSource?: string;\r\n      logging?: boolean;\r\n      clientOptions?: MongoClientOptions;\r\n    },\r\n    private readonly driverOptions?: MongoDriverOptions,\r\n  ) {\r\n    this.transactionOptions = {\r\n      ...DEFAULT_TRANSACTION_OPTIONS,\r\n      ...driverOptions?.transactionOptions,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Get data base name\r\n   */\r\n  public get databaseName(): string | undefined {\r\n    if (!this._databaseName) {\r\n      this.resolveDatabaseName();\r\n    }\r\n\r\n    return this._databaseName;\r\n  }\r\n\r\n  /**\r\n   * Resolve database name either from config or uri\r\n   */\r\n  private resolveDatabaseName() {\r\n    if (this.config.database) {\r\n      this._databaseName = this.config.database;\r\n    } else if (this.config.uri) {\r\n      this._databaseName = this.config.uri.split(\"/\").pop()?.split(\"?\")?.[0];\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Indicates whether the driver currently maintains an active connection.\r\n   */\r\n  public get isConnected(): boolean {\r\n    return this.connected;\r\n  }\r\n\r\n  /**\r\n   * Get the MongoDB database instance.\r\n   *\r\n   * @returns The MongoDB Db instance\r\n   * @throws {Error} If not connected\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const db = driver.getDatabase();\r\n   * const collection = db.collection(\"users\");\r\n   * ```\r\n   */\r\n  public getDatabase(): Db {\r\n    if (!this.database) {\r\n      throw new Error(\r\n        \"Database not available. Ensure the driver is connected before accessing the database.\",\r\n      );\r\n    }\r\n    return this.database;\r\n  }\r\n\r\n  /**\r\n   * Get the ID generator instance for this driver.\r\n   *\r\n   * Creates a MongoIdGenerator on first access if autoGenerateId is enabled.\r\n   *\r\n   * @returns The ID generator instance, or undefined if disabled\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const idGenerator = driver.getIdGenerator();\r\n   * if (idGenerator) {\r\n   *   const id = await idGenerator.generateNextId({ table: \"users\" });\r\n   * }\r\n   * ```\r\n   */\r\n  public getIdGenerator(): IdGeneratorContract | undefined {\r\n    // Return undefined if ID generation is disabled\r\n    if (this.driverOptions?.autoGenerateId === false) {\r\n      return undefined;\r\n    }\r\n\r\n    // Create ID generator lazily on first access\r\n    if (!this.idGeneratorInstance) {\r\n      this.idGeneratorInstance = new MongoIdGenerator(this, this.driverOptions?.counterCollection);\r\n    }\r\n\r\n    return this.idGeneratorInstance;\r\n  }\r\n\r\n  /**\r\n   * Establish a MongoDB connection using the configured options.\r\n   * Throws if the connection attempt fails.\r\n   */\r\n  public async connect(): Promise<void> {\r\n    if (this.connected) {\r\n      return;\r\n    }\r\n\r\n    await assertModuleIsLoaded();\r\n\r\n    const uri = this.resolveUri();\r\n\r\n    const { MongoClient, ObjectId: ObjectIdMongoDB } = MongoDBClient;\r\n\r\n    ObjectId = ObjectIdMongoDB;\r\n\r\n    const client = new MongoClient(uri, this.buildClientOptions());\r\n\r\n    try {\r\n      log.info(\r\n        \"database.mongodb\",\r\n        \"connection\",\r\n        `Connecting to database ${colors.bold(colors.yellowBright(this.databaseName))}`,\r\n      );\r\n      await client.connect();\r\n      this.client = client;\r\n      this.database = client.db(this.databaseName);\r\n\r\n      this.connected = true;\r\n      log.success(\"database.mongodb\", \"connection\", \"Connected to database\");\r\n\r\n      client.on(\"close\", () => {\r\n        if (this.connected) {\r\n          this.connected = false;\r\n          this.emit(\"disconnected\");\r\n          log.warn(\"database.mongodb\", \"connection\", \"Disconnected from database\");\r\n        }\r\n      });\r\n\r\n      if (this.config.logging) {\r\n        const ignoredCommands = [\"isMaster\", \"hello\", \"ping\", \"saslStart\", \"saslContinue\"];\r\n\r\n        client.on(\"commandStarted\", (event: any) => {\r\n          if (ignoredCommands.includes(event.commandName)) return;\r\n\r\n          let cmdStr = JSON.stringify(event.command);\r\n          if (cmdStr.length > 300) {\r\n            cmdStr = cmdStr.substring(0, 300) + \"...\";\r\n          }\r\n\r\n          log.info({\r\n            module: \"database.mongodb\",\r\n            action: \"query.executing\",\r\n            message: `[${event.commandName}] ${cmdStr}`,\r\n            context: { command: event.command },\r\n          });\r\n        });\r\n\r\n        client.on(\"commandSucceeded\", (event: any) => {\r\n          if (ignoredCommands.includes(event.commandName)) return;\r\n\r\n          log.success({\r\n            module: \"database.mongodb\",\r\n            action: \"query.executed\",\r\n            message: `[${event.duration.toFixed(2)}ms] [${event.commandName}]`,\r\n          });\r\n        });\r\n\r\n        client.on(\"commandFailed\", (event: any) => {\r\n          if (ignoredCommands.includes(event.commandName)) return;\r\n\r\n          log.error({\r\n            module: \"database.mongodb\",\r\n            action: \"query.error\",\r\n            message: `[${event.duration.toFixed(2)}ms] [${event.commandName}]`,\r\n            context: { failure: event.failure },\r\n          });\r\n        });\r\n      }\r\n\r\n      this.emit(\"connected\");\r\n    } catch (error: any) {\r\n      await client.close().catch(() => undefined);\r\n      this.emit(\"disconnected\");\r\n      log.error(\r\n        \"database.mongodb\",\r\n        \"connection\",\r\n        `Failed to connect to database: ${error.message}`,\r\n      );\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Close the underlying MongoDB connection.\r\n   */\r\n  public async disconnect(): Promise<void> {\r\n    if (!this.client) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      await this.client.close();\r\n    } finally {\r\n      this.connected = false;\r\n      this.emit(\"disconnected\");\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Subscribe to driver lifecycle events.\r\n   */\r\n  public on(event: DriverEvent, listener: DriverEventListener): void {\r\n    this.events.on(event, listener);\r\n  }\r\n\r\n  /**\r\n   * Insert a single document into the given collection.\r\n   */\r\n  public async insert(\r\n    table: string,\r\n    document: Record<string, unknown>,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<InsertResult> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<InsertOneOptions>(options);\r\n    const result = await collection.insertOne(document, mongoOptions);\r\n\r\n    return {\r\n      document: {\r\n        ...document,\r\n        _id: result.insertedId,\r\n      },\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Insert multiple documents into the given collection.\r\n   */\r\n  public async insertMany(\r\n    table: string,\r\n    documents: Record<string, unknown>[],\r\n    options?: Record<string, unknown>,\r\n  ): Promise<InsertResult[]> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<BulkWriteOptions>(options);\r\n    const result: InsertManyResult<Record<string, unknown>> = await collection.insertMany(\r\n      documents,\r\n      mongoOptions,\r\n    );\r\n\r\n    return documents.map((document, index) => {\r\n      const insertedId = result.insertedIds[index as unknown as keyof typeof result.insertedIds];\r\n\r\n      return {\r\n        document: {\r\n          ...document,\r\n          _id: insertedId,\r\n        },\r\n      };\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Update a single document that matches the provided filter.\r\n   */\r\n  public async update(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    update: Record<string, unknown>,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<UpdateResult> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<UpdateOptions>(options);\r\n    const result = await collection.updateOne(\r\n      filter,\r\n      update as UpdateFilter<Record<string, unknown>>,\r\n      mongoOptions,\r\n    );\r\n\r\n    return { modifiedCount: result.modifiedCount };\r\n  }\r\n\r\n  /**\r\n   * Replace a single document that matches the provided filter.\r\n   */\r\n  public async replace<T = unknown>(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    document: Record<string, unknown>,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<T | null> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const result = await collection.findOneAndReplace(filter, document as Record<string, unknown>);\r\n\r\n    return result?.value as T | null;\r\n  }\r\n\r\n  /**\r\n   * Find one and update a single document that matches the provided filter and return the updated document\r\n   */\r\n  public async findOneAndUpdate<T = unknown>(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    update: UpdateOperations,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<T | null> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<FindOneAndUpdateOptions>(options);\r\n    const result = await collection.findOneAndUpdate(filter, update as Record<string, unknown>, {\r\n      returnDocument: \"after\",\r\n      ...mongoOptions,\r\n    });\r\n\r\n    return result as T | null;\r\n  }\r\n\r\n  /**\r\n   * Upsert (insert or update) a single document.\r\n   *\r\n   * Uses MongoDB's findOneAndUpdate with upsert option.\r\n   *\r\n   * @param table - Target collection name\r\n   * @param filter - Filter conditions to find existing document\r\n   * @param document - Document data to insert or update\r\n   * @param options - Optional upsert options\r\n   * @returns The upserted document\r\n   */\r\n  public async upsert<T = unknown>(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    document: Record<string, unknown>,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<T> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<FindOneAndUpdateOptions>(options);\r\n\r\n    // Use $set to update all fields from document\r\n    const update = { $set: document };\r\n\r\n    const result = await collection.findOneAndUpdate(filter, update, {\r\n      upsert: true,\r\n      returnDocument: \"after\",\r\n      ...mongoOptions,\r\n    });\r\n\r\n    return result as T;\r\n  }\r\n\r\n  /**\r\n   * Find one and delete a single document that matches the provided filter and return the deleted document.\r\n   *\r\n   * @param table - Target collection name\r\n   * @param filter - Filter conditions\r\n   * @param options - Optional delete options\r\n   * @returns The deleted document or null if not found\r\n   */\r\n  public async findOneAndDelete<T = unknown>(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<T | null> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<FindOneAndDeleteOptions>(options);\r\n\r\n    const result = await collection.findOneAndDelete(filter, mongoOptions || {});\r\n\r\n    return result as T | null;\r\n  }\r\n\r\n  /**\r\n   * Update multiple documents that match the provided filter.\r\n   */\r\n  public async updateMany(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    update: UpdateOperations,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<UpdateResult> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<UpdateOptions>(options);\r\n    const result = await collection.updateMany(\r\n      filter,\r\n      update as UpdateFilter<Record<string, unknown>>,\r\n      mongoOptions,\r\n    );\r\n\r\n    return { modifiedCount: result.modifiedCount };\r\n  }\r\n\r\n  /**\r\n   * Delete a single document that matches the provided filter.\r\n   */\r\n  public async delete(\r\n    table: string,\r\n    filter: Record<string, unknown> = {},\r\n    options?: Record<string, unknown>,\r\n  ): Promise<number> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<DeleteOptions>(options);\r\n    const result = await collection.deleteOne(filter, mongoOptions);\r\n\r\n    return result.deletedCount > 0 ? 1 : 0;\r\n  }\r\n\r\n  /**\r\n   * Delete documents that match the provided filter.\r\n   */\r\n  public async deleteMany(\r\n    table: string,\r\n    filter: Record<string, unknown> = {},\r\n    options?: Record<string, unknown>,\r\n  ): Promise<number> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<DeleteOptions>(options);\r\n\r\n    const result = await collection.deleteMany(filter, mongoOptions);\r\n\r\n    return result.deletedCount ?? 0;\r\n  }\r\n\r\n  /**\r\n   * Remove all records from a collection.\r\n   *\r\n   * This uses deleteMany with an empty filter to remove all documents.\r\n   * For very large collections, consider using the migration driver's\r\n   * dropTable + createTable approach for better performance.\r\n   */\r\n  public async truncateTable(table: string, options?: Record<string, unknown>): Promise<number> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<DeleteOptions>(options);\r\n    const result = await collection.deleteMany({}, mongoOptions);\r\n\r\n    return result.deletedCount ?? 0;\r\n  }\r\n\r\n  /**\r\n   * Serialize the given data\r\n   */\r\n  public serialize(data: Record<string, unknown>): Record<string, unknown> {\r\n    const serialized: Record<string, unknown> = {};\r\n\r\n    for (const [key, value] of Object.entries(data)) {\r\n      if (value === undefined) {\r\n        continue; // Skip undefined values\r\n      }\r\n\r\n      if (value instanceof ObjectId) {\r\n        serialized[key] = value.toString();\r\n      } else if (value instanceof Date) {\r\n        serialized[key] = value.toISOString();\r\n      } else if (typeof value === \"bigint\") {\r\n        serialized[key] = value.toString();\r\n      } else if (typeof value === \"object\" && value !== null && !Array.isArray(value)) {\r\n        // Nested objects will be stored as JSONB\r\n        serialized[key] = value;\r\n      } else {\r\n        serialized[key] = value;\r\n      }\r\n    }\r\n\r\n    return serialized;\r\n  }\r\n\r\n  /**\r\n   * Get the dirty tracker for this driver.\r\n   */\r\n  public getDirtyTracker(data: Record<string, unknown>): DatabaseDirtyTracker {\r\n    return new DatabaseDirtyTracker(data);\r\n  }\r\n\r\n  /**\r\n   * Deserialize the given data\r\n   */\r\n  public deserialize(data: Record<string, unknown>): Record<string, unknown> {\r\n    if (data._id && typeof data._id === \"string\") {\r\n      data._id = new ObjectId(data._id);\r\n    }\r\n\r\n    for (const [key, value] of Object.entries(data)) {\r\n      // Only re-inflate strings — Mongo driver already returns Date objects from DB reads\r\n      if (typeof value === \"string\" && isValidDateValue(value)) {\r\n        data[key] = new Date(value);\r\n      }\r\n    }\r\n\r\n    return data;\r\n  }\r\n\r\n  /**\r\n   * Provide a Mongo-backed query builder instance for the given collection.\r\n   */\r\n  public queryBuilder<T = unknown>(table: string): QueryBuilderContract<T> {\r\n    return new MongoQueryBuilder(table, dataSourceRegistry.get());\r\n  }\r\n\r\n  /**\r\n   * Begin a MongoDB transaction, returning commit/rollback helpers.\r\n   */\r\n  public async beginTransaction(): Promise<DriverTransactionContract<ClientSession>> {\r\n    const client = this.getClientInstance();\r\n    const session = client.startSession();\r\n\r\n    await session.startTransaction(this.transactionOptions);\r\n    databaseTransactionContext.enter({ session });\r\n    let finished = false;\r\n\r\n    const finalize = async (operation: () => Promise<void>): Promise<void> => {\r\n      if (finished) return;\r\n\r\n      try {\r\n        await operation();\r\n      } finally {\r\n        finished = true;\r\n        databaseTransactionContext.exit();\r\n        await session.endSession().catch(() => undefined);\r\n      }\r\n    };\r\n\r\n    return {\r\n      context: session,\r\n      commit: async () => {\r\n        await finalize(async () => {\r\n          try {\r\n            await session.commitTransaction();\r\n          } catch (error) {\r\n            await session.abortTransaction().catch(() => undefined);\r\n            throw error;\r\n          }\r\n        });\r\n      },\r\n      rollback: async () => {\r\n        await finalize(async () => {\r\n          await session.abortTransaction();\r\n        });\r\n      },\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Execute a function within a transaction scope (recommended pattern).\r\n   *\r\n   * Automatically commits on success, rolls back on any error, and guarantees\r\n   * resource cleanup. This is the recommended way to use transactions.\r\n   *\r\n   * **MongoDB Requirements:**\r\n   * - Requires MongoDB 4.0+ with replica set or sharded cluster\r\n   * - Standalone MongoDB instances do not support transactions\r\n   *\r\n   * @param fn - Async function to execute within transaction\r\n   * @param options - Transaction options (read preference, write concern, etc.)\r\n   * @returns The return value of the callback function\r\n   * @throws {Error} If transaction fails, is explicitly rolled back, or replica set not configured\r\n   */\r\n  public async transaction<T>(\r\n    fn: (ctx: TransactionContext) => Promise<T>,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<T> {\r\n    // Prevent nested transaction() calls\r\n    if (databaseTransactionContext.hasActiveTransaction()) {\r\n      throw new Error(\r\n        \"Nested transaction() calls are not supported. \" +\r\n          \"Use beginTransaction() with savepoints for advanced transaction patterns.\",\r\n      );\r\n    }\r\n\r\n    // Check if MongoDB is running as a replica set (required for transactions)\r\n    await this.ensureReplicaSetAvailable();\r\n\r\n    const client = this.getClientInstance();\r\n    const session = client.startSession();\r\n\r\n    try {\r\n      await session.startTransaction({\r\n        ...this.transactionOptions,\r\n        ...(options as TransactionOptions),\r\n      });\r\n\r\n      // Set transaction context for queries within callback\r\n      databaseTransactionContext.enter({ session });\r\n\r\n      try {\r\n        // Create transaction context with rollback method\r\n        const ctx: TransactionContext = {\r\n          rollback(reason?: string): never {\r\n            throw new TransactionRollbackError(reason);\r\n          },\r\n        };\r\n\r\n        // Execute callback\r\n        const result = await fn(ctx);\r\n\r\n        // Auto-commit on success\r\n        await session.commitTransaction();\r\n\r\n        return result;\r\n      } catch (error) {\r\n        // Auto-rollback on any error (including explicit rollback)\r\n        await session.abortTransaction().catch(() => undefined);\r\n        throw error;\r\n      } finally {\r\n        // Guaranteed context cleanup\r\n        databaseTransactionContext.exit();\r\n      }\r\n    } finally {\r\n      // Guaranteed session cleanup\r\n      await session.endSession().catch(() => undefined);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Execute atomic operations (typically $inc/$set style updates) against documents.\r\n   *\r\n   * Uses `updateMany` so callers can atomically modify any set of documents.\r\n   */\r\n  public async atomic(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    operations: Record<string, unknown>,\r\n    options?: Record<string, unknown>,\r\n  ): Promise<UpdateResult> {\r\n    const collection = this.getDatabaseInstance().collection(table);\r\n    const mongoOptions = this.withSession<UpdateOptions>(options);\r\n    const result = await collection.updateMany(\r\n      filter,\r\n      operations as UpdateFilter<Record<string, unknown>>,\r\n      mongoOptions,\r\n    );\r\n\r\n    return { modifiedCount: result.modifiedCount };\r\n  }\r\n\r\n  /**\r\n   * Lazily create (and cache) the Mongo sync adapter.\r\n   * The adapter uses this driver instance to ensure all operations\r\n   * participate in active transactions via the session context.\r\n   */\r\n  public syncAdapter(): SyncAdapterContract {\r\n    if (!this.syncAdapterInstance) {\r\n      this.syncAdapterInstance = new MongoSyncAdapter(this);\r\n    }\r\n\r\n    return this.syncAdapterInstance;\r\n  }\r\n\r\n  /**\r\n   * Lazily create (and cache) the Mongo migration driver.\r\n   * The migration driver handles schema operations like indexes, collections, etc.\r\n   */\r\n  public migrationDriver(): MigrationDriverContract {\r\n    if (!this.migrationDriverInstance) {\r\n      this.migrationDriverInstance = new MongoMigrationDriver(this);\r\n    }\r\n\r\n    return this.migrationDriverInstance!;\r\n  }\r\n\r\n  /**\r\n   * Expose the underlying Mongo client for advanced consumers.\r\n   */\r\n  public getClient<Client = MongoClient>(): Client {\r\n    return this.getClientInstance() as Client;\r\n  }\r\n\r\n  /**\r\n   * Retrieve the active Mongo client, throwing if the driver is disconnected.\r\n   */\r\n  private getClientInstance(): MongoClient {\r\n    if (!this.client) {\r\n      throw new Error(\"Mongo driver is not connected.\");\r\n    }\r\n\r\n    return this.client;\r\n  }\r\n\r\n  /**\r\n   * Retrieve the active Mongo database, throwing if the driver is disconnected.\r\n   * @private\r\n   */\r\n  private getDatabaseInstance(): Db {\r\n    if (!this.database) {\r\n      throw new Error(\"Mongo driver is not connected to a database.\");\r\n    }\r\n\r\n    return this.database;\r\n  }\r\n\r\n  /**\r\n   * Resolve the Mongo connection string based on provided options.\r\n   */\r\n  private resolveUri(): string {\r\n    if (this.config.uri) {\r\n      return this.config.uri;\r\n    }\r\n\r\n    const host = this.config.host ?? \"localhost\";\r\n    const port = this.config.port ?? 27017;\r\n\r\n    return `mongodb://${host}:${port}`;\r\n  }\r\n\r\n  /**\r\n   * Build the Mongo client options derived from the driver configuration.\r\n   */\r\n  private buildClientOptions(): MongoClientOptions {\r\n    const baseOptions: MongoClientOptions = {\r\n      ...(this.config.clientOptions ?? {}),\r\n    };\r\n\r\n    if (this.config.logging) {\r\n      baseOptions.monitorCommands = true;\r\n    }\r\n\r\n    if (this.config.username && !baseOptions.auth) {\r\n      baseOptions.auth = {\r\n        username: this.config.username,\r\n        password: this.config.password,\r\n      };\r\n    }\r\n\r\n    if (this.config.authSource && !baseOptions.authSource) {\r\n      baseOptions.authSource = this.config.authSource;\r\n    }\r\n\r\n    return baseOptions;\r\n  }\r\n\r\n  /**\r\n   * Emit a driver lifecycle event.\r\n   */\r\n  private emit(event: DriverEvent, ...args: unknown[]): void {\r\n    this.events.emit(event, ...args);\r\n  }\r\n\r\n  /**\r\n   * Ensure MongoDB is running as a replica set (required for transactions).\r\n   *\r\n   * @throws {Error} If MongoDB is running as a standalone instance\r\n   */\r\n  private async ensureReplicaSetAvailable(): Promise<void> {\r\n    try {\r\n      const admin = this.database!.admin();\r\n      const status = await admin.serverStatus();\r\n\r\n      if (!status.repl) {\r\n        throw new Error(\r\n          \"MongoDB transactions require a replica set or sharded cluster. \" +\r\n            \"Standalone MongoDB instances do not support transactions.\\n\\n\" +\r\n            \"For local development:\\n\" +\r\n            \"  - Run MongoDB with --replSet flag: mongod --replSet rs0\\n\" +\r\n            \"  - Or use Docker with replica set configuration\\n\" +\r\n            \"  - Or use MongoDB Atlas (cloud) which provides replica sets by default\",\r\n        );\r\n      }\r\n    } catch (error: any) {\r\n      if (error.message?.includes(\"replica set\")) {\r\n        throw error;\r\n      }\r\n      throw new Error(`Failed to check MongoDB replica set status: ${error.message}`);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Attach the active transaction session (when available) to Mongo options.\r\n   */\r\n  private withSession<TOptions extends { session?: ClientSession }>(\r\n    options?: Record<string, unknown>,\r\n  ): TOptions | undefined {\r\n    const session = databaseTransactionContext.getSession<ClientSession>();\r\n\r\n    if (!session) {\r\n      return options as TOptions | undefined;\r\n    }\r\n\r\n    const baseOptions = options ? ({ ...options } as TOptions) : ({} as TOptions);\r\n\r\n    baseOptions.session = session;\r\n\r\n    return baseOptions;\r\n  }\r\n\r\n  // ============================================================\r\n  // SQL Compatibility Operations (Not supported in MongoDB)\r\n  // ============================================================\r\n\r\n  /**\r\n   * Return a SQL serializer for this driver's dialect.\r\n   * Not supported for MongoDB.\r\n   */\r\n  public getSQLSerializer(): SQLSerializer {\r\n    throw new Error(\"MongoDB driver does not support SQL serialization.\");\r\n  }\r\n\r\n  /**\r\n   * Execute a raw SQL query.\r\n   * Not supported for MongoDB.\r\n   */\r\n  public async query<T = unknown>(_sql: string, _params?: unknown[]): Promise<any> {\r\n    throw new Error(\"MongoDB driver does not support raw SQL queries.\");\r\n  }\r\n\r\n  // ============================================================\r\n  // Database Lifecycle Operations\r\n  // ============================================================\r\n\r\n  /**\r\n   * Create a new database.\r\n   *\r\n   * In MongoDB, databases are created automatically when data is first written.\r\n   * This method creates an empty collection to ensure the database exists.\r\n   *\r\n   * @param name - Database name to create\r\n   * @returns true if created, false if already exists\r\n   */\r\n  public async createDatabase(name: string): Promise<boolean> {\r\n    const client = this.getClientInstance();\r\n\r\n    // Check if database already exists\r\n    if (await this.databaseExists(name)) {\r\n      return false;\r\n    }\r\n\r\n    try {\r\n      // MongoDB creates databases on first write, so create a system collection\r\n      const db = client.db(name);\r\n      await db.createCollection(\"__init__\");\r\n      // Drop the temp collection\r\n      await db.collection(\"__init__\").drop();\r\n\r\n      log.success(\"database\", \"lifecycle\", `Created database ${name}`);\r\n      return true;\r\n    } catch (error) {\r\n      log.error(\"database\", \"lifecycle\", `Failed to create database ${name}: ${error}`);\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Drop a database.\r\n   *\r\n   * @param name - Database name to drop\r\n   * @returns true if dropped, false if didn't exist\r\n   */\r\n  public async dropDatabase(name: string): Promise<boolean> {\r\n    const client = this.getClientInstance();\r\n\r\n    // Check if database exists\r\n    if (!(await this.databaseExists(name))) {\r\n      return false;\r\n    }\r\n\r\n    try {\r\n      await client.db(name).dropDatabase();\r\n      log.success(\"database\", \"lifecycle\", `Dropped database ${name}`);\r\n      return true;\r\n    } catch (error) {\r\n      log.error(\"database\", \"lifecycle\", `Failed to drop database ${name}: ${error}`);\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Check if a database exists.\r\n   *\r\n   * @param name - Database name to check\r\n   * @returns true if database exists\r\n   */\r\n  public async databaseExists(name: string): Promise<boolean> {\r\n    const client = this.getClientInstance();\r\n\r\n    const result = await client.db(\"admin\").admin().listDatabases();\r\n    return result.databases.some((db) => db.name === name);\r\n  }\r\n\r\n  /**\r\n   * List all databases.\r\n   *\r\n   * @returns Array of database names\r\n   */\r\n  public async listDatabases(): Promise<string[]> {\r\n    const client = this.getClientInstance();\r\n\r\n    const result = await client.db(\"admin\").admin().listDatabases();\r\n    return result.databases\r\n      .map((db) => db.name)\r\n      .filter((name) => ![\"admin\", \"local\", \"config\"].includes(name));\r\n  }\r\n\r\n  // ============================================================\r\n  // Table/Collection Management Operations\r\n  // ============================================================\r\n\r\n  /**\r\n   * Drop a collection.\r\n   *\r\n   * @param name - Collection name to drop\r\n   * @throws Error if collection doesn't exist\r\n   */\r\n  public async dropTable(name: string): Promise<void> {\r\n    const db = this.getDatabaseInstance();\r\n    await db.collection(name).drop();\r\n    log.success(\"database\", \"collection\", `Dropped collection ${name}`);\r\n  }\r\n\r\n  /**\r\n   * Drop a collection if it exists.\r\n   *\r\n   * @param name - Collection name to drop\r\n   */\r\n  public async dropTableIfExists(name: string): Promise<void> {\r\n    if (await this.blueprint.tableExists(name)) {\r\n      await this.dropTable(name);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Drop all collections in the current database.\r\n   *\r\n   * Useful for `migrate:fresh` command.\r\n   */\r\n  public async dropAllTables(): Promise<void> {\r\n    const collections = await this.blueprint.listTables();\r\n\r\n    if (collections.length === 0) {\r\n      return;\r\n    }\r\n\r\n    const db = this.getDatabaseInstance();\r\n\r\n    for (const collection of collections) {\r\n      await db.collection(collection).drop();\r\n    }\r\n\r\n    log.success(\"database\", \"collection\", `Dropped ${collections.length} collections`);\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;AA+CA,MAAM,8BAAkD;CACtD,gBAAgB;CAChB,aAAa,EAAE,OAAO,QAAQ;CAC9B,cAAc,EAAE,GAAG,WAAW;AAChC;;;;AASA,IAAI;AAEJ,IAAI;AAEJ,IAAI,iBAAiC;AAErC,IAAI;;;;AAKJ,MAAM,+BAA+B;;;;;;;;;;EAUnC,KAAK;;;;AAKP,eAAe,cAAc;CAC3B,IAAI;EACF,iBAAiB,OAAO;EACxB,gBAAgB,MAAM;EACtB,WAAW,cAAc;EACzB,iBAAiB;CACnB,QAAQ;EACN,iBAAiB;CACnB;AACF;AAEA,YAAY;AAEZ,SAAgB,wBAAwB;CACtC,OAAO;AACT;AAEA,eAAe,uBAAuB;CACpC,IAAI,mBAAmB,OACrB,MAAM,IAAI,MAAM,4BAA4B;CAG9C,IAAI,mBAAmB,MAAM;EAC3B,MAAM;EAEN,OAAO,MAAM,qBAAqB;CACpC;AACF;;;;;;;AAQA,IAAa,gBAAb,MAAqD;CAyDhC;CAWA;CAnEnB,AAAiB,SAAS,IAAI,aAAa;CAC3C,AAAO;CACP,AAAO;CACP,AAAQ,YAAY;CACpB,AAAQ;CACR,AAAQ;CACR,AAAiB;CACjB,AAAQ;CACR,AAAQ;CAER,IAAW,YAAqC;EAC9C,IAAI,CAAC,KAAK,YACR,KAAK,aAAa,IAAI,iBAAiB,KAAK,QAAS;EAGvD,OAAO,KAAK;CACd;;;;CAKA,AAAgB,OAAO;;;;CAKvB,AAAU;;;;;;;;;;CAWV,AAAgB,gBAAwC;EACtD,kBAAkB;EAClB,iBAAiB;EACjB,iBAAiB;EACjB,iBAAiB;EACjB,YAAY;EACZ,gBAAgB;EAChB,YAAY;EACZ,gBAAgB;EAChB,aAAa,UAAU,GAAG,MAAM;CAClC;;;;;;;CAQA,AAAO,YACL,AAAiB,QAWjB,AAAiB,eACjB;EAZiB;EAWA;EAEjB,KAAK,qBAAqB;GACxB,GAAG;GACH,GAAG,eAAe;EACpB;CACF;;;;CAKA,IAAW,eAAmC;EAC5C,IAAI,CAAC,KAAK,eACR,KAAK,oBAAoB;EAG3B,OAAO,KAAK;CACd;;;;CAKA,AAAQ,sBAAsB;EAC5B,IAAI,KAAK,OAAO,UACd,KAAK,gBAAgB,KAAK,OAAO;OAC5B,IAAI,KAAK,OAAO,KACrB,KAAK,gBAAgB,KAAK,OAAO,IAAI,MAAM,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI;CAExE;;;;CAKA,IAAW,cAAuB;EAChC,OAAO,KAAK;CACd;;;;;;;;;;;;;CAcA,AAAO,cAAkB;EACvB,IAAI,CAAC,KAAK,UACR,MAAM,IAAI,MACR,uFACF;EAEF,OAAO,KAAK;CACd;;;;;;;;;;;;;;;;CAiBA,AAAO,iBAAkD;EAEvD,IAAI,KAAK,eAAe,mBAAmB,OACzC;EAIF,IAAI,CAAC,KAAK,qBACR,KAAK,sBAAsB,IAAI,iBAAiB,MAAM,KAAK,eAAe,iBAAiB;EAG7F,OAAO,KAAK;CACd;;;;;CAMA,MAAa,UAAyB;EACpC,IAAI,KAAK,WACP;EAGF,MAAM,qBAAqB;EAE3B,MAAM,MAAM,KAAK,WAAW;EAE5B,MAAM,EAAE,aAAa,UAAU,oBAAoB;EAEnD,WAAW;EAEX,MAAM,SAAS,IAAI,YAAY,KAAK,KAAK,mBAAmB,CAAC;EAE7D,IAAI;GACF,IAAI,KACF,oBACA,cACA,0BAA0B,OAAO,KAAK,OAAO,aAAa,KAAK,YAAY,CAAC,GAC9E;GACA,MAAM,OAAO,QAAQ;GACrB,KAAK,SAAS;GACd,KAAK,WAAW,OAAO,GAAG,KAAK,YAAY;GAE3C,KAAK,YAAY;GACjB,IAAI,QAAQ,oBAAoB,cAAc,uBAAuB;GAErE,OAAO,GAAG,eAAe;IACvB,IAAI,KAAK,WAAW;KAClB,KAAK,YAAY;KACjB,KAAK,KAAK,cAAc;KACxB,IAAI,KAAK,oBAAoB,cAAc,4BAA4B;IACzE;GACF,CAAC;GAED,IAAI,KAAK,OAAO,SAAS;IACvB,MAAM,kBAAkB;KAAC;KAAY;KAAS;KAAQ;KAAa;IAAc;IAEjF,OAAO,GAAG,mBAAmB,UAAe;KAC1C,IAAI,gBAAgB,SAAS,MAAM,WAAW,GAAG;KAEjD,IAAI,SAAS,KAAK,UAAU,MAAM,OAAO;KACzC,IAAI,OAAO,SAAS,KAClB,SAAS,OAAO,UAAU,GAAG,GAAG,IAAI;KAGtC,IAAI,KAAK;MACP,QAAQ;MACR,QAAQ;MACR,SAAS,IAAI,MAAM,YAAY,IAAI;MACnC,SAAS,EAAE,SAAS,MAAM,QAAQ;KACpC,CAAC;IACH,CAAC;IAED,OAAO,GAAG,qBAAqB,UAAe;KAC5C,IAAI,gBAAgB,SAAS,MAAM,WAAW,GAAG;KAEjD,IAAI,QAAQ;MACV,QAAQ;MACR,QAAQ;MACR,SAAS,IAAI,MAAM,SAAS,QAAQ,CAAC,EAAE,OAAO,MAAM,YAAY;KAClE,CAAC;IACH,CAAC;IAED,OAAO,GAAG,kBAAkB,UAAe;KACzC,IAAI,gBAAgB,SAAS,MAAM,WAAW,GAAG;KAEjD,IAAI,MAAM;MACR,QAAQ;MACR,QAAQ;MACR,SAAS,IAAI,MAAM,SAAS,QAAQ,CAAC,EAAE,OAAO,MAAM,YAAY;MAChE,SAAS,EAAE,SAAS,MAAM,QAAQ;KACpC,CAAC;IACH,CAAC;GACH;GAEA,KAAK,KAAK,WAAW;EACvB,SAAS,OAAY;GACnB,MAAM,OAAO,MAAM,EAAE,YAAY,MAAS;GAC1C,KAAK,KAAK,cAAc;GACxB,IAAI,MACF,oBACA,cACA,kCAAkC,MAAM,SAC1C;GACA,MAAM;EACR;CACF;;;;CAKA,MAAa,aAA4B;EACvC,IAAI,CAAC,KAAK,QACR;EAGF,IAAI;GACF,MAAM,KAAK,OAAO,MAAM;EAC1B,UAAU;GACR,KAAK,YAAY;GACjB,KAAK,KAAK,cAAc;EAC1B;CACF;;;;CAKA,AAAO,GAAG,OAAoB,UAAqC;EACjE,KAAK,OAAO,GAAG,OAAO,QAAQ;CAChC;;;;CAKA,MAAa,OACX,OACA,UACA,SACuB;EACvB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA8B,OAAO;EAC/D,MAAM,SAAS,MAAM,WAAW,UAAU,UAAU,YAAY;EAEhE,OAAO,EACL,UAAU;GACR,GAAG;GACH,KAAK,OAAO;EACd,EACF;CACF;;;;CAKA,MAAa,WACX,OACA,WACA,SACyB;EACzB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA8B,OAAO;EAC/D,MAAM,SAAoD,MAAM,WAAW,WACzE,WACA,YACF;EAEA,OAAO,UAAU,KAAK,UAAU,UAAU;GACxC,MAAM,aAAa,OAAO,YAAY;GAEtC,OAAO,EACL,UAAU;IACR,GAAG;IACH,KAAK;GACP,EACF;EACF,CAAC;CACH;;;;CAKA,MAAa,OACX,OACA,QACA,QACA,SACuB;EACvB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA2B,OAAO;EAO5D,OAAO,EAAE,gBAAe,MANH,WAAW,UAC9B,QACA,QACA,YACF,GAE+B,cAAc;CAC/C;;;;CAKA,MAAa,QACX,OACA,QACA,UACA,SACmB;EAInB,QAAO,MAHY,KAAK,oBAAoB,EAAE,WAAW,KAC3B,EAAE,kBAAkB,QAAQ,QAAmC,IAE9E;CACjB;;;;CAKA,MAAa,iBACX,OACA,QACA,QACA,SACmB;EACnB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAAqC,OAAO;EAMtE,OAAO,MALc,WAAW,iBAAiB,QAAQ,QAAmC;GAC1F,gBAAgB;GAChB,GAAG;EACL,CAAC;CAGH;;;;;;;;;;;;CAaA,MAAa,OACX,OACA,QACA,UACA,SACY;EACZ,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAAqC,OAAO;EAGtE,MAAM,SAAS,EAAE,MAAM,SAAS;EAQhC,OAAO,MANc,WAAW,iBAAiB,QAAQ,QAAQ;GAC/D,QAAQ;GACR,gBAAgB;GAChB,GAAG;EACL,CAAC;CAGH;;;;;;;;;CAUA,MAAa,iBACX,OACA,QACA,SACmB;EACnB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAAqC,OAAO;EAItE,OAAO,MAFc,WAAW,iBAAiB,QAAQ,gBAAgB,CAAC,CAAC;CAG7E;;;;CAKA,MAAa,WACX,OACA,QACA,QACA,SACuB;EACvB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA2B,OAAO;EAO5D,OAAO,EAAE,gBAAe,MANH,WAAW,WAC9B,QACA,QACA,YACF,GAE+B,cAAc;CAC/C;;;;CAKA,MAAa,OACX,OACA,SAAkC,CAAC,GACnC,SACiB;EACjB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA2B,OAAO;EAG5D,QAAO,MAFc,WAAW,UAAU,QAAQ,YAAY,GAEhD,eAAe,IAAI,IAAI;CACvC;;;;CAKA,MAAa,WACX,OACA,SAAkC,CAAC,GACnC,SACiB;EACjB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA2B,OAAO;EAI5D,QAAO,MAFc,WAAW,WAAW,QAAQ,YAAY,GAEjD,gBAAgB;CAChC;;;;;;;;CASA,MAAa,cAAc,OAAe,SAAoD;EAC5F,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA2B,OAAO;EAG5D,QAAO,MAFc,WAAW,WAAW,CAAC,GAAG,YAAY,GAE7C,gBAAgB;CAChC;;;;CAKA,AAAO,UAAU,MAAwD;EACvE,MAAM,aAAsC,CAAC;EAE7C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,GAAG;GAC/C,IAAI,UAAU,QACZ;GAGF,IAAI,iBAAiB,UACnB,WAAW,OAAO,MAAM,SAAS;QAC5B,IAAI,iBAAiB,MAC1B,WAAW,OAAO,MAAM,YAAY;QAC/B,IAAI,OAAO,UAAU,UAC1B,WAAW,OAAO,MAAM,SAAS;QAC5B,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK,GAE5E,WAAW,OAAO;QAElB,WAAW,OAAO;EAEtB;EAEA,OAAO;CACT;;;;CAKA,AAAO,gBAAgB,MAAqD;EAC1E,OAAO,IAAI,qBAAqB,IAAI;CACtC;;;;CAKA,AAAO,YAAY,MAAwD;EACzE,IAAI,KAAK,OAAO,OAAO,KAAK,QAAQ,UAClC,KAAK,MAAM,IAAI,SAAS,KAAK,GAAG;EAGlC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,GAE5C,IAAI,OAAO,UAAU,YAAY,iBAAiB,KAAK,GACrD,KAAK,OAAO,IAAI,KAAK,KAAK;EAI9B,OAAO;CACT;;;;CAKA,AAAO,aAA0B,OAAwC;EACvE,OAAO,IAAI,kBAAkB,OAAO,mBAAmB,IAAI,CAAC;CAC9D;;;;CAKA,MAAa,mBAAsE;EAEjF,MAAM,UADS,KAAK,kBACC,EAAE,aAAa;EAEpC,MAAM,QAAQ,iBAAiB,KAAK,kBAAkB;EACtD,2BAA2B,MAAM,EAAE,QAAQ,CAAC;EAC5C,IAAI,WAAW;EAEf,MAAM,WAAW,OAAO,cAAkD;GACxE,IAAI,UAAU;GAEd,IAAI;IACF,MAAM,UAAU;GAClB,UAAU;IACR,WAAW;IACX,2BAA2B,KAAK;IAChC,MAAM,QAAQ,WAAW,EAAE,YAAY,MAAS;GAClD;EACF;EAEA,OAAO;GACL,SAAS;GACT,QAAQ,YAAY;IAClB,MAAM,SAAS,YAAY;KACzB,IAAI;MACF,MAAM,QAAQ,kBAAkB;KAClC,SAAS,OAAO;MACd,MAAM,QAAQ,iBAAiB,EAAE,YAAY,MAAS;MACtD,MAAM;KACR;IACF,CAAC;GACH;GACA,UAAU,YAAY;IACpB,MAAM,SAAS,YAAY;KACzB,MAAM,QAAQ,iBAAiB;IACjC,CAAC;GACH;EACF;CACF;;;;;;;;;;;;;;;;CAiBA,MAAa,YACX,IACA,SACY;EAEZ,IAAI,2BAA2B,qBAAqB,GAClD,MAAM,IAAI,MACR,yHAEF;EAIF,MAAM,KAAK,0BAA0B;EAGrC,MAAM,UADS,KAAK,kBACC,EAAE,aAAa;EAEpC,IAAI;GACF,MAAM,QAAQ,iBAAiB;IAC7B,GAAG,KAAK;IACR,GAAI;GACN,CAAC;GAGD,2BAA2B,MAAM,EAAE,QAAQ,CAAC;GAE5C,IAAI;IASF,MAAM,SAAS,MAAM,GAAG,EANtB,SAAS,QAAwB;KAC/B,MAAM,IAAI,yBAAyB,MAAM;IAC3C,EAIwB,CAAC;IAG3B,MAAM,QAAQ,kBAAkB;IAEhC,OAAO;GACT,SAAS,OAAO;IAEd,MAAM,QAAQ,iBAAiB,EAAE,YAAY,MAAS;IACtD,MAAM;GACR,UAAU;IAER,2BAA2B,KAAK;GAClC;EACF,UAAU;GAER,MAAM,QAAQ,WAAW,EAAE,YAAY,MAAS;EAClD;CACF;;;;;;CAOA,MAAa,OACX,OACA,QACA,YACA,SACuB;EACvB,MAAM,aAAa,KAAK,oBAAoB,EAAE,WAAW,KAAK;EAC9D,MAAM,eAAe,KAAK,YAA2B,OAAO;EAO5D,OAAO,EAAE,gBAAe,MANH,WAAW,WAC9B,QACA,YACA,YACF,GAE+B,cAAc;CAC/C;;;;;;CAOA,AAAO,cAAmC;EACxC,IAAI,CAAC,KAAK,qBACR,KAAK,sBAAsB,IAAI,iBAAiB,IAAI;EAGtD,OAAO,KAAK;CACd;;;;;CAMA,AAAO,kBAA2C;EAChD,IAAI,CAAC,KAAK,yBACR,KAAK,0BAA0B,IAAI,qBAAqB,IAAI;EAG9D,OAAO,KAAK;CACd;;;;CAKA,AAAO,YAA0C;EAC/C,OAAO,KAAK,kBAAkB;CAChC;;;;CAKA,AAAQ,oBAAiC;EACvC,IAAI,CAAC,KAAK,QACR,MAAM,IAAI,MAAM,gCAAgC;EAGlD,OAAO,KAAK;CACd;;;;;CAMA,AAAQ,sBAA0B;EAChC,IAAI,CAAC,KAAK,UACR,MAAM,IAAI,MAAM,8CAA8C;EAGhE,OAAO,KAAK;CACd;;;;CAKA,AAAQ,aAAqB;EAC3B,IAAI,KAAK,OAAO,KACd,OAAO,KAAK,OAAO;EAMrB,OAAO,aAHM,KAAK,OAAO,QAAQ,YAGR,GAFZ,KAAK,OAAO,QAAQ;CAGnC;;;;CAKA,AAAQ,qBAAyC;EAC/C,MAAM,cAAkC,EACtC,GAAI,KAAK,OAAO,iBAAiB,CAAC,EACpC;EAEA,IAAI,KAAK,OAAO,SACd,YAAY,kBAAkB;EAGhC,IAAI,KAAK,OAAO,YAAY,CAAC,YAAY,MACvC,YAAY,OAAO;GACjB,UAAU,KAAK,OAAO;GACtB,UAAU,KAAK,OAAO;EACxB;EAGF,IAAI,KAAK,OAAO,cAAc,CAAC,YAAY,YACzC,YAAY,aAAa,KAAK,OAAO;EAGvC,OAAO;CACT;;;;CAKA,AAAQ,KAAK,OAAoB,GAAG,MAAuB;EACzD,KAAK,OAAO,KAAK,OAAO,GAAG,IAAI;CACjC;;;;;;CAOA,MAAc,4BAA2C;EACvD,IAAI;GAIF,IAAI,EAAC,MAHS,KAAK,SAAU,MACJ,EAAE,aAAa,GAE5B,MACV,MAAM,IAAI,MACR,0UAMF;EAEJ,SAAS,OAAY;GACnB,IAAI,MAAM,SAAS,SAAS,aAAa,GACvC,MAAM;GAER,MAAM,IAAI,MAAM,+CAA+C,MAAM,SAAS;EAChF;CACF;;;;CAKA,AAAQ,YACN,SACsB;EACtB,MAAM,UAAU,2BAA2B,WAA0B;EAErE,IAAI,CAAC,SACH,OAAO;EAGT,MAAM,cAAc,UAAW,EAAE,GAAG,QAAQ,IAAkB,CAAC;EAE/D,YAAY,UAAU;EAEtB,OAAO;CACT;;;;;CAUA,AAAO,mBAAkC;EACvC,MAAM,IAAI,MAAM,oDAAoD;CACtE;;;;;CAMA,MAAa,MAAmB,MAAc,SAAmC;EAC/E,MAAM,IAAI,MAAM,kDAAkD;CACpE;;;;;;;;;;CAeA,MAAa,eAAe,MAAgC;EAC1D,MAAM,SAAS,KAAK,kBAAkB;EAGtC,IAAI,MAAM,KAAK,eAAe,IAAI,GAChC,OAAO;EAGT,IAAI;GAEF,MAAM,KAAK,OAAO,GAAG,IAAI;GACzB,MAAM,GAAG,iBAAiB,UAAU;GAEpC,MAAM,GAAG,WAAW,UAAU,EAAE,KAAK;GAErC,IAAI,QAAQ,YAAY,aAAa,oBAAoB,MAAM;GAC/D,OAAO;EACT,SAAS,OAAO;GACd,IAAI,MAAM,YAAY,aAAa,6BAA6B,KAAK,IAAI,OAAO;GAChF,MAAM;EACR;CACF;;;;;;;CAQA,MAAa,aAAa,MAAgC;EACxD,MAAM,SAAS,KAAK,kBAAkB;EAGtC,IAAI,CAAE,MAAM,KAAK,eAAe,IAAI,GAClC,OAAO;EAGT,IAAI;GACF,MAAM,OAAO,GAAG,IAAI,EAAE,aAAa;GACnC,IAAI,QAAQ,YAAY,aAAa,oBAAoB,MAAM;GAC/D,OAAO;EACT,SAAS,OAAO;GACd,IAAI,MAAM,YAAY,aAAa,2BAA2B,KAAK,IAAI,OAAO;GAC9E,MAAM;EACR;CACF;;;;;;;CAQA,MAAa,eAAe,MAAgC;EAI1D,QAAO,MAHQ,KAAK,kBAEM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,cAAc,GAChD,UAAU,MAAM,OAAO,GAAG,SAAS,IAAI;CACvD;;;;;;CAOA,MAAa,gBAAmC;EAI9C,QAAO,MAHQ,KAAK,kBAEM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,cAAc,GAChD,UACX,KAAK,OAAO,GAAG,IAAI,EACnB,QAAQ,SAAS,CAAC;GAAC;GAAS;GAAS;EAAQ,EAAE,SAAS,IAAI,CAAC;CAClE;;;;;;;CAYA,MAAa,UAAU,MAA6B;EAElD,MADW,KAAK,oBACT,EAAE,WAAW,IAAI,EAAE,KAAK;EAC/B,IAAI,QAAQ,YAAY,cAAc,sBAAsB,MAAM;CACpE;;;;;;CAOA,MAAa,kBAAkB,MAA6B;EAC1D,IAAI,MAAM,KAAK,UAAU,YAAY,IAAI,GACvC,MAAM,KAAK,UAAU,IAAI;CAE7B;;;;;;CAOA,MAAa,gBAA+B;EAC1C,MAAM,cAAc,MAAM,KAAK,UAAU,WAAW;EAEpD,IAAI,YAAY,WAAW,GACzB;EAGF,MAAM,KAAK,KAAK,oBAAoB;EAEpC,KAAK,MAAM,cAAc,aACvB,MAAM,GAAG,WAAW,UAAU,EAAE,KAAK;EAGvC,IAAI,QAAQ,YAAY,cAAc,WAAW,YAAY,OAAO,aAAa;CACnF;AACF"}

package/esm/drivers/mongodb/mongodb-id-generator.d.mts

@@ -0,0 +1,120 @@
+import { GenerateIdOptions, IdGeneratorContract } from "../../contracts/database-id-generator.contract.mjs";
+import { MongoDbDriver } from "./mongodb-driver.mjs";
+
+//#region ../../@warlock.js/cascade/src/drivers/mongodb/mongodb-id-generator.d.ts
+/**
+ * MongoDB-specific ID generator for auto-incrementing integer IDs.
+ *
+ * Maintains a separate collection that tracks the last generated ID for each table.
+ * Generates auto-incrementing IDs similar to SQL's AUTO_INCREMENT feature.
+ *
+ * **Collection Structure:**
+ * ```json
+ * {
+ *   "collection": "users",
+ *   "id": 12345
+ * }
+ * ```
+ *
+ * **Features:**
+ * - Atomic ID generation using findOneAndUpdate with aggregation pipeline
+ * - Automatic transaction support (driver handles session context)
+ * - Configurable initial ID and increment values
+ * - Thread-safe and concurrent-safe
+ *
+ * @example
+ * ```typescript
+ * const mongoDriver = new MongoDbDriver(config);
+ * const idGenerator = new MongoIdGenerator(mongoDriver);
+ *
+ * const dataSource = new DataSource({
+ *   name: "primary",
+ *   driver: mongoDriver,
+ *   idGenerator,
+ * });
+ *
+ * // Generate IDs with custom configuration
+ * const id = await idGenerator.generateNextId({
+ *   table: "users",
+ *   initialId: 1000,
+ *   incrementIdBy: 1
+ * });
+ * ```
+ */
+declare class MongoIdGenerator implements IdGeneratorContract {
+  private readonly driver;
+  /**
+   * The collection name that stores ID counters.
+   * Each document tracks the last ID for a specific table.
+   *
+   * Named "MasterMind" for backward compatibility with legacy Cascade.
+   */
+  readonly counterCollection: string;
+  /**
+   * Create a new MongoDB ID generator instance.
+   *
+   * @param driver - The MongoDB driver instance
+   * @param counterCollection - Name of the collection storing ID counters (default: "MasterMind")
+   *
+   * @example
+   * ```typescript
+   * const idGenerator = new MongoIdGenerator(mongoDriver, "id_counters");
+   * ```
+   */
+  constructor(driver: MongoDbDriver, counterCollection?: string);
+  /**
+   * Generate the next ID for a table.
+   *
+   * Uses atomic findOneAndUpdate with aggregation pipeline to ensure uniqueness
+   * even in concurrent scenarios. Automatically participates in active transactions.
+   *
+   * @param options - Configuration for ID generation
+   * @returns The generated ID
+   *
+   * @example
+   * ```typescript
+   * // Simple usage
+   * const id = await idGenerator.generateNextId({ table: "users" });
+   *
+   * // With custom initial ID
+   * const id = await idGenerator.generateNextId({
+   *   table: "products",
+   *   initialId: 1000,
+   *   incrementIdBy: 1
+   * });
+   * ```
+   */
+  generateNextId(options: GenerateIdOptions): Promise<number>;
+  /**
+   * Get the last generated ID for a table.
+   *
+   * @param table - The table/collection name
+   * @returns The last generated ID, or 0 if none exists
+   *
+   * @example
+   * ```typescript
+   * const lastId = await idGenerator.getLastId("users");
+   * console.log(`Last user ID: ${lastId}`);
+   * ```
+   */
+  getLastId(table: string): Promise<number>;
+  /**
+   * Set the last ID for a table.
+   *
+   * Creates or updates the counter document for the specified table.
+   * Useful for seeding or resetting ID sequences.
+   *
+   * @param table - The table/collection name
+   * @param id - The ID to set as the last generated ID
+   *
+   * @example
+   * ```typescript
+   * // Reset user IDs to start from 1000
+   * await idGenerator.setLastId("users", 1000);
+   * ```
+   */
+  setLastId(table: string, id: number): Promise<void>;
+}
+//#endregion
+export { MongoIdGenerator };
+//# sourceMappingURL=mongodb-id-generator.d.mts.map

package/esm/drivers/mongodb/mongodb-id-generator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb-id-generator.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/mongodb/mongodb-id-generator.ts"],"mappings":";;;;;;;AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsH4D;;;;;;cAtH/C,gBAAA,YAA4B,mBAAA;EAAA,iBAqBpB,MAAA;;;;;;;WAdH,iBAAA;;;;;;;;;;;;cAcG,MAAA,EAAQ,aAAA,EACzB,iBAAA;;;;;;;;;;;;;;;;;;;;;;;EA6BW,cAAA,CAAe,OAAA,EAAS,iBAAA,GAAoB,OAAA;;;;;;;;;;;;;EA8C5C,SAAA,CAAU,KAAA,WAAgB,OAAA;;;;;;;;;;;;;;;;EAqB1B,SAAA,CAAU,KAAA,UAAe,EAAA,WAAa,OAAA;AAAA"}

package/esm/drivers/mongodb/mongodb-id-generator.mjs

@@ -0,0 +1,141 @@
+//#region ../../@warlock.js/cascade/src/drivers/mongodb/mongodb-id-generator.ts
+/**
+* MongoDB-specific ID generator for auto-incrementing integer IDs.
+*
+* Maintains a separate collection that tracks the last generated ID for each table.
+* Generates auto-incrementing IDs similar to SQL's AUTO_INCREMENT feature.
+*
+* **Collection Structure:**
+* ```json
+* {
+*   "collection": "users",
+*   "id": 12345
+* }
+* ```
+*
+* **Features:**
+* - Atomic ID generation using findOneAndUpdate with aggregation pipeline
+* - Automatic transaction support (driver handles session context)
+* - Configurable initial ID and increment values
+* - Thread-safe and concurrent-safe
+*
+* @example
+* ```typescript
+* const mongoDriver = new MongoDbDriver(config);
+* const idGenerator = new MongoIdGenerator(mongoDriver);
+*
+* const dataSource = new DataSource({
+*   name: "primary",
+*   driver: mongoDriver,
+*   idGenerator,
+* });
+*
+* // Generate IDs with custom configuration
+* const id = await idGenerator.generateNextId({
+*   table: "users",
+*   initialId: 1000,
+*   incrementIdBy: 1
+* });
+* ```
+*/
+var MongoIdGenerator = class {
+	driver;
+	/**
+	* The collection name that stores ID counters.
+	* Each document tracks the last ID for a specific table.
+	*
+	* Named "MasterMind" for backward compatibility with legacy Cascade.
+	*/
+	counterCollection = "MasterMind";
+	/**
+	* Create a new MongoDB ID generator instance.
+	*
+	* @param driver - The MongoDB driver instance
+	* @param counterCollection - Name of the collection storing ID counters (default: "MasterMind")
+	*
+	* @example
+	* ```typescript
+	* const idGenerator = new MongoIdGenerator(mongoDriver, "id_counters");
+	* ```
+	*/
+	constructor(driver, counterCollection) {
+		this.driver = driver;
+		if (counterCollection) this.counterCollection = counterCollection;
+	}
+	/**
+	* Generate the next ID for a table.
+	*
+	* Uses atomic findOneAndUpdate with aggregation pipeline to ensure uniqueness
+	* even in concurrent scenarios. Automatically participates in active transactions.
+	*
+	* @param options - Configuration for ID generation
+	* @returns The generated ID
+	*
+	* @example
+	* ```typescript
+	* // Simple usage
+	* const id = await idGenerator.generateNextId({ table: "users" });
+	*
+	* // With custom initial ID
+	* const id = await idGenerator.generateNextId({
+	*   table: "products",
+	*   initialId: 1000,
+	*   incrementIdBy: 1
+	* });
+	* ```
+	*/
+	async generateNextId(options) {
+		const { table, initialId = 1, incrementIdBy = 1 } = options;
+		return (await this.driver.getDatabase().collection(this.counterCollection).findOneAndUpdate({ collection: table }, [{ $set: {
+			id: { $cond: {
+				if: { $or: [{ $eq: ["$id", null] }, { $not: "$id" }] },
+				then: initialId,
+				else: { $add: ["$id", incrementIdBy] }
+			} },
+			collection: table
+		} }], {
+			upsert: true,
+			returnDocument: "after"
+		}))?.id ?? initialId;
+	}
+	/**
+	* Get the last generated ID for a table.
+	*
+	* @param table - The table/collection name
+	* @returns The last generated ID, or 0 if none exists
+	*
+	* @example
+	* ```typescript
+	* const lastId = await idGenerator.getLastId("users");
+	* console.log(`Last user ID: ${lastId}`);
+	* ```
+	*/
+	async getLastId(table) {
+		return (await this.driver.queryBuilder(this.counterCollection).where("collection", table).first())?.id ?? 0;
+	}
+	/**
+	* Set the last ID for a table.
+	*
+	* Creates or updates the counter document for the specified table.
+	* Useful for seeding or resetting ID sequences.
+	*
+	* @param table - The table/collection name
+	* @param id - The ID to set as the last generated ID
+	*
+	* @example
+	* ```typescript
+	* // Reset user IDs to start from 1000
+	* await idGenerator.setLastId("users", 1000);
+	* ```
+	*/
+	async setLastId(table, id) {
+		await this.driver.update(this.counterCollection, { collection: table }, { $set: {
+			id,
+			collection: table
+		} }, { upsert: true });
+	}
+};
+
+//#endregion
+export { MongoIdGenerator };
+//# sourceMappingURL=mongodb-id-generator.mjs.map

package/esm/drivers/mongodb/mongodb-id-generator.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb-id-generator.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/mongodb/mongodb-id-generator.ts"],"sourcesContent":["import type { GenerateIdOptions, IdGeneratorContract } from \"../../contracts\";\nimport type { MongoDbDriver } from \"./mongodb-driver\";\n\n/**\n * MongoDB-specific ID generator for auto-incrementing integer IDs.\n *\n * Maintains a separate collection that tracks the last generated ID for each table.\n * Generates auto-incrementing IDs similar to SQL's AUTO_INCREMENT feature.\n *\n * **Collection Structure:**\n * ```json\n * {\n *   \"collection\": \"users\",\n *   \"id\": 12345\n * }\n * ```\n *\n * **Features:**\n * - Atomic ID generation using findOneAndUpdate with aggregation pipeline\n * - Automatic transaction support (driver handles session context)\n * - Configurable initial ID and increment values\n * - Thread-safe and concurrent-safe\n *\n * @example\n * ```typescript\n * const mongoDriver = new MongoDbDriver(config);\n * const idGenerator = new MongoIdGenerator(mongoDriver);\n *\n * const dataSource = new DataSource({\n *   name: \"primary\",\n *   driver: mongoDriver,\n *   idGenerator,\n * });\n *\n * // Generate IDs with custom configuration\n * const id = await idGenerator.generateNextId({\n *   table: \"users\",\n *   initialId: 1000,\n *   incrementIdBy: 1\n * });\n * ```\n */\nexport class MongoIdGenerator implements IdGeneratorContract {\n  /**\n   * The collection name that stores ID counters.\n   * Each document tracks the last ID for a specific table.\n   *\n   * Named \"MasterMind\" for backward compatibility with legacy Cascade.\n   */\n  public readonly counterCollection: string = \"MasterMind\";\n\n  /**\n   * Create a new MongoDB ID generator instance.\n   *\n   * @param driver - The MongoDB driver instance\n   * @param counterCollection - Name of the collection storing ID counters (default: \"MasterMind\")\n   *\n   * @example\n   * ```typescript\n   * const idGenerator = new MongoIdGenerator(mongoDriver, \"id_counters\");\n   * ```\n   */\n  public constructor(\n    private readonly driver: MongoDbDriver,\n    counterCollection?: string,\n  ) {\n    if (counterCollection) {\n      this.counterCollection = counterCollection;\n    }\n  }\n\n  /**\n   * Generate the next ID for a table.\n   *\n   * Uses atomic findOneAndUpdate with aggregation pipeline to ensure uniqueness\n   * even in concurrent scenarios. Automatically participates in active transactions.\n   *\n   * @param options - Configuration for ID generation\n   * @returns The generated ID\n   *\n   * @example\n   * ```typescript\n   * // Simple usage\n   * const id = await idGenerator.generateNextId({ table: \"users\" });\n   *\n   * // With custom initial ID\n   * const id = await idGenerator.generateNextId({\n   *   table: \"products\",\n   *   initialId: 1000,\n   *   incrementIdBy: 1\n   * });\n   * ```\n   */\n  public async generateNextId(options: GenerateIdOptions): Promise<number> {\n    const { table, initialId = 1, incrementIdBy = 1 } = options;\n\n    // Get the MongoDB database instance\n    const database = this.driver.getDatabase();\n    const collection = database.collection(this.counterCollection);\n\n    // Use atomic findOneAndUpdate with aggregation pipeline\n    // The driver's withSession method will automatically attach the session if in a transaction\n    const result = await collection.findOneAndUpdate(\n      { collection: table },\n      [\n        {\n          $set: {\n            id: {\n              $cond: {\n                if: { $or: [{ $eq: [\"$id\", null] }, { $not: \"$id\" }] },\n                then: initialId,\n                else: { $add: [\"$id\", incrementIdBy] },\n              },\n            },\n            collection: table,\n          },\n        },\n      ],\n      {\n        upsert: true,\n        returnDocument: \"after\",\n      },\n    );\n\n    return result?.id ?? initialId;\n  }\n\n  /**\n   * Get the last generated ID for a table.\n   *\n   * @param table - The table/collection name\n   * @returns The last generated ID, or 0 if none exists\n   *\n   * @example\n   * ```typescript\n   * const lastId = await idGenerator.getLastId(\"users\");\n   * console.log(`Last user ID: ${lastId}`);\n   * ```\n   */\n  public async getLastId(table: string): Promise<number> {\n    const query = this.driver.queryBuilder(this.counterCollection);\n    const doc = (await query.where(\"collection\", table).first()) as Record<string, unknown> | null;\n    return (doc?.id as number) ?? 0;\n  }\n\n  /**\n   * Set the last ID for a table.\n   *\n   * Creates or updates the counter document for the specified table.\n   * Useful for seeding or resetting ID sequences.\n   *\n   * @param table - The table/collection name\n   * @param id - The ID to set as the last generated ID\n   *\n   * @example\n   * ```typescript\n   * // Reset user IDs to start from 1000\n   * await idGenerator.setLastId(\"users\", 1000);\n   * ```\n   */\n  public async setLastId(table: string, id: number): Promise<void> {\n    await this.driver.update(\n      this.counterCollection,\n      { collection: table },\n      { $set: { id, collection: table } },\n      { upsert: true },\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,IAAa,mBAAb,MAA6D;CAqBxC;;;;;;;CAdnB,AAAgB,oBAA4B;;;;;;;;;;;;CAa5C,AAAO,YACL,AAAiB,QACjB,mBACA;EAFiB;EAGjB,IAAI,mBACF,KAAK,oBAAoB;CAE7B;;;;;;;;;;;;;;;;;;;;;;;CAwBA,MAAa,eAAe,SAA6C;EACvE,MAAM,EAAE,OAAO,YAAY,GAAG,gBAAgB,MAAM;EA8BpD,QAAO,MA3BU,KAAK,OAAO,YACH,EAAE,WAAW,KAAK,iBAId,EAAE,iBAC9B,EAAE,YAAY,MAAM,GACpB,CACE,EACE,MAAM;GACJ,IAAI,EACF,OAAO;IACL,IAAI,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,EAAE;IACrD,MAAM;IACN,MAAM,EAAE,MAAM,CAAC,OAAO,aAAa,EAAE;GACvC,EACF;GACA,YAAY;EACd,EACF,CACF,GACA;GACE,QAAQ;GACR,gBAAgB;EAClB,CACF,IAEe,MAAM;CACvB;;;;;;;;;;;;;CAcA,MAAa,UAAU,OAAgC;EAGrD,QAAQ,MAFM,KAAK,OAAO,aAAa,KAAK,iBACrB,EAAE,MAAM,cAAc,KAAK,EAAE,MAAM,IAC7C,MAAiB;CAChC;;;;;;;;;;;;;;;;CAiBA,MAAa,UAAU,OAAe,IAA2B;EAC/D,MAAM,KAAK,OAAO,OAChB,KAAK,mBACL,EAAE,YAAY,MAAM,GACpB,EAAE,MAAM;GAAE;GAAI,YAAY;EAAM,EAAE,GAClC,EAAE,QAAQ,KAAK,CACjB;CACF;AACF"}