@vandenberghinc/volt 1.2.5 → 1.2.6

package/backend/dist/cjs/backend/src/database/collection.js

@@ -1,3301 +0,0 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var stdin_exports = {};
-__export(stdin_exports, {
-  Collection: () => Collection,
-  TransactionCollection: () => TransactionCollection
-});
-module.exports = __toCommonJS(stdin_exports);
-var mongodb = __toESM(require("mongodb"));
-var vlib = __toESM(require("@vandenberghinc/vlib"));
-var import_flatten = require("./flatten.js");
-var import_errors = require("../errors/index.js");
-class Collection {
-  /** Collection name */
-  name;
-  /** The mongo collection. */
-  _col;
-  /**
-   * The Database parent class, used to initialize the collection on demand.
-   * So the user can define collections at root level before the database is initialized.
-   */
-  db;
-  /** Is initialized. */
-  initialized = false;
-  /** Whether this collection instance is transaction-based. */
-  is_transaction = false;
-  /** Whether this transaction has been finalized (committed or aborted). */
-  is_finalized_transaction = false;
-  /** Time to live in msec for all documents. */
-  ttl;
-  /** Is ttl behaviour enabled? */
-  ttl_enabled;
-  /** Enable sliding ttl (refreshes ttl on update), or static ttl (sets ttl on insert) */
-  sliding_ttl;
-  /**
-   * The temporary indexes passed to the constructor for the init method.
-   * @note This is not private so it can be updated by {@link QuotaManager}.
-   */
-  _init_indexes;
-  /** The MongoDB client session for transaction support. */
-  _session;
-  /**
-   * The record type version for the database.
-   * See {@link Collection.Opts.record_version} for more info.
-   *
-   * Ensure its always defined so we always set the version to `1`,
-   * in case the user decides later that it would need the transform version
-   * for older documents. Otherwise they would not have the old `1` version.
-   */
-  record_version;
-  /**
-   * The function to transform an older document version to the current version.
-   * See {@link Collection.Opts.on_transform_version} for more info.
-   */
-  on_transform_version;
-  /**
-   * Save fully transformed documents again to prevent unneeded future transformations.
-   * See {@link Collection.Opts.persist_transformed_on_load} for more info.
-   */
-  persist_transformed_on_load;
-  /**
-   * The function to call when a document is loaded (also when a default value is used).
-   * See {@link Collection.Opts.on_load} for more info.
-   */
-  on_load_cb;
-  /**
-   * Constructs a new Collection instance.
-   *
-   * @param opts The constructor options for the collection.
-   *
-   * @throws An error when attempting to initialize a transaction-based collection without initializing the derived collection first.
-   *
-   * @docs
-   */
-  constructor(opts) {
-    if (!opts.transaction_based) {
-      this.name = opts.name;
-      this._col = opts.col;
-      this.db = opts.db;
-      this._init_indexes = opts.indexes;
-      this.is_transaction = false;
-      let ttl_ms;
-      let ttl_sliding = true;
-      if (typeof opts.ttl === "number") {
-        ttl_ms = opts.ttl;
-        ttl_sliding = true;
-      } else if (opts.ttl && typeof opts.ttl === "object") {
-        ttl_ms = opts.ttl.milliseconds;
-        ttl_sliding = opts.ttl.sliding ?? true;
-      } else {
-        ttl_ms = void 0;
-        ttl_sliding = true;
-      }
-      this.ttl = ttl_ms;
-      this.ttl_enabled = this.ttl != null;
-      this.sliding_ttl = ttl_sliding;
-      if (opts.on_transform_version != null && opts.record_version == null) {
-        throw new import_errors.InvalidUsageError({
-          message: "Option 'on_transform_version' requires 'record_version' to be defined.",
-          reason: "missing_record_version"
-        });
-      }
-      if (opts.record_version != null && (!Number.isInteger(opts.record_version) || opts.record_version < 1)) {
-        throw new import_errors.InvalidUsageError({
-          message: "Option 'record_version' must be a positive integer.",
-          reason: "invalid_record_version"
-        });
-      }
-      const version = opts.record_version ?? 1;
-      if (version !== 1 && opts.on_transform_version == null) {
-        throw new import_errors.InvalidUsageError({
-          message: "Option 'on_transform_version' must be set when 'record_version' is not 1.",
-          reason: "missing_transform_version"
-        });
-      }
-      this.record_version = opts.record_version ?? 1;
-      this.on_transform_version = opts.on_transform_version;
-      this.on_load_cb = opts.on_load;
-      this.persist_transformed_on_load = opts.persist_transformed_on_load ?? true;
-    } else {
-      if (!opts.derived_collection.initialized) {
-        throw new import_errors.InvalidUsageError({
-          message: `Derived collection "${opts.derived_collection.name}" is not yet initialized, this is required in order to construct a transaction based collection.`,
-          reason: "collection_not_initialized"
-        });
-      }
-      this.name = opts.derived_collection.name;
-      this._col = opts.derived_collection._col;
-      this.ttl = opts.derived_collection.ttl;
-      this.sliding_ttl = opts.derived_collection.sliding_ttl;
-      this.ttl_enabled = opts.derived_collection.ttl_enabled;
-      this.db = opts.derived_collection.db;
-      this.is_transaction = true;
-      this.record_version = opts.derived_collection.record_version;
-      this.on_transform_version = opts.derived_collection.on_transform_version;
-      this.on_load_cb = opts.derived_collection.on_load_cb;
-      this.persist_transformed_on_load = opts.derived_collection.persist_transformed_on_load;
-    }
-  }
-  // -------------------------------------------------------------------
-  // Private methods.
-  // -------------------------------------------------------------------
-  /**
-   * Initialize a database query from path or object.
-   * @throws An error if the input type is incorrect, and optionally if the query is empty.
-   */
-  _init_query(query, allow_empty, param_name) {
-    if (!query || typeof query !== "object" || Array.isArray(query)) {
-      throw new import_errors.InvalidUsageError({
-        message: `Parameter "${param_name}" is not a valid query.`,
-        reason: "invalid_query",
-        field: param_name
-      });
-    }
-    if (!allow_empty && Object.keys(query).length === 0) {
-      throw new import_errors.InvalidUsageError({
-        message: `Parameter "${param_name}" is an empty object.`,
-        reason: "empty_query",
-        field: param_name
-      });
-    }
-    return query;
-  }
-  /**
-   * Setup the ttl configuration.
-   *
-   * @note When transaction mode is enabled, the session option will not be used.
-   */
-  async _setup_ttl() {
-    this.assert_not_transaction_based();
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    if (!this.ttl_enabled || this.ttl == null) {
-      return;
-    }
-    const desired_seconds = Math.max(1, Math.ceil(this.ttl / 1e3));
-    const indexes = await this._col.indexes();
-    const ttl_index = indexes.find((ix) => ix && typeof ix.key === "object" && ix.key.__ttl_timestamp === 1);
-    if (!ttl_index) {
-      await this._col.createIndex({ __ttl_timestamp: 1 }, { expireAfterSeconds: desired_seconds });
-      return;
-    }
-    if (ttl_index.expireAfterSeconds !== desired_seconds) {
-      let coll_mod_succeeded = false;
-      try {
-        await this.db._db.command({
-          collMod: this.name,
-          index: {
-            name: ttl_index.name,
-            expireAfterSeconds: desired_seconds
-          }
-        });
-        coll_mod_succeeded = true;
-      } catch (error) {
-      }
-      if (!coll_mod_succeeded) {
-        try {
-          await this._col.dropIndex(ttl_index.name ?? "__ttl_timestamp_1");
-        } catch {
-        }
-        await this._col.createIndex({ __ttl_timestamp: 1 }, { expireAfterSeconds: desired_seconds });
-      }
-    }
-  }
-  /**
-   * Apply the ttl timestamp to a database operation (update doc or pipeline).
-   * Do not upsert if the user explicitly sets `upsert: false` in the operation.
-   */
-  _apply_ttl_to_operation(operation, upsert) {
-    if (!this.ttl_enabled)
-      return;
-    const now = /* @__PURE__ */ new Date();
-    if (Array.isArray(operation)) {
-      if (this.sliding_ttl) {
-        operation.push({ $set: { __ttl_timestamp: now } });
-      } else {
-        operation.push({ $set: { __ttl_timestamp: { $ifNull: ["$__ttl_timestamp", now] } } });
-      }
-      return;
-    }
-    const opKey = this.sliding_ttl ? "$set" : "$setOnInsert";
-    if (this.sliding_ttl || upsert !== false) {
-      const bucket = operation[opKey];
-      if (bucket == null) {
-        operation[opKey] = { __ttl_timestamp: now };
-      } else if (typeof bucket === "object") {
-        bucket.__ttl_timestamp = now;
-      } else {
-        throw new import_errors.InvalidUsageError({
-          message: `Invalid update operator object for TTL control at "${opKey}".`,
-          reason: "bad_ttl_operator"
-        });
-      }
-    }
-  }
-  /**
-   * Injects `__record_version` into an update **only on insert paths**.
-       *
-           * Rules:
-           * - **Pipeline updates** (`update: Document[]`): no-op here (MongoDB has no `$setOnInsert` in pipelines).
-           *   If you rely on upsert+pipeline, set `__record_version` explicitly in your pipeline.
-   * - **Replacement doc** (no operators):
-   *   - When `upsert === true`, set `__record_version` **only if missing**.
-   *   - When `upsert !== true`, do nothing (don’t mask older stored versions).
-       * - **Operator doc**:
-       *   - Respect any user-provided `__record_version` in `$set` or `$setOnInsert`.
-       *   - When `upsert === true` and the user didn’t provide a value, set it via `$setOnInsert`.
-   *
-       * Rationale:
-           * This avoids bumping `__record_version` during normal updates (which would mask older versions)
-           * while still stamping newly inserted documents.
-   */
-  _apply_record_version_to_operation(operation, upsert) {
-    const current = this.record_version;
-    if (current == null)
-      return;
-    if (Array.isArray(operation))
-      return;
-    const op = operation;
-    const hasDollar = Object.keys(op).some((k) => k[0] === "$");
-    if (!hasDollar) {
-      if (!upsert)
-        return;
-      if (op.__record_version == null) {
-        op.__record_version = current;
-      }
-      return;
-    }
-    const userSet = op?.$set?.__record_version;
-    const userOnIns = op?.$setOnInsert?.__record_version;
-    if (userSet != null || userOnIns != null)
-      return;
-    if (upsert) {
-      op.$setOnInsert = { ...op.$setOnInsert ?? {}, __record_version: current };
-    }
-  }
-  /**
-   * Decide if an error is worth a bounded retry.
-   * Prefers label-based detection and adds well-known transient/network surfaces.
-   *
-   * @param unknown_err The thrown error.
-   * @returns True for retryable/transient errors; false otherwise.
-   */
-  _should_retry_error(unknown_err) {
-    if (typeof unknown_err !== "object" || !unknown_err || Array.isArray(unknown_err)) {
-      return false;
-    }
-    const err = unknown_err;
-    const name = err?.name;
-    const code_name = err?.codeName;
-    const has_label = (label) => {
-      if (typeof err?.hasErrorLabel === "function") {
-        try {
-          return !!err.hasErrorLabel(label);
-        } catch {
-          return false;
-        }
-      }
-      const labels = err?.errorLabels;
-      return Array.isArray(labels) && labels.includes(label);
-    };
-    const raw_code = err?.code;
-    const numeric_code = typeof raw_code === "number" ? raw_code : typeof raw_code === "string" && /^\d+$/.test(raw_code) ? Number(raw_code) : void 0;
-    const sys_code = typeof raw_code === "string" && isNaN(Number(raw_code)) ? raw_code : void 0;
-    const transient_sys = /* @__PURE__ */ new Set([
-      "ECONNRESET",
-      "ETIMEDOUT",
-      "EPIPE",
-      "ECONNREFUSED",
-      "ENETUNREACH",
-      "ENETDOWN",
-      "EHOSTUNREACH",
-      "EAI_AGAIN"
-    ]);
-    if (name === "AbortError")
-      return false;
-    if (has_label("TransientTransactionError") || has_label("UnknownTransactionCommitResult") || has_label("RetryableWriteError")) {
-      return true;
-    }
-    if (name === "MongoNetworkError" || name === "MongoNetworkTimeoutError" || name === "MongoServerSelectionError" || name === "MongoTopologyClosedError" || sys_code && transient_sys.has(sys_code)) {
-      return true;
-    }
-    switch (numeric_code) {
-      case 6:
-        return true;
-      case 7:
-        return true;
-      case 50:
-        return true;
-      case 89:
-        return true;
-      case 91:
-        return true;
-      case 112:
-        return true;
-      case 189:
-        return true;
-      case 262:
-        return true;
-      case 10107:
-        return true;
-      case 11600:
-        return true;
-      case 11602:
-        return true;
-      case 13435:
-        return true;
-      case 13436:
-        return true;
-      case 9001:
-        return true;
-      default:
-        break;
-    }
-    if (code_name === "PoolClearedError")
-      return true;
-    return false;
-  }
-  /**
-   * Execute an async function with bounded, exponential backoff retries for retryable errors.
-   *
-   * - attempts: 1 ⇒ no retry (single execution).
-   * - Uses small bounded jitter to smooth load (see Collection.Retry).
-   *
-   * @param fn The async operation to execute.
-   * @param retry Number of attempts (1 = no retries) or {@link Collection.Retry.Opts}.
-   * @returns The function result when successful.
-   * @throws The last error if not retryable or retries exhausted.
-   */
-  async _with_retry(fn, retry) {
-    const opts = Collection.Retry.normalize(retry);
-    if (opts.attempts <= 1) {
-      return await Promise.resolve().then(fn);
-    }
-    const last_index = opts.attempts - 1;
-    for (let i = 0; i < opts.attempts; i++) {
-      try {
-        return await Promise.resolve().then(fn);
-      } catch (err) {
-        if (!this._should_retry_error(err) || i >= last_index) {
-          throw err;
-        }
-        const delay = Collection.Retry.compute_backoff_delay(i, opts);
-        if (delay > 0) {
-          await new Promise((resolve) => setTimeout(resolve, delay));
-        }
-      }
-    }
-    throw new Error("Unexpected retry loop termination in _with_retry");
-  }
-  /**
-   * Ensure `__record_version` is properly included for projections so version
-   * transformation can determine the original version reliably.
-   *
-   * @param projection The user-specified projection (if any).
-   * @returns A projection with `__record_version` enforced where needed.
-   */
-  _ensure_version_in_projection(projection) {
-    if (!projection)
-      return projection;
-    if (Array.isArray(projection)) {
-      return projection.includes("__record_version") ? projection : [...projection, "__record_version"];
-    }
-    if (Object.values(projection).some((v) => v === 0 || v === false)) {
-      if (projection["__record_version"] != null) {
-        const clone = { ...projection };
-        delete clone["__record_version"];
-        return clone;
-      }
-      return projection;
-    }
-    if (projection["__record_version"] !== 1 && projection["__record_version"] !== true) {
-      return { ...projection, __record_version: 1 };
-    }
-    return projection;
-  }
-  /**
-   * Determine whether a projection should be considered partial.
-   * @param projection The user-specified projection (if any).
-   * @returns True when a non-empty projection was provided.
-   */
-  _is_partial_projection(projection) {
-    if (!projection)
-      return false;
-    if (Array.isArray(projection))
-      return projection.length > 0;
-    return Object.keys(projection).length > 0;
-  }
-  /**
-    * Check whether the given update is operator-style (or a pipeline).
-    * - Aggregation pipeline: Array → valid.
-    * - Operator update: at least one top-level key starts with '$' → valid.
-    * - Plain object without '$' keys → NOT valid for updateOne/findOneAndUpdate.
-    */
-  _is_operator_update_or_pipeline(operation) {
-    return Array.isArray(operation) || operation && typeof operation === "object" && Object.keys(operation).some((k) => k[0] === "$");
-  }
-  _index_key_signature(keys) {
-    return Object.entries(keys).map(([k, v]) => `${k}:${v}`).join("|");
-  }
-  _keys_equal(a, b) {
-    const aEnt = Object.entries(a);
-    const bEnt = Object.entries(b);
-    if (aEnt.length !== bEnt.length)
-      return false;
-    for (let i = 0; i < aEnt.length; i++) {
-      const [ak, av] = aEnt[i];
-      const [bk, bv] = bEnt[i];
-      if (ak !== bk || av !== bv)
-        return false;
-    }
-    return true;
-  }
-  _normalize_index_opts(opts) {
-    let key;
-    let keys;
-    let options;
-    let unique;
-    let sparse;
-    let forced = false;
-    if (typeof opts === "string") {
-      key = opts;
-      unique = void 0;
-      sparse = void 0;
-    } else {
-      ({ key, keys, forced = false } = opts);
-      const user_options = opts.options;
-      options = user_options ? { ...user_options } : void 0;
-      if (opts.unique != null && options?.unique != null && opts.unique !== options.unique) {
-        throw new import_errors.InvalidUsageError({
-          message: `Encountered different values for attribute 'unique': ${opts.unique} and 'options.unique': ${options.unique}.`,
-          reason: "invalid_unique_option"
-        });
-      }
-      unique = opts.unique ?? options?.unique;
-      if (opts.sparse != null && options?.sparse != null && opts.sparse !== options.sparse) {
-        throw new import_errors.InvalidUsageError({
-          message: `Encountered different values for attribute 'sparse': ${opts.sparse} and 'options.sparse': ${options.sparse}.`,
-          reason: "invalid_sparse_option"
-        });
-      }
-      sparse = opts.sparse ?? options?.sparse;
-    }
-    if (unique != null) {
-      options = options || {};
-      options.unique = unique;
-    }
-    if (sparse != null) {
-      options = options || {};
-      options.sparse = sparse;
-    }
-    let keys_obj;
-    if (key) {
-      keys_obj = { [key]: 1 };
-    } else if (Array.isArray(keys) && keys.length > 0) {
-      keys_obj = {};
-      for (const k of keys)
-        keys_obj[k] = 1;
-    } else if (keys != null && typeof keys === "object") {
-      keys_obj = keys;
-    } else {
-      throw new import_errors.InvalidUsageError({
-        message: "Define one of the following parameters: [key, keys].",
-        reason: "invalid_index_definition"
-      });
-    }
-    return { keys_obj, options, forced };
-  }
-  /**
-   * Drop all indexes that are NOT part of this._init_indexes, excluding _id_ (and TTL index if enabled).
-   *
-   * @note We match by key pattern rather than name because names can differ.
-   */
-  async _drop_non_init_indexes() {
-    this.assert_not_transaction_based();
-    this.assert_init();
-    const existing = await this._col.listIndexes().toArray();
-    const desired = /* @__PURE__ */ new Set();
-    for (const item of this._init_indexes ?? []) {
-      const { keys_obj } = this._normalize_index_opts(item);
-      desired.add(this._index_key_signature(keys_obj));
-    }
-    const protected_names = /* @__PURE__ */ new Set(["_id_"]);
-    const keep_ttl = this.ttl_enabled;
-    const ttl_sig = this._index_key_signature({ __ttl_timestamp: 1 });
-    for (const ix of existing) {
-      const name = ix?.name;
-      if (!name)
-        continue;
-      if (protected_names.has(name))
-        continue;
-      const keyObj = ix.key;
-      if (!keyObj)
-        continue;
-      const sig = this._index_key_signature(keyObj);
-      if (desired.has(sig))
-        continue;
-      if (keep_ttl && sig === ttl_sig)
-        continue;
-      try {
-        this.db.server.log(3, `Dropping stale index "${name}" on collection: ${this.name}`);
-        await this._col.dropIndex(name);
-      } catch (err) {
-        if (err?.codeName !== "IndexNotFound")
-          throw err;
-      }
-    }
-  }
-  /**
-   * Creates indexes on collections.
-   *
-   * @note When transaction mode is enabled, the session option will not be used.
-   *
-   * @param opts The index create options.
-   */
-  async _create_index(opts) {
-    this.assert_not_transaction_based();
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    const { keys_obj, options, forced } = this._normalize_index_opts(opts);
-    const drop_index = async () => {
-      const existing = await this._col.listIndexes().toArray();
-      const match = existing.find((ix) => {
-        const ix_key = ix?.key;
-        if (!ix_key)
-          return false;
-        return this._keys_equal(ix_key, keys_obj);
-      });
-      if (match?.name) {
-        try {
-          await this._col.dropIndex(match.name);
-        } catch (err) {
-          if (err?.codeName !== "IndexNotFound")
-            throw err;
-        }
-        return;
-      }
-      if (options?.name) {
-        try {
-          await this._col.dropIndex(options.name);
-        } catch (err) {
-          if (err?.codeName !== "IndexNotFound")
-            throw err;
-        }
-        return;
-      }
-      const synthesized = Object.entries(keys_obj).map(([k, v]) => `${k}_${v}`).join("_");
-      try {
-        await this._col.dropIndex(synthesized);
-      } catch (err) {
-        if (err?.codeName !== "IndexNotFound")
-          throw err;
-      }
-    };
-    try {
-      try {
-        return await this._col.createIndex(keys_obj, options);
-      } catch (err) {
-        if (forced && err && typeof err === "object" && err.codeName === "IndexKeySpecsConflict") {
-          await drop_index();
-          return await this._col.createIndex(keys_obj, options);
-        }
-        throw err;
-      }
-    } catch (err) {
-      throw new Error(`Failed to create index on collection "${this.name}": ${err}`, { cause: err });
-    }
-  }
-  // async create_index(opts: string | Collection.IndexOpts): Promise<string> {
-  //     // Not supported on transaction-based collections.
-  //     this.assert_not_transaction_based();
-  //     // Ensure initialized
-  //     if (!this.initialized) { await this.init(); } this.assert_init();
-  //     // ---- Normalize inputs ----
-  //     let key: string | undefined;
-  //     let keys: string[] | Record<string, number> | undefined;
-  //     let options: mongodb.CreateIndexesOptions | undefined;
-  //     let unique: boolean | undefined;
-  //     let sparse: boolean | undefined;
-  //     let forced = false;
-  //     if (typeof opts === "string") {
-  //         key = opts;
-  //         unique = undefined;
-  //         sparse = undefined;
-  //     } else {
-  //         ({ key, keys, forced = false } = opts);
-  //         const options = opts.options as unknown as undefined | mongodb.CreateIndexesOptions;
-  //         // Conflict guard between `unique` and `options.unique`
-  //         if (opts.unique != null && options?.unique != null && opts.unique !== options.unique) {
-  //             throw new InvalidUsageError({
-  //                 message: `Encountered different values for attribute 'unique': ${opts.unique} and 'options.unique': ${options.unique}.`,
-  //                 reason: "invalid_unique_option",
-  //             });
-  //         }
-  //         unique = opts.unique ?? options?.unique;
-  //         // Conflict guard between `sparse` and `options.sparse`
-  //         if (opts.sparse != null && options?.sparse != null && opts.sparse !== options.sparse) {
-  //             throw new InvalidUsageError({
-  //                 message: `Encountered different values for attribute 'sparse': ${opts.sparse} and 'options.sparse': ${options.sparse}.`,
-  //                 reason: "invalid_sparse_option",
-  //             });
-  //         }
-  //         sparse = opts.sparse ?? options?.sparse;
-  //     }
-  //     // Ensure `unique` in options when provided
-  //     if (unique) {
-  //         options = options || {};
-  //         options.unique = unique;
-  //     }
-  //     // Ensure `sparse` in options when provided
-  //     if (sparse) {
-  //         options = options || {};
-  //         options.sparse = sparse;
-  //     }
-  //     // Build keys object
-  //     let keys_obj: Record<string, number>;
-  //     if (key) {
-  //         keys_obj = { [key]: 1 };
-  //     } else if (Array.isArray(keys) && keys.length > 0) {
-  //         keys_obj = {};
-  //         for (const k of keys) keys_obj[k] = 1;
-  //     } else if (keys != null && typeof keys === "object") {
-  //         keys_obj = keys as Record<string, number>;
-  //     } else {
-  //         throw new InvalidUsageError({
-  //             message: "Define one of the following parameters: [key, keys].",
-  //             reason: "invalid_index_definition",
-  //         });
-  //     }
-  //     const drop_index = async () => {
-  //         try {
-  //             const existing = await this._col.listIndexes().toArray();
-  //             const match = existing.find(ix => {
-  //                 const ix_key = ix?.key as Record<string, number> | undefined;
-  //                 if (!ix_key) return false;
-  //                 const a = Object.entries(ix_key);
-  //                 const b = Object.entries(keys_obj);
-  //                 if (a.length !== b.length) return false;
-  //                 // exact key-value equality (order-insensitive)
-  //                 const as = new Map(a);
-  //                 for (const [kk, vv] of b) {
-  //                     if (as.get(kk) !== vv) return false;
-  //                 }
-  //                 return true;
-  //             });
-  //             // Prefer matched key's real name
-  //             if (match?.name) {
-  //                 try { await this._col.dropIndex(match.name); }
-  //                 catch (err: any) { if (err?.codeName !== "IndexNotFound") throw err; }
-  //             } else if (options?.name) {
-  //                 try { await this._col.dropIndex(options.name); }
-  //                 catch (err: any) { if (err?.codeName !== "IndexNotFound") throw err; }
-  //             } else {
-  //                 // last-resort synthesized name (simple cases)
-  //                 const synthesized = Object.entries(keys_obj).map(([k, v]) => `${k}_${v}`).join("_");
-  //                 try { await this._col.dropIndex(synthesized); }
-  //                 catch (err: any) { if (err?.codeName !== "IndexNotFound") throw err; }
-  //             }
-  //         } catch (err) {
-  //             // If listIndexes itself fails for some reason, do not hide the error
-  //             throw new Error(`Failed to create index on collection "${this.name}": ${err}`, { cause: err });
-  //         }
-  //     }
-  //     try {
-  //         // Create (or re-create)
-  //         try {
-  //             return await this._col.createIndex(keys_obj, options);
-  //         }
-  //         // Retry once on IndexKeySpecsConflict when forced=true
-  //         catch (err) {
-  //             if (forced && err && typeof err === "object" && (
-  //                 (err as any).codeName === "IndexKeySpecsConflict"
-  //             )) {
-  //                 await drop_index();
-  //                 return await this._col.createIndex(keys_obj, options);
-  //             }
-  //             throw err;
-  //         }
-  //     } catch (err) {
-  //         throw new Error(`Failed to create index on collection "${this.name}": ${err}`, { cause: err });
-  //     }
-  // }
-  // -------------------------------------------------------------------
-  // Public methods.
-  // -------------------------------------------------------------------
-  /**
-   * Initialize the collection, creating indexes and setting up TTL if needed.
-   * @returns The initialized collection instance.
-   *
-   * @docs
-   */
-  async init() {
-    if (this.initialized === false) {
-      this.db.server.log(3, "Initializing collection: ", this.name);
-      if (!this.is_transaction) {
-        if (this._col == null) {
-          this.db.server.log(3, "Checking collection: ", this.name);
-          if (!this.db.server.production) {
-            await this.db.ensure_connection();
-          }
-          if (!this.db.connected || !this.db._db) {
-            throw new import_errors.InvalidUsageError({
-              message: `Database client is not connected.`,
-              reason: "client_not_connected"
-            });
-          }
-          if (this.db._listed_cols == null) {
-            this.db.server.log(3, "Listing collections...");
-            this.db._listed_cols = await this.db._db.listCollections().toArray();
-            this.db.server.log(3, "Listed collections: " + this.db._listed_cols.map((x) => x.name).join(", "));
-          }
-          if (!this.db._listed_cols.find((x) => x.name === this.name)) {
-            this.db.server.log(3, "Creating collection: " + this.name);
-            let create_col_retries = 3;
-            let last_error = null;
-            let collection_created = false;
-            while (create_col_retries > 0 && !collection_created) {
-              try {
-                await this.db._db.createCollection(this.name);
-                collection_created = true;
-              } catch (error) {
-                last_error = error;
-                if (error.codeName === "NamespaceExists") {
-                  collection_created = true;
-                } else if (create_col_retries > 1 && (error.code === 11e3 || error.code === 48)) {
-                  create_col_retries--;
-                  await new Promise((r) => setTimeout(r, 100));
-                } else {
-                  throw error;
-                }
-              }
-            }
-            if (!collection_created && last_error) {
-              throw last_error;
-            }
-          }
-          this.db.server.log(3, "Initializing mongodb collection connection: " + this.name);
-          this._col = this.db._db.collection(this.name);
-        }
-        this.initialized = true;
-        if (this.ttl_enabled) {
-          this.db.server.log(3, "Setting up TTL index for collection: " + this.name);
-          await this._setup_ttl();
-        }
-        await this._drop_non_init_indexes();
-        if (this._init_indexes?.length) {
-          for (const item of this._init_indexes) {
-            this.db.server.log(3, "Creating index " + JSON.stringify(item) + " on collection: " + this.name);
-            await this._create_index(item);
-          }
-        }
-      } else {
-        if (!this.db.client) {
-          throw new import_errors.InvalidUsageError({
-            message: "Database client is not initialized, this is likely because you did not initialize the transaction based collection through 'Collection.start_transaction'.",
-            reason: "client_not_connected"
-          });
-        }
-        if (!this._col) {
-          throw new import_errors.InvalidUsageError({
-            message: "Derived collection is not initialized, this should have been initialized before passing it to a transaction based collection constructor.",
-            reason: "derived_collection_not_initialized"
-          });
-        }
-        this._session = this.db.client.startSession();
-        this._session.startTransaction();
-        this.initialized = true;
-      }
-    }
-    return this;
-  }
-  /**
-   * Assert that the collection is initialized and has a valid MongoDB collection.
-   * @throws {Error} Throws if the collection is not initialized or _col is null
-   * @returns An initialized collection type assertion
-   *
-   * @docs
-   */
-  assert_init() {
-    if (!this.initialized || this._col == null) {
-      throw new import_errors.InvalidUsageError({
-        message: `Collection "${this.name}" is not initialized.`,
-        reason: "collection_not_initialized"
-      });
-    }
-  }
-  /**
-   * Assert that if this is a transaction, it has not been finalized.
-   * @throws Error if this is a finalized transaction.
-   *
-   * @docs
-   */
-  assert_not_finalized() {
-    if (this.is_transaction && this.is_finalized_transaction) {
-      throw new import_errors.InvalidUsageError({
-        message: `Transaction has already been finalized (committed or aborted).`,
-        reason: "transaction_finalized"
-      });
-    }
-  }
-  /**
-   * Assert that this collection is not transaction based.
-   *
-   * @docs
-   */
-  assert_not_transaction_based() {
-    if (this.is_transaction) {
-      throw new import_errors.InvalidUsageError({
-        message: `Collection "${this.name}" is transaction based.`,
-        reason: "collection_is_transaction"
-      });
-    }
-  }
-  /**
-   * Get operation options with session if this is a transaction.
-   * @returns Options object with session if applicable.
-   *
-   * @docs
-   */
-  get_operation_options(opts) {
-    if (this.is_transaction && this._session) {
-      return { ...opts, session: this._session };
-    }
-    return opts ?? {};
-  }
-  /**
-   * Get the raw and initialized MongoDB collection.
-   * @returns The MongoDB collection instance.
-   *
-   * @docs
-   */
-  async col() {
-    await this.init();
-    return this._col;
-  }
-  /**
-   * Check if an index exists.
-   * @note Not supported for transaction based collections.
-   * @param index The name of the index to check.
-   * @returns True if the index exists, false otherwise.
-   *
-   * @docs
-   */
-  async has_index(index) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    this.assert_not_transaction_based();
-    return (await this._col.listIndexes().toArray()).some((x) => x.name === index);
-  }
-  /**
-   * Standalone helper: merge `source` into `target` for missing keys only.
-   * Clones assigned nested objects/arrays/dates once (when `clone` is true).
-   *
-   * @throws An error if the max depth recursion depth has been exceeded.
-   *
-   * @docs
-   */
-  static insert_defaults(target, source, opts = {}) {
-    const max_depth = opts.max_depth ?? 1e3;
-    const depth = opts.depth ?? 0;
-    const should_clone = opts.clone ?? true;
-    const isPlainObject = (v) => v != null && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype;
-    const cloneAssigned = (val, d) => {
-      if (!should_clone)
-        return val;
-      if (d > max_depth)
-        return val;
-      if (Array.isArray(val)) {
-        return val.map((item) => cloneAssigned(item, d + 1));
-      }
-      if (val instanceof Date) {
-        return new Date(val.getTime());
-      }
-      if (isPlainObject(val)) {
-        const out = {};
-        for (const k of Object.keys(val)) {
-          out[k] = cloneAssigned(val[k], d + 1);
-        }
-        return out;
-      }
-      return val;
-    };
-    if (depth > max_depth) {
-      throw new Error(`Maximum recursion depth (${max_depth}) exceeded in 'insert_defaults'`);
-    }
-    for (const key of Object.keys(source)) {
-      const v = target[key];
-      const d = source[key];
-      if (v === void 0) {
-        target[key] = cloneAssigned(d, depth + 1);
-      } else if (isPlainObject(v) && isPlainObject(d)) {
-        Collection.insert_defaults(v, d, { depth: depth + 1, max_depth, clone: should_clone });
-      }
-    }
-  }
-  flatten(obj, prefix = "") {
-    return (0, import_flatten.flatten)(obj, prefix);
-  }
-  /**
-   * Execute `on_transform_version` and `on_load_cb` on a loaded document.
-   * Ensures `__record_version` is set when {@link record_version} is defined.
-   *
-   * @note This is done automatically during load operations.
-   *
-   * @param data The loaded document.
-   * @param opts Additional options.
-   *
-   * @returns The transformed document.
-   *
-   * @throws {Collection.OnTransformError} When an error occurs during the {@link Collection.Opts.on_transform_version} callback.
-   * @throws {Collection.OnLoadError} When an error occurs during the {@link Collection.Opts.on_load} callback.
-   *
-   * @docs
-   */
-  async apply_on_load(data, opts) {
-    let transformed = false;
-    const is_partial = this._is_partial_projection(opts.projection);
-    if (this.record_version != null && this.on_transform_version != null && data && data.__record_version !== this.record_version) {
-      try {
-        data = await this.on_transform_version(data, {
-          from_version: data.__record_version,
-          to_version: this.record_version,
-          projection: opts.projection,
-          is_partial
-        });
-        transformed = true;
-      } catch (error) {
-        throw new Collection.OnTransformError({
-          message: `Failed to transform document from version '${data.__record_version}' to '${this.record_version}'.`,
-          query: {},
-          reason: "callback_error",
-          cause: error
-        });
-      }
-      data.__record_version = this.record_version;
-    }
-    if (this.on_load_cb) {
-      try {
-        data = await this.on_load_cb(data, {
-          projection: opts.projection,
-          is_partial
-        });
-      } catch (error) {
-        throw new Collection.OnLoadError({
-          message: `Encountered an error during the 'on_load' callback.`,
-          query: {},
-          reason: "callback_error",
-          cause: error
-        });
-      }
-    }
-    if (transformed && this.persist_transformed_on_load && opts.persist && // only persist if doc came from DB (not a default)
-    !is_partial && // only when we have a full document
-    data?._id != null) {
-      try {
-        if (this.persist_transformed_on_load === "replace") {
-          const replace_doc = { ...data };
-          if (this.ttl_enabled && replace_doc.__ttl_timestamp == null) {
-            replace_doc.__ttl_timestamp = /* @__PURE__ */ new Date();
-          }
-          if (this.record_version != null && replace_doc.__record_version == null) {
-            replace_doc.__record_version = this.record_version;
-          }
-          const res = this.replace(
-            { _id: data._id },
-            replace_doc,
-            { upsert: false, throw: false, apply_ttl: false }
-            // do not create on read
-          );
-          if (opts.await_persist) {
-            await res;
-          } else {
-            void res;
-          }
-        } else {
-          const set_doc = { ...data };
-          delete set_doc._id;
-          delete set_doc.__ttl_timestamp;
-          const res = this.save(
-            { _id: data._id },
-            { $set: set_doc },
-            { upsert: false, throw: false, apply_ttl: false }
-            // do not create on read
-          );
-          if (opts.await_persist) {
-            await res;
-          } else {
-            void res;
-          }
-        }
-      } catch {
-      }
-    }
-    return data;
-  }
-  /**
-   * Count documents accurately using MongoDB's `countDocuments`.
-   *
-   * @param query An optional filter to count matching documents. When omitted, counts all documents.
-   * @param opts  Additional options, see {@link Collection.CountOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @returns
-   * - A number representing the accurate count when successful.
-   * - A {@link Collection.CountError} when `opts.throw === false` and an error occurs.
-   *
-   * @throws {Collection.CountError} When `throw !== false` and the count fails.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async count(query, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const query_op = this._init_query(query ?? {}, true, "query");
-    const throw_errors = opts?.throw ?? true;
-    try {
-      const n = await this._with_retry(() => this._col.countDocuments(query_op, this.get_operation_options(typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {})), opts?.retry);
-      return n;
-    } catch (e) {
-      const err = new Collection.CountError({
-        message: "Count operation failed due to an unexpected error.",
-        query: query_op,
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-  }
-  /**
-   * Return a fast, approximate count of the entire collection using
-   * MongoDB's `estimatedDocumentCount`. This method does **not** accept
-   * a filter and may be off under heavy churn.
-   *
-   * @param opts Additional options, see {@link Collection.CountOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @returns
-   * - A number representing the estimated total number of documents when successful.
-   * - A {@link Collection.CountError} when `opts.throw === false` and an error occurs.
-   *
-   * @throws {Collection.CountError} When `throw !== false` and the count fails.
-   * @throws {InvalidUsageError} (always) When the collection was not used properly.
-   *
-   * @docs
-   */
-  async count_estimated(opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const throw_errors = opts?.throw ?? true;
-    try {
-      const n = await this._with_retry(() => this._col.estimatedDocumentCount(this.get_operation_options(typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {})), opts?.retry);
-      return n;
-    } catch (e) {
-      const err = new Collection.CountError({
-        message: "Estimated count operation failed due to an unexpected error.",
-        query: {},
-        // no filter for estimatedDocumentCount
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-  }
-  /**
-   * List all documents for a specific query.
-   *
-   * @param query The database directory path.
-   * @param opts The list options, see {@link Collection.ListOpts}.
-   * @param allow_empty_query When `true`, allows an empty query (i.e. `{}`) to be passed, which would otherwise throw an error.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note The {@link Collection.Opts.on_load} and {@link Collection.Opts.on_transform_version} callbacks
-   *       are not executed when `opts.cursor === true`.
-   * @note When `opts.callback` is a function (and `opts.cursor !== true`), this method streams documents and
-   *       invokes the callback for each processed document, then returns `undefined` on success.
-   *       This mode is memory-friendly and avoids accumulating the entire result set.
-   *
-   * @returns
-   * - An error if `opts.throw === false` and a {@link Collection.ListError} has occurred.
-   * - The find cursor when `opts.cursor === true`.
-   * - When `opts.callback && !opts.cursor` is provided, `undefined` on success.
-   * - When `opts.page_info === true && !opts.cursor && !opts.callback`, returns {@link Collection.ListedPage}.
-   * - Otherwise, an array of documents matching the path.
-   *
-   * @throws {Collection.ListError} When `throw !== false` if an error occurred during the operation, in which case {@link Collection.ListError.cause} is defined.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async list(query, opts, allow_empty_query = false) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const throw_errors = opts?.throw ?? true;
-    const has_callback = typeof opts?.callback === "function";
-    const page_info_requested = opts?.page_info === true && opts?.cursor !== true && !has_callback;
-    if (has_callback && opts?.cursor === true) {
-      throw new import_errors.InvalidUsageError({
-        message: "Option 'callback' cannot be combined with 'cursor: true'.",
-        reason: "invalid_option_combination",
-        field: "opts.callback"
-      });
-    }
-    if (has_callback && opts?.page_info === true) {
-      throw new import_errors.InvalidUsageError({
-        message: "Option 'callback' cannot be combined with 'page_info: true'.",
-        reason: "invalid_option_combination",
-        field: "opts.callback"
-      });
-    }
-    const user_limit = opts?.limit;
-    if (typeof user_limit === "number") {
-      const effective_user_limit = page_info_requested ? user_limit + 1 : user_limit;
-      const is_integer = Number.isInteger(user_limit);
-      const is_valid = user_limit >= 0 && Number.isFinite(effective_user_limit);
-      if (!is_integer || !is_valid) {
-        throw new import_errors.InvalidUsageError({
-          message: `Option 'limit' must be a non-negative finite integer${page_info_requested ? " (including +1 for pagination)." : "."}`,
-          reason: "invalid_limit",
-          field: "opts.limit"
-        });
-      }
-    }
-    const probing_limit = typeof user_limit === "number" && page_info_requested ? user_limit + 1 : user_limit;
-    if (opts?.skip != null) {
-      if (!Number.isInteger(opts.skip) || opts.skip < 0) {
-        throw new import_errors.InvalidUsageError({
-          message: "Option 'skip' must be a non-negative integer.",
-          reason: "invalid_skip",
-          field: "opts.skip"
-        });
-      }
-    }
-    if (user_limit === 0 && !opts?.cursor) {
-      if (has_callback) {
-        return void 0;
-      }
-      return page_info_requested ? { items: [], has_more: false } : [];
-    }
-    let batch_size = typeof opts?.pagination?.batch_size === "number" ? Math.floor(opts.pagination.batch_size) : 1e3;
-    if (!Number.isFinite(batch_size) || batch_size < 1 || batch_size > 1e4) {
-      throw new import_errors.InvalidUsageError({
-        message: "Option `pagination.batch_size` must be an integer between '1' and '10000'.",
-        reason: "invalid_pagination_batch_size",
-        field: "opts.pagination.batch_size"
-      });
-    }
-    if (typeof probing_limit === "number" && probing_limit > 0 && probing_limit < 1e4) {
-      batch_size = Math.min(batch_size, probing_limit);
-    }
-    const query_op = this._init_query(query, allow_empty_query, "query");
-    const find_options = {
-      projection: opts?.projection ? Collection.Projection.init(this._ensure_version_in_projection(opts.projection)) : void 0,
-      sort: opts?.sort,
-      skip: opts?.skip,
-      // no default so we can stream all docs if no limit was set.
-      // allow +1 probe for page_info
-      limit: probing_limit
-    };
-    if (typeof opts?.timeout === "number") {
-      find_options.maxTimeMS = opts.timeout;
-    }
-    try {
-      const cursor = await this._with_retry(() => this._col.find(query_op, this.get_operation_options(find_options)), opts?.retry);
-      cursor.batchSize(batch_size);
-      if (typeof opts?.timeout === "number") {
-        cursor.maxTimeMS(opts.timeout);
-      }
-      if (opts?.cursor)
-        return cursor;
-      if (has_callback) {
-        const max_docs2 = user_limit ?? Number.POSITIVE_INFINITY;
-        let processed_count = 0;
-        try {
-          while (processed_count < max_docs2) {
-            const first = await this._with_retry(() => cursor.next(), opts?.retry);
-            if (first == null)
-              break;
-            let processed = first;
-            if (processed && typeof processed === "object") {
-              processed = await this.apply_on_load(processed, {
-                projection: opts?.projection,
-                persist: true,
-                await_persist: false
-              });
-            }
-            try {
-              await opts.callback(processed);
-            } catch (cb_err) {
-              throw new Collection.ListError({
-                message: "List callback failed for a streamed document.",
-                query: query_op,
-                reason: "callback_error",
-                cause: cb_err
-              });
-            }
-            processed_count++;
-            if (processed_count >= max_docs2)
-              break;
-            let drained = 1;
-            while (drained < batch_size && processed_count < max_docs2) {
-              const next_in_buffer = await cursor.tryNext();
-              if (next_in_buffer == null)
-                break;
-              let processed2 = next_in_buffer;
-              if (processed2 && typeof processed2 === "object") {
-                processed2 = await this.apply_on_load(processed2, {
-                  projection: opts?.projection,
-                  persist: true,
-                  await_persist: false
-                });
-              }
-              try {
-                await opts.callback(processed2);
-              } catch (cb_err) {
-                throw new Collection.ListError({
-                  message: "List callback failed for a streamed document.",
-                  query: query_op,
-                  reason: "callback_error",
-                  cause: cb_err
-                });
-              }
-              processed_count++;
-              drained++;
-            }
-          }
-        } finally {
-          if (!cursor.closed) {
-            await cursor.close().catch(() => {
-            });
-          }
-        }
-        return void 0;
-      }
-      const max_docs = user_limit ?? Number.POSITIVE_INFINITY;
-      const target = page_info_requested && typeof user_limit === "number" ? user_limit + 1 : max_docs;
-      const docs = [];
-      let fetched = 0;
-      try {
-        while (fetched < target) {
-          const first = await this._with_retry(() => cursor.next(), opts?.retry);
-          if (first == null) {
-            break;
-          }
-          let processed = first;
-          if (processed && typeof processed === "object") {
-            processed = await this.apply_on_load(processed, {
-              projection: opts?.projection,
-              persist: true,
-              await_persist: false
-            });
-          }
-          docs.push(processed);
-          fetched++;
-          if (fetched >= target) {
-            break;
-          }
-          let drained = 1;
-          while (drained < batch_size && fetched < target) {
-            const next_in_buffer = await cursor.tryNext();
-            if (next_in_buffer == null) {
-              break;
-            }
-            let processed2 = next_in_buffer;
-            if (processed2 && typeof processed2 === "object") {
-              processed2 = await this.apply_on_load(processed2, {
-                projection: opts?.projection,
-                persist: true,
-                await_persist: false
-              });
-            }
-            docs.push(processed2);
-            fetched++;
-            drained++;
-          }
-        }
-      } finally {
-        if (!cursor.closed) {
-          await cursor.close().catch(() => {
-          });
-        }
-      }
-      if (page_info_requested) {
-        let has_more = false;
-        let out = docs;
-        if (typeof user_limit === "number" && docs.length > user_limit) {
-          has_more = true;
-          out = docs.slice(0, user_limit);
-        }
-        return { items: out, has_more };
-      }
-      if (docs.length > max_docs && max_docs !== Number.POSITIVE_INFINITY) {
-        return docs.slice(0, max_docs);
-      }
-      return docs;
-    } catch (e) {
-      if (e instanceof Collection.ListError) {
-        if (throw_errors)
-          throw e;
-        return e;
-      }
-      const error = new Collection.ListError({
-        message: "Encountered an error while listing documents.",
-        query: query_op,
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw error;
-      return error;
-    }
-  }
-  /**
-   * List all documents of the collection.
-   *
-   * @param opts The list options, see {@link Collection.ListOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note The {@link Collection.Opts.on_load} and {@link Collection.Opts.on_transform_version} callbacks
-   *       are not executed when `opts.cursor === true`.
-   * @note When `opts.callback` is a function (and `opts.cursor !== true`), this method streams documents and
-   *       invokes the callback for each processed document, then returns `undefined` on success.
-   *
-   * @returns
-   * - Array of all documents in the collection.
-   * - The find cursor when `opts.cursor === true`.
-   * - `undefined` when `opts.callback && !opts.cursor`.
-   * - An error if `opts.throw === false` and a {@link Collection.ListError} has occurred.
-   *
-   * @throws {Collection.ListError} When `throw !== false` if an error occurred during the operation, in which case {@link Collection.ListError.cause} is defined.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async list_all(opts) {
-    return this.list({}, opts, true);
-  }
-  /**
-   * Check if a document exists by only loading the document's id.
-   *
-   * @param query The database path to the document.
-   * @param opts The exists options, see {@link Collection.ExistsOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note This method does not execute the {@link Collection.Opts.on_load}
-   *       and {@link Collection.Opts.on_transform_version} callbacks.
-   *
-   * @returns
-   * - An error if `opts.throw === false` and a {@link Collection.ExistsError} has occurred.
-   * - True if the document exists, false otherwise.
-   *
-   * @throws {Collection.ExistsError} When `throw !== false` if an error occurred during the operation, in which case {@link Collection.ExistsError.cause} is defined.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async exists(query, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const query_op = this._init_query(query, false, "query");
-    const throw_errors = opts?.throw ?? true;
-    try {
-      const find_opts = {
-        projection: { _id: 1 }
-      };
-      if (typeof opts?.timeout === "number") {
-        find_opts.maxTimeMS = opts.timeout;
-      }
-      const doc = await this._with_retry(() => this._col.findOne(query_op, this.get_operation_options(find_opts)), opts?.retry);
-      return doc != null;
-    } catch (e) {
-      const err = new Collection.ExistsError({
-        message: "Failed to check if the queried document exists due to an unexpected error.",
-        query: query_op,
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-  }
-  /**
-   * Load a single document by query.
-   *
-   * Applies an optional projection and, if a `default` is provided, inserts any
-   * missing keys from the default into the loaded document (values are deep-cloned).
-   *
-   * @note The `default` value is deep-cloned if it is returned or inserted.
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @param query The database query.
-   * @param opts Additional load options {@link Collection.LoadOpts}.
-   *
-   * @returns
-   * - When `opts.throw === false`:
-   *   - If found: the loaded (projected) document.
-   *   - If not found and `opts.default` is provided: the deep-cloned default data.
-   *   - If not found and no default: a {@link Collection.NotFoundError}.
-   *   - On load failure: a {@link Collection.LoadError}.
-   * - When `opts.throw !== false` (default):
-   *   - If found: the loaded (projected) document.
-   *   - If not found and `opts.default` is provided: the deep-cloned default data.
-   *   - If not found and no default: a {@link Collection.NotFoundError} is **thrown**.
-   *   - On load failure: a {@link Collection.LoadError} is **thrown**.
-   *
-   * @throws {Collection.LoadError} Only when `opts.throw !== false` and the load fails.
-   * @throws {Collection.NotFoundError} When the document is not found and `opts.throw !== false && opts.default == null`.
-   * @throws {InvalidUsageError} When the provided arguments are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async load(query, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const retry = opts?.retry;
-    const throw_errors = opts?.throw ?? true;
-    const find_query = this._init_query(query, false, "query");
-    const base_find = {};
-    if (opts?.projection)
-      base_find.projection = Collection.Projection.init(this._ensure_version_in_projection(opts.projection));
-    if (typeof opts?.timeout === "number")
-      base_find.maxTimeMS = opts.timeout;
-    const find_opts = this.get_operation_options(base_find);
-    try {
-      const doc = await this._with_retry(() => this._col.findOne(find_query, find_opts), opts?.retry);
-      if (!doc) {
-        if (opts?.default) {
-          let default_doc;
-          if (typeof opts.default === "function") {
-            default_doc = vlib.Object.deep_copy(opts.default());
-          } else {
-            default_doc = vlib.Object.deep_copy(opts.default);
-          }
-          if (default_doc._id == null) {
-            default_doc._id = new mongodb.ObjectId();
-          }
-          if (this.record_version != null) {
-            default_doc.__record_version = this.record_version;
-          }
-          let out = default_doc;
-          const is_partial = this._is_partial_projection(opts?.projection);
-          out = await this.apply_on_load(out, {
-            projection: opts?.projection,
-            persist: false,
-            // do not persist defaults.
-            await_persist: true
-          });
-          return out;
-        }
-        const err = new Collection.NotFoundError({
-          message: "Document not found.",
-          query: find_query,
-          reason: "not_found"
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      let working = doc;
-      if (opts?.default) {
-        if (typeof opts.default === "function") {
-          Collection.insert_defaults(working, opts.default(), { clone: true });
-        } else {
-          Collection.insert_defaults(working, opts.default, { clone: true });
-        }
-      }
-      working = await this.apply_on_load(working, {
-        projection: opts?.projection,
-        persist: true,
-        await_persist: true
-      });
-      return working;
-    } catch (e) {
-      if (e instanceof Collection.NotFoundError) {
-        if (throw_errors)
-          throw e;
-        return e;
-      }
-      const err = new Collection.LoadError({
-        message: "Load failed due to an unexpected error.",
-        query: find_query,
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-  }
-  /**
-   * Save data with predefined `$set` behaviour.
-   * When the document already exists this function only updates the specified content attributes.
-   * When a document does not exist it will automatically be created, unless `opts.upsert !== false`.
-   *
-   * @param query The database query / path to the document.
-   * @param content The data to save.
-   * @param opts Additional options, see {@link Collection.SetOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note The `opts.upsert` option defaults to `true`.
-   * @note `set()` does not deep-merge nested objects.
-   *       With `flatten: false`, nested objects are written as whole objects—so their keys are replaced
-   *       by exactly what you provide (missing nested keys can be overwritten/removed).
-   *       With `flatten: true`, nested objects are flattened into dot notation, allowing you to update specific nested keys without affecting siblings.
-   *
-   * @returns
-   * - When `opts.bulk === true`: an unexecuted bulk operation.
-   * - When `opts.return === true`: the **updated** document; or a {@link Collection.SaveError} when `throw:false` and a write failure occurs.
-   * - Otherwise: `undefined` on success; or a {@link Collection.SaveError} when `throw:false` and a write failure occurs.
-   *
-   * @throws {Collection.SaveError} Only when `opts.throw !== false` and the write fails.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async set(query, content, opts) {
-    if (opts?.flatten)
-      content = this.flatten(content);
-    const operation = { $set: content };
-    return await this.save(query, operation, opts);
-  }
-  /**
-   * Save a single document without performing any default `$set` or `$inc` like operations.
-   * When a document does not exist it will automatically be created unless `opts.upsert === false`.
-   *
-   * @param query The database query / path to the document.
-   * @param operation The MongoDB update document or pipeline (e.g. `{ $set: { key: value } }`).
-   * @param opts Additional options, see {@link Collection.SaveOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note The `opts.upsert` option defaults to `true`.
-   * @note Replacement documents are not allowed here. An update operator
-   *       document (e.g. `$set`, `$inc`) or an aggregation pipeline is required.
-   *       To replace a document use {@link replace}.
-   *
-   * @note This writes the value you pass in—it does not deep-merge nested objects.
-   *       If you save a nested object, any nested keys you leave out may be overwritten/removed.
-   *       Use `set()` in combination with `flatten: true` to perform deep merges on nested objects without worrying about this behavior.
-   *
-   * @returns
-   * - When `opts.bulk === true`: an unexecuted bulk operation.
-   * - When `opts.return === true`: the **updated** document; or a {@link Collection.SaveError} when `throw:false` and a write failure occurs.
-   * - Otherwise: {@link mongodb.UpdateResult} on success; or a {@link Collection.SaveError} when `throw:false` and a write failure occurs.
-   *
-   * @throws {Collection.SaveError} Only when `opts.throw !== false` and the write fails.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async save(query, operation, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    if (!this._is_operator_update_or_pipeline(operation)) {
-      throw new import_errors.InvalidUsageError({
-        message: "Plain replacement documents are not allowed for 'save()' (uses updateOne/findOneAndUpdate). Pass an operator update or aggregation pipeline. To replace a document, call 'replace()'.",
-        reason: "invalid_update_document",
-        field: "operation"
-      });
-    }
-    const query_op = this._init_query(query, false, "query");
-    const throw_errors = opts?.throw ?? true;
-    const retry = opts?.retry;
-    const upsert = opts?.upsert ?? true;
-    if (this.ttl_enabled && opts?.apply_ttl !== false)
-      this._apply_ttl_to_operation(operation, upsert);
-    if (this.record_version != null)
-      this._apply_record_version_to_operation(operation, upsert);
-    if (opts?.bulk) {
-      const b_op = {
-        updateOne: {
-          filter: query_op,
-          update: operation,
-          upsert
-        }
-      };
-      return b_op;
-    }
-    if (opts?.return) {
-      let res;
-      try {
-        res = await this._with_retry(() => this._col.findOneAndUpdate(query_op, operation, this.get_operation_options({
-          upsert,
-          returnDocument: mongodb.ReturnDocument.AFTER,
-          includeResultMetadata: false,
-          ...typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {}
-        })), retry);
-      } catch (e) {
-        const err = new Collection.SaveError({
-          message: "Update failed due to an unexpected error.",
-          query: query_op,
-          reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-          cause: e
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      if (!res) {
-        const err = new Collection.SaveError({
-          message: "Document write was not acknowledged.",
-          query: query_op,
-          reason: "not_acknowledged"
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      try {
-        const processed = await this.apply_on_load(res, {
-          projection: void 0,
-          persist: true,
-          await_persist: true
-        });
-        return processed;
-      } catch (e) {
-        const err = new Collection.SaveError({
-          message: "Update succeeded but post-load processing failed.",
-          query: query_op,
-          reason: "post_process_failed",
-          cause: e
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-    } else {
-      let res;
-      try {
-        res = await this._with_retry(() => this._col.updateOne(query_op, operation, this.get_operation_options({
-          upsert,
-          ...typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {}
-        })), retry);
-      } catch (e) {
-        const err = new Collection.SaveError({
-          message: "Update failed due to an unexpected error.",
-          query: query_op,
-          reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-          cause: e
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      if (!res.acknowledged || res.matchedCount === 0 && res.upsertedCount === 0) {
-        const err = new Collection.SaveError({
-          message: !res.acknowledged ? "Document write was not acknowledged." : "No document matched the filter and no upsert occurred.",
-          query: query_op,
-          reason: !res.acknowledged ? "not_acknowledged" : "no_match"
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      return res;
-    }
-  }
-  /**
-   * Save multiple documents without performing any default `$set` or `$inc` operations.
-   * Uses MongoDB `updateMany` (unlike {@link save}, which uses `updateOne`).
-   *
-   * @param query      The database query / path to the documents.
-   * @param operation  The MongoDB update document or pipeline (e.g. `{ $set: { ... } }`).
-   * @param opts       Additional options, see {@link Collection.SaveManyOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note The `opts.upsert` option defaults to `false` (unlike {@link save}, which defaults to `true`).
-   * @note When `opts.return` is truthy, this performs a **follow-up** {@link list} with the same `query`
-   *       to return the (post-update) documents. This is **less efficient** than `save(..., { return: true })`
-   *       because it requires an additional list query after the write.
-   * @note If the follow-up `list()` fails:
-   *       - with `opts.throw !== false`, it will throw a {@link Collection.ListError};
-   *       - with `opts.throw === false`, it will return a {@link Collection.ListError}.
-   *
-   * @returns
-   * - When `opts.bulk === true`: an unexecuted bulk operation (`{ updateMany: ... }`).
-   * - When `opts.return` is falsy: {@link mongodb.UpdateResult} on success; or a {@link Collection.SaveError} when `throw:false`.
-   * - When `opts.return` is truthy: the matched/updated docs (via `list()`); or
-   *   - a {@link Collection.SaveError} when the write fails and `throw:false`, or
-   *   - a {@link Collection.ListError} when the follow-up read fails and `throw:false`.
-   *
-   * @throws {Collection.SaveError} Only when `opts.throw !== false` and the write fails.
-   * @throws {Collection.ListError} Only when `opts.throw !== false` and the follow-up list fails.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or the collection was misused.
-   *
-   * @docs
-   */
-  async save_many(query, operation, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    if (!this._is_operator_update_or_pipeline(operation)) {
-      throw new import_errors.InvalidUsageError({
-        message: "Plain replacement documents are not allowed for 'save_many()' (uses updateMany). Pass an operator update or aggregation pipeline. To replace documents, call 'replace_many()'.",
-        reason: "invalid_update_document",
-        field: "operation"
-      });
-    }
-    const query_op = this._init_query(query, false, "query");
-    const throw_errors = opts?.throw ?? true;
-    const retry = opts?.retry;
-    const upsert = opts?.upsert ?? false;
-    if (this.ttl_enabled && opts?.apply_ttl !== false) {
-      this._apply_ttl_to_operation(operation, upsert);
-    }
-    if (this.record_version != null) {
-      this._apply_record_version_to_operation(operation, upsert);
-    }
-    if (opts?.bulk) {
-      const b_op = {
-        updateMany: {
-          filter: query_op,
-          update: operation,
-          upsert
-        }
-      };
-      return b_op;
-    }
-    let write;
-    try {
-      write = await this._with_retry(() => this._col.updateMany(query_op, operation, this.get_operation_options({
-        upsert,
-        ...typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {}
-      })), retry);
-    } catch (e) {
-      const err = new Collection.SaveError({
-        message: "Update-many failed due to an unexpected error.",
-        query: query_op,
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-    if (!write.acknowledged || write.matchedCount === 0 && write.upsertedCount === 0) {
-      const err = new Collection.SaveError({
-        message: !write.acknowledged ? "Document write was not acknowledged." : "No document matched the filter and no upsert occurred.",
-        query: query_op,
-        reason: !write.acknowledged ? "not_acknowledged" : "no_match"
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-    if (!opts?.return) {
-      return write;
-    }
-    const follow = typeof opts.return === "object" ? opts.return : {};
-    const out = await this.list(query, {
-      ...follow,
-      // copy control fields from the write options
-      throw: opts.throw,
-      retry: opts.retry,
-      timeout: opts.timeout
-      // Note: we intentionally do NOT set cursor/page_info (they're excluded in SaveManyReturnOpts).
-    });
-    return out;
-  }
-  /**
-   * Build an aggregation replacement pipeline that preserves _id on matches and
-   * applies versioning/TTL consistently with non-pipeline paths.
-   *
-   * - On matches: preserve stored `__record_version` and (for static TTL) stored `__ttl_timestamp`.
-   * - On upserts:
-   *   - `__record_version`: respect user value if provided, else stamp `this.record_version`.
-   *   - `__ttl_timestamp`:
-   *       • sliding TTL  → always set to "now"
-   *       • static  TTL  → respect user value if provided, else set to "now"
-   *
-   * @param base_replacement A shallow clone of the user replacement. For replace_many, pass without `_id`.
-   * @param upsert           Whether the write is an upsert.
-   * @param apply_ttl        Whether TTL logic should be applied (`this.ttl_enabled && opts?.apply_ttl !== false`).
-   * @returns A MongoDB aggregation pipeline that performs the replacement.
-   */
-  _build_replace_pipeline(base_replacement, upsert, apply_ttl) {
-    const now = /* @__PURE__ */ new Date();
-    const merge_objects = [
-      base_replacement,
-      {
-        $cond: [
-          { $ne: ["$_id", null] },
-          { _id: "$_id" },
-          {}
-        ]
-      }
-    ];
-    if (this.record_version != null) {
-      merge_objects.push({ __old_rv: "$__record_version" });
-    }
-    if (apply_ttl) {
-      merge_objects.push({ __old_ttl: "$__ttl_timestamp" });
-    } else {
-      merge_objects.push({ __ttl_timestamp: "$__ttl_timestamp" });
-    }
-    const pipeline = [
-      { $replaceWith: { $mergeObjects: merge_objects } }
-    ];
-    if (this.record_version != null) {
-      pipeline.push({
-        $set: {
-          /**
-           * Matches:
-           *   Prefer stored version (`__old_rv`), otherwise keep any user-provided value.
-           * Upserts:
-           *   Respect user-provided value if present; otherwise default to `this.record_version`.
-           */
-          __record_version: {
-            $cond: [
-              { $ne: ["$__old_rv", null] },
-              "$__old_rv",
-              upsert ? { $ifNull: ["$__record_version", this.record_version] } : "$__record_version"
-            ]
-          }
-        }
-      });
-    }
-    if (apply_ttl) {
-      pipeline.push({
-        $set: this.sliding_ttl ? { __ttl_timestamp: now } : {
-          __ttl_timestamp: {
-            $cond: [
-              { $ne: ["$__old_ttl", null] },
-              "$__old_ttl",
-              { $ifNull: ["$__ttl_timestamp", now] }
-            ]
-          }
-        }
-      });
-    }
-    pipeline.push({ $unset: ["__old_rv", "__old_ttl"] });
-    return pipeline;
-  }
-  /**
-   * Replace a single document.
-   * Accepts a replacement document only (no update operators/pipelines).
-   *
-   * Internally uses an aggregation pipeline to emulate a full replacement while preserving `_id`
-   * for matched documents and applying record-version/TTL semantics consistently.
-   *
-   * @param query       The match filter.
-   * @param replacement The replacement document, no `$` operators.
-   * @param opts        Options, see {@link Collection.ReplaceOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note The `opts.upsert` option defaults to `true`.
-   * @note TTL semantics:
-   *       - When `opts.apply_ttl === false` (or TTL is disabled), the existing TTL is preserved for matched docs.
-   *       - With sliding TTL, `__ttl_timestamp` is refreshed on every write.
-   *       - With static TTL, matched docs keep their original TTL; upserts receive a fresh timestamp.
-   *
-   * @warning Updating the document id `_id` will cause undefined behaviour on matches. On matched documents,
-   *          a user-supplied `_id` is ignored and the existing `_id` is preserved. On true upserts, a
-   *          user-supplied `_id` is allowed and will be used by the server.
-   *
-   * @returns
-   * - When `opts.bulk === true`: an unexecuted bulk operation.
-   * - When `opts.return === true`: the **updated** document; or a {@link Collection.SaveError} when `throw:false` and a write failure occurs.
-   * - Otherwise: {@link mongodb.UpdateResult} on success; or a {@link Collection.SaveError} when `throw:false` and a write failure occurs.
-   *
-   * @throws {Collection.SaveError} Only when `opts.throw !== false` and the write fails.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async replace(query, replacement, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    if (this._is_operator_update_or_pipeline(replacement)) {
-      throw new import_errors.InvalidUsageError({
-        message: "The 'replace()' method accepts a replacement document only (no update operators or pipelines).",
-        reason: "invalid_replacement_document",
-        field: "replacement"
-      });
-    }
-    const query_op = this._init_query(query, false, "query");
-    const throw_errors = opts?.throw ?? true;
-    const retry = opts?.retry;
-    const upsert = opts?.upsert ?? true;
-    const apply_ttl = this.ttl_enabled && opts?.apply_ttl !== false;
-    const base_replacement = { ...replacement };
-    if (upsert === false) {
-      delete base_replacement._id;
-    }
-    const pipeline = this._build_replace_pipeline(base_replacement, upsert, apply_ttl);
-    if (opts?.bulk) {
-      const b_op = {
-        updateOne: {
-          filter: query_op,
-          update: pipeline,
-          upsert
-        }
-      };
-      return b_op;
-    }
-    if (opts?.return) {
-      let res;
-      try {
-        res = await this._with_retry(() => this._col.findOneAndUpdate(query_op, pipeline, this.get_operation_options({
-          upsert,
-          returnDocument: mongodb.ReturnDocument.AFTER,
-          includeResultMetadata: false,
-          ...typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {}
-        })), retry);
-      } catch (e) {
-        const err = new Collection.SaveError({
-          message: "Replace failed due to an unexpected error.",
-          query: query_op,
-          reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-          cause: e
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      if (!res) {
-        const err = new Collection.SaveError({
-          message: "Document write was not acknowledged.",
-          query: query_op,
-          reason: "not_acknowledged"
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      try {
-        const processed = await this.apply_on_load(res, {
-          projection: void 0,
-          persist: true,
-          await_persist: true
-        });
-        return processed;
-      } catch (e) {
-        const err = new Collection.SaveError({
-          message: "Replace succeeded but post-load processing failed.",
-          query: query_op,
-          reason: "post_process_failed",
-          cause: e
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-    }
-    let write;
-    try {
-      write = await this._with_retry(() => this._col.updateOne(query_op, pipeline, this.get_operation_options({
-        upsert,
-        ...typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {}
-      })), retry);
-    } catch (e) {
-      const err = new Collection.SaveError({
-        message: "Replace failed due to an unexpected error.",
-        query: query_op,
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-    if (!write.acknowledged || write.matchedCount === 0 && write.upsertedCount === 0) {
-      const err = new Collection.SaveError({
-        message: !write.acknowledged ? "Document write was not acknowledged." : "No document matched the filter and no upsert occurred.",
-        query: query_op,
-        reason: !write.acknowledged ? "not_acknowledged" : "no_match"
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-    return write;
-  }
-  /**
-   * Replace multiple documents matched by `query`.
-   * Accepts a **replacement document only** (no update operators or pipelines).
-   *
-   * Internally uses an aggregation pipeline to emulate a full replacement while preserving `_id`
-   * for matched documents and applying record-version/TTL semantics consistently.
-   *
-   * @param query        The match filter.
-   * @param replacement  The replacement document, no `$` operators.
-   * @param opts         Options, see {@link Collection.ReplaceManyOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note The `opts.upsert` option defaults to `false` (unlike {@link replace}, which defaults to `true`).
-   * @note When `opts.return` is truthy, this performs a **follow-up** {@link list} with the same `query`
-   *       to return the (post-update) documents. This is **less efficient** than `replace(..., { return: true })`
-   *       because it requires an additional list query after the write.
-   * @note TTL semantics:
-   *       - When `opts.apply_ttl === false` (or TTL is disabled), the existing TTL is preserved for matched docs.
-   *       - With sliding TTL, `__ttl_timestamp` is refreshed on every write.
-   *       - With static TTL, matched docs keep their original TTL; upserts receive a fresh timestamp.
-   *
-   * @warning The `_id` field is handled with special care:
-   *          - Any `_id` present in the `replacement` is **ignored/stripped** for `replace_many`.
-   *            This prevents attempts to change immutable ids across multiple documents.
-   *          - For matched documents, the existing `_id` is always preserved.
-   *          - For true upserts (`opts.upsert === true` when no match occurs), the server will
-   *            generate a new `_id`. If you need to upsert with a caller-chosen `_id`, use
-   *            {@link replace} (single-document) instead.
-   *
-   * @returns
-   * - When `opts.bulk === true`: an unexecuted bulk operation (`{ updateMany: ... }`).
-   * - When `opts.return` is falsy: {@link mongodb.UpdateResult} on success; or a
-   *   {@link Collection.SaveError} when `throw:false` and a write failure occurs.
-   * - When `opts.return` is truthy: the matched/updated docs (via a follow-up {@link list});
-   *   or a {@link Collection.SaveError} / {@link Collection.ListError} when `throw:false`.
-   *
-   * @throws {Collection.SaveError} Only when `opts.throw !== false` and the write fails.
-   * @throws {Collection.ListError} Only when `opts.throw !== false` and the follow-up list fails.
-   * @throws {InvalidUsageError} (always) When arguments are invalid or the collection was misused.
-   *
-   * @docs
-   */
-  async replace_many(query, replacement, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    if (this._is_operator_update_or_pipeline(replacement)) {
-      throw new import_errors.InvalidUsageError({
-        message: "The 'replace_many()' method accepts a replacement document only (no update operators or pipelines).",
-        reason: "invalid_replacement_document",
-        field: "replacement"
-      });
-    }
-    const query_op = this._init_query(query, false, "query");
-    const throw_errors = opts?.throw ?? true;
-    const retry = opts?.retry;
-    const upsert = opts?.upsert ?? false;
-    const apply_ttl = this.ttl_enabled && opts?.apply_ttl !== false;
-    const base_replacement = { ...replacement };
-    delete base_replacement._id;
-    const pipeline = this._build_replace_pipeline(base_replacement, upsert, apply_ttl);
-    if (opts?.bulk) {
-      const b_op = {
-        updateMany: {
-          filter: query_op,
-          update: pipeline,
-          upsert
-        }
-      };
-      return b_op;
-    }
-    let write;
-    try {
-      write = await this._with_retry(() => this._col.updateMany(query_op, pipeline, this.get_operation_options({
-        upsert,
-        ...typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {}
-      })), retry);
-    } catch (e) {
-      const err = new Collection.SaveError({
-        message: "Replace-many failed due to an unexpected error.",
-        query: query_op,
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-    if (!write.acknowledged || write.matchedCount === 0 && write.upsertedCount === 0) {
-      const err = new Collection.SaveError({
-        message: !write.acknowledged ? "Document write was not acknowledged." : "No document matched the filter and no upsert occurred.",
-        query: query_op,
-        reason: !write.acknowledged ? "not_acknowledged" : "no_match"
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-    if (!opts?.return) {
-      return write;
-    }
-    const follow = typeof opts.return === "object" ? opts.return : {};
-    const out = await this.list(query, {
-      ...follow,
-      throw: opts.throw,
-      retry: opts.retry,
-      timeout: opts.timeout
-    });
-    return out;
-  }
-  /**
-   * Delete a document of the collection.
-   *
-   * @param query The database query to the document.
-   * @param opts Additional options, see {@link Collection.DeleteOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @returns
-   * - An unexecuted bulk operation object if `bulk === true`.
-   * - A {@link Collection.DeleteError} when occurred and `opts.throw === false`.
-   * - A {@link mongodb.DeleteResult}.
-   *
-   * @throws {Collection.DeleteError} When `opts.throw !== false` and if the deletion was not acknowledged, this does not check against the deleted document count.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async delete(query, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const throw_errors = opts?.throw ?? true;
-    const query_op = this._init_query(query, false, "query");
-    if (opts != null && opts.bulk) {
-      const b_op = {
-        deleteOne: {
-          filter: query_op
-        }
-      };
-      return b_op;
-    } else {
-      let res;
-      try {
-        res = await this._with_retry(() => this._col.deleteOne(query_op, this.get_operation_options(typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {})), opts?.retry);
-      } catch (e) {
-        const err = new Collection.DeleteError({
-          message: `Failed to delete document(s) in collection "${this.name}".`,
-          query: query_op,
-          reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-          cause: e
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      if (!res.acknowledged) {
-        const err = new Collection.DeleteError({
-          message: `Failed to delete document(s) in collection "${this.name}".`,
-          query: query_op,
-          reason: "not_acknowledged"
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      return res;
-    }
-  }
-  /**
-   * Delete multiple documents matching the query.
-   *
-   * @param query The database query to the document(s).
-   * @param opts Additional options, see {@link Collection.DeleteOpts}.
-   * @param allow_empty_query When `true`, allows an empty query (i.e. `{}`) to be passed, which would otherwise throw an error.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @returns
-   * - An unexecuted bulk operation object if `bulk === true`.
-   * - A {@link Collection.DeleteError} when occurred and `opts.throw == false`.
-   * - A {@link mongodb.DeleteResult}.
-   *
-   * @throws {Collection.DeleteError} When `opts.throw !== false` and if the deletion was not acknowledged, this does not check against the deleted document count.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async delete_many(query, opts, allow_empty_query = false) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const throw_errors = opts?.throw ?? true;
-    const query_op = this._init_query(query, allow_empty_query, "query");
-    if (opts != null && opts.bulk) {
-      const b_op = {
-        deleteMany: {
-          filter: query_op
-        }
-      };
-      return b_op;
-    } else {
-      let res;
-      try {
-        res = await this._with_retry(() => this._col.deleteMany(query_op, this.get_operation_options(typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {})), opts?.retry);
-      } catch (e) {
-        const err = new Collection.DeleteError({
-          message: `Failed to delete document(s) in collection "${this.name}".`,
-          query: query_op,
-          reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-          cause: e
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      if (!res.acknowledged) {
-        const err = new Collection.DeleteError({
-          message: `Failed to delete document(s) in collection "${this.name}".`,
-          query: query_op,
-          reason: "not_acknowledged"
-        });
-        if (throw_errors)
-          throw err;
-        return err;
-      }
-      return res;
-    }
-  }
-  /**
-   * Delete all documents in the collection.
-   *
-   * @param opts Additional options, see {@link Collection.DeleteOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @returns
-   * - An unexecuted bulk operation object if `bulk === true`.
-   * - A {@link Collection.DeleteError} when occurred and `opts.throw == false`.
-   * - A {@link mongodb.DeleteResult}.
-   *
-   * @throws {Collection.DeleteError} When `opts.throw !== false` and if the deletion was not acknowledged, this does not check against the deleted document count.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async delete_all(opts) {
-    return this.delete_many({}, opts, true);
-  }
-  /**
-   * Delete all documents from the collection and drop the collection.
-   *
-   * @note This function is not supported for transaction based collections.
-   *
-   * @param opts Additional options, see {@link Collection.DeleteOpts}.
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @returns
-   * - A {@link Collection.DeleteError} when occurred and `opts.throw === false`.
-   * - Undefined upon success.
-   *
-   * @throws {Collection.DeleteError} When `opts.throw !== false` and if the deletion was not acknowledged, this does not check against the deleted document count.
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async delete_collection(opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    this.assert_not_transaction_based();
-    const throw_errors = opts?.throw ?? true;
-    let res;
-    try {
-      res = await this._with_retry(() => this._col.drop(this.get_operation_options(typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {})), opts?.retry);
-    } catch (e) {
-      if (e && typeof e === "object" && (e?.code === 26 || e?.codeName === "NamespaceNotFound")) {
-        return void 0;
-      }
-      const err = new Collection.DeleteError({
-        message: `Failed to drop collection "${this.name}".`,
-        query: {},
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-    if (!res) {
-      const err = new Collection.DeleteError({
-        message: `Failed to drop collection "${this.name}", detected by a falsy return.`,
-        query: {},
-        reason: "not_acknowledged"
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-  }
-  // /**
-  //  * @todo implement
-  //  * Enhanced bulk operations with retry logic for failed operations
-  //  * @param operations - Array of bulk write operations
-  //  * @param retries - Number of retry attempts for failed operations. Set to -1 to disable retries. Default is 3.
-  //  * @returns Simplified BulkWriteResult with aggregated counts from all attempts
-  //  */
-  // async bulk_operations(
-  //     operations: any[] = [],
-  //     retries: number = 3
-  // ): Promise<{
-  //     ok: boolean;
-  //     inserted_count: number;
-  //     matched_count: number;
-  //     modified_count: number;
-  //     deleted_count: number;
-  //     upserted_count: number;
-  //     upserted_ids: { [key: number]: any };
-  //     inserted_ids: { [key: number]: any };
-  //     failed_operations: number[];
-  //     errors?: any[];
-  // }> {
-  //     if (!this.initialized) { await this.init(); }
-  //     this.assert_init();
-  //     // Validate operations
-  //     if (!Array.isArray(operations)) {
-  //         throw new TypeError('Operations must be an array');
-  //     }
-  //     // Return early for empty operations
-  //     if (operations.length === 0) {
-  //         return {
-  //             ok: true,
-  //             inserted_count: 0,
-  //             matched_count: 0,
-  //             modified_count: 0,
-  //             deleted_count: 0,
-  //             upserted_count: 0,
-  //             upserted_ids: {},
-  //             inserted_ids: {},
-  //             failed_operations: []
-  //         };
-  //     }
-  //     // MongoDB bulk write limit
-  //     const MAX_BATCH_SIZE = 100000;
-  //     if (operations.length > MAX_BATCH_SIZE) {
-  //         throw new Error(`Bulk operations exceed MongoDB limit of ${MAX_BATCH_SIZE}. Please batch your operations.`);
-  //     }
-  //     // Initialize aggregated results
-  //     const aggregated_result = {
-  //         ok: true,
-  //         inserted_count: 0,
-  //         matched_count: 0,
-  //         modified_count: 0,
-  //         deleted_count: 0,
-  //         upserted_count: 0,
-  //         upserted_ids: {} as { [key: number]: any },
-  //         inserted_ids: {} as { [key: number]: any },
-  //         failed_operations: [] as number[],
-  //         errors: [] as any[]
-  //     };
-  //     // Track operation status (true = succeeded, false = failed/pending)
-  //     const operation_status: Map<number, boolean> = new Map();
-  //     operations.forEach((_, index) => operation_status.set(index, false));
-  //     // Track latest errors for each operation (will be cleared if operation succeeds)
-  //     const latest_errors: Map<number, any> = new Map();
-  //     // Track operations that need to be executed
-  //     let pending_operations = operations.map((op, index) => ({ op, original_index: index }));
-  //     let attempt_count = 0;
-  //     const max_attempts = retries < 0 ? 1 : retries + 1;
-  //     while (pending_operations.length > 0 && attempt_count < max_attempts) {
-  //         attempt_count++;
-  //         try {
-  //             // Execute bulk operations
-  //             const result = await this._col.bulkWrite(
-  //                 pending_operations.map(item => item.op),
-  //                 { ordered: false } // Use unordered for better error handling
-  //             );
-  //             // Track which operations succeeded in this attempt
-  //             const succeeded_in_this_attempt = new Set<number>();
-  //             // Aggregate successful results
-  //             aggregated_result.inserted_count += result.insertedCount;
-  //             aggregated_result.matched_count += result.matchedCount;
-  //             aggregated_result.modified_count += result.modifiedCount;
-  //             aggregated_result.deleted_count += result.deletedCount;
-  //             aggregated_result.upserted_count += result.upsertedCount;
-  //             // Map inserted/upserted IDs back to original indices
-  //             if (result.insertedIds && typeof result.insertedIds === 'object') {
-  //                 for (const [key, value] of Object.entries(result.insertedIds)) {
-  //                     const idx = parseInt(key);
-  //                     if (!isNaN(idx) && pending_operations[idx]) {
-  //                         const original_index = pending_operations[idx].original_index;
-  //                         aggregated_result.inserted_ids[original_index] = value;
-  //                         succeeded_in_this_attempt.add(original_index);
-  //                     }
-  //                 }
-  //             }
-  //             if (result.upsertedIds && typeof result.upsertedIds === 'object') {
-  //                 for (const [key, value] of Object.entries(result.upsertedIds)) {
-  //                     const idx = parseInt(key);
-  //                     if (!isNaN(idx) && pending_operations[idx]) {
-  //                         const original_index = pending_operations[idx].original_index;
-  //                         aggregated_result.upserted_ids[original_index] = value;
-  //                         succeeded_in_this_attempt.add(original_index);
-  //                     }
-  //                 }
-  //             }
-  //             // Check for write errors
-  //             const write_errors = result.hasWriteErrors?.() ? result.getWriteErrors() : [];
-  //             if (write_errors.length > 0) {
-  //                 aggregated_result.ok = false;
-  //                 // Track failed operations by their indices in current batch
-  //                 const failed_indices_in_batch = new Set(write_errors.map(err => err.index));
-  //                 // Update errors for failed operations
-  //                 for (const error of write_errors) {
-  //                     if (error.index < pending_operations.length) {
-  //                         const original_index = pending_operations[error.index].original_index;
-  //                         latest_errors.set(original_index, {
-  //                             ...error,
-  //                             index: original_index,
-  //                             attempt: attempt_count,
-  //                             timestamp: new Date().toISOString()
-  //                         });
-  //                     }
-  //                 }
-  //                 // Mark operations as succeeded if they weren't in the error list
-  //                 pending_operations.forEach((item, batch_index) => {
-  //                     if (!failed_indices_in_batch.has(batch_index)) {
-  //                         const original_index = item.original_index;
-  //                         operation_status.set(original_index, true);
-  //                         succeeded_in_this_attempt.add(original_index);
-  //                         // Clear any previous errors for this operation
-  //                         latest_errors.delete(original_index);
-  //                     }
-  //                 });
-  //                 // Filter pending operations to only include failed ones
-  //                 if (retries >= 0 && attempt_count < max_attempts) {
-  //                     pending_operations = pending_operations.filter((_, index) => failed_indices_in_batch.has(index));
-  //                     // Add exponential backoff for retries
-  //                     if (pending_operations.length > 0) {
-  //                         const delay = Math.min(1000 * Math.pow(2, attempt_count - 1), 5000);
-  //                         await new Promise(resolve => setTimeout(resolve, delay));
-  //                     }
-  //                 } else {
-  //                     // No more retries, exit
-  //                     break;
-  //                 }
-  //             } else {
-  //                 // All operations in this batch succeeded
-  //                 pending_operations.forEach(item => {
-  //                     operation_status.set(item.original_index, true);
-  //                     succeeded_in_this_attempt.add(item.original_index);
-  //                     // Clear any previous errors for these operations
-  //                     latest_errors.delete(item.original_index);
-  //                 });
-  //                 pending_operations = [];
-  //             }
-  //             // Log successful recoveries for monitoring
-  //             if (attempt_count > 1 && succeeded_in_this_attempt.size > 0) {
-  //                 console.log(`[BulkOps] Recovered ${succeeded_in_this_attempt.size} operations on attempt ${attempt_count}`);
-  //             }
-  //         } catch (error: any) {
-  //             aggregated_result.ok = false;
-  //             // Track error for all pending operations
-  //             const affected_indices = pending_operations.map(item => item.original_index);
-  //             for (const original_index of affected_indices) {
-  //                 latest_errors.set(original_index, {
-  //                     message: error.message || 'Unknown error',
-  //                     code: error.code,
-  //                     attempt: attempt_count,
-  //                     index: original_index,
-  //                     timestamp: new Date().toISOString(),
-  //                     type: 'batch_error'
-  //                 });
-  //             }
-  //             // If retries are disabled or we've exhausted retries, throw
-  //             if (retries < 0 || attempt_count >= max_attempts) {
-  //                 break;
-  //             }
-  //             // Add exponential backoff before retry
-  //             const delay = Math.min(1000 * Math.pow(2, attempt_count - 1), 5000);
-  //             await new Promise(resolve => setTimeout(resolve, delay));
-  //         }
-  //     }
-  //     // Final reconciliation: determine which operations ultimately failed
-  //     aggregated_result.failed_operations = [];
-  //     aggregated_result.errors = [];
-  //     for (const [index, succeeded] of operation_status.entries()) {
-  //         if (!succeeded) {
-  //             aggregated_result.failed_operations.push(index);
-  //             const error = latest_errors.get(index);
-  //             if (error) {
-  //                 aggregated_result.errors.push(error);
-  //             }
-  //         }
-  //     }
-  //     // Sort failed operations for consistency
-  //     aggregated_result.failed_operations.sort((a, b) => a - b);
-  //     // Clean up errors array if empty
-  //     if (aggregated_result.errors.length === 0) {
-  //         delete (aggregated_result as any).errors;
-  //     }
-  //     // If we still have failed operations after all retries, include detailed error
-  //     if (aggregated_result.failed_operations.length > 0) {
-  //         const error = new Error(
-  //             `Bulk operations partially failed: ${aggregated_result.failed_operations.length} of ${operations.length} operations could not be completed after ${attempt_count} attempts. ` +
-  //             `Successfully processed: ${operations.length - aggregated_result.failed_operations.length} operations.`
-  //         );
-  //         (error as any).aggregated_result = aggregated_result;
-  //         (error as any).retry_attempts = attempt_count;
-  //         (error as any).success_rate = ((operations.length - aggregated_result.failed_operations.length) / operations.length * 100).toFixed(2) + '%';
-  //         // Only throw if all operations failed
-  //         if (aggregated_result.failed_operations.length === operations.length) {
-  //             throw error;
-  //         }
-  //         // Log partial failure for monitoring
-  //         console.warn(`[BulkOps] Partial failure:`, (error as any).success_rate, 'success rate');
-  //     } else {
-  //         // Clean up failed operations array.
-  //         delete (aggregated_result as any).failed_operations;
-  //     }
-  //     return aggregated_result;
-  // }
-  /**
-   * Execute bulk write operations.
-   *
-   * @param operations Array of bulk write operations.
-   * @param opts Additional options, see {@link Collection.BulkOpts}
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   *
-   * @returns
-   * - A {@link Collection.BulkError} if occurred and `opts.throw === false`.
-   * - A {@link mongodb.BulkWriteResult}.
-   *
-   * @throws {Collection.BulkError} When `opts.throw !== false` and if the bulk operation failed, this does not check against the bulk write result (this may change in the future).
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async bulk_operations(operations, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    if (!Array.isArray(operations)) {
-      throw new TypeError("Operations must be an array");
-    }
-    if (operations.length > 1e5) {
-      throw new import_errors.InvalidUsageError({
-        message: "Bulk operations exceed MongoDB limit of 100000",
-        reason: "invalid_operations_length"
-      });
-    }
-    const throw_errors = opts?.throw ?? true;
-    if (this.ttl_enabled || this.record_version != null) {
-      const now = /* @__PURE__ */ new Date();
-      for (const op of operations) {
-        if (this.record_version != null) {
-          const rv = this.record_version;
-          if (op.insertOne?.document && typeof op.insertOne.document === "object") {
-            const d = op.insertOne.document;
-            if (d.__record_version == null) {
-              d.__record_version = rv;
-            }
-          } else if (op.replaceOne?.replacement && typeof op.replaceOne.replacement === "object") {
-            if (op.replaceOne.upsert) {
-              const d = op.replaceOne.replacement;
-              if (d.__record_version == null) {
-                d.__record_version = rv;
-              }
-            }
-          } else if (op.updateOne?.update) {
-            if (op.updateOne.upsert)
-              this._apply_record_version_to_operation(op.updateOne.update, true);
-          } else if (op.updateMany?.update) {
-            if (op.updateMany.upsert)
-              this._apply_record_version_to_operation(op.updateMany.update, true);
-          }
-        }
-        if (!this.ttl_enabled)
-          continue;
-        if (op.insertOne?.document && typeof op.insertOne.document === "object") {
-          if (this.sliding_ttl || op.insertOne.document.__ttl_timestamp == null) {
-            op.insertOne.document.__ttl_timestamp = now;
-          }
-          continue;
-        }
-        if (op.replaceOne?.replacement && typeof op.replaceOne.replacement === "object") {
-          if (this.sliding_ttl) {
-            op.replaceOne.replacement.__ttl_timestamp = now;
-          } else if (op.replaceOne.upsert && op.replaceOne.replacement.__ttl_timestamp == null) {
-            op.replaceOne.replacement.__ttl_timestamp = now;
-          }
-          continue;
-        }
-        if (op.updateOne?.update) {
-          this._apply_ttl_to_operation(op.updateOne.update, op.updateOne.upsert);
-          continue;
-        }
-        if (op.updateMany?.update) {
-          this._apply_ttl_to_operation(op.updateMany.update, op.updateMany.upsert);
-          continue;
-        }
-      }
-    }
-    try {
-      return await this._with_retry(() => this._col.bulkWrite(operations, this.get_operation_options({
-        ordered: true,
-        ...typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {}
-      })), opts?.retry);
-    } catch (e) {
-      const err = new Collection.BulkError({
-        message: "Bulk operations failed due to an unexpected error.",
-        query: {},
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-  }
-  /**
-   * Execute an aggregation pipeline.
-   *
-   * @param pipeline MongoDB aggregation pipeline stages.
-   * @param opts Aggregation options, see {@link Collection.AggregateOpts}
-   *
-   * @note The `opts.throw` option defaults to `true`.
-   * @note This method does not execute the {@link Collection.Opts.on_load}
-   *       and {@link Collection.Opts.on_transform_version} callbacks.
-   *
-   * @returns
-   * - A {@link Collection.AggregateError} if occurred and `opts.throw === false`.
-   * - An {@link mongodb.AggregationCursor} if `opts.cursor === true`.
-   * - An array of document results.
-   *
-   * @throws {Collection.AggregateError} When `opts.throw !== false` and if the aggregate operation failed, this does not check against the aggregate result (this may change in the future).
-   * @throws {InvalidUsageError} (always) When the provided argument(s) are invalid or if the collection was not used properly.
-   *
-   * @docs
-   */
-  async aggregate(pipeline, opts) {
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    this.assert_not_finalized();
-    const throw_errors = opts?.throw ?? true;
-    try {
-      const cursor = await this._with_retry(() => this._col.aggregate(pipeline, this.get_operation_options(typeof opts?.timeout === "number" ? { maxTimeMS: opts.timeout } : {})), opts?.retry);
-      if (typeof opts?.timeout === "number" && typeof cursor.maxTimeMS === "function") {
-        cursor.maxTimeMS(opts.timeout);
-      }
-      if (opts?.cursor)
-        return cursor;
-      const arr = await this._with_retry(() => cursor.toArray(), opts?.retry);
-      return arr;
-    } catch (e) {
-      const err = new Collection.AggregateError({
-        message: "Aggregate operation failed due to an unexpected error.",
-        query: {},
-        reason: this._should_retry_error(e) ? Collection.Retry.get_attempts(opts?.retry) > 1 ? "retries_exhausted" : "retryable" : "unknown",
-        cause: e
-      });
-      if (throw_errors)
-        throw err;
-      return err;
-    }
-  }
-  /**
-   * Clean a document from all default system attributes.
-   * @param doc The document to clean.
-   * @returns The cleaned document without system attributes.
-   *
-   * @docs
-   */
-  clean(doc) {
-    if (doc == null) {
-      return doc;
-    }
-    if (typeof doc === "object") {
-      const out = { ...doc };
-      delete out._id;
-      delete out._path;
-      if (out.__ttl_timestamp != null) {
-        delete out.__ttl_timestamp;
-      }
-      if (out.__record_version != null) {
-        delete out.__record_version;
-      }
-      return out;
-    }
-    return doc;
-  }
-  // ---------------------------------------------------------
-  // Sessions & transactions.
-  // ---------------------------------------------------------
-  /**
-   * Start a new transaction by creating a TransactionCollection instance.
-   * @returns A new TransactionCollection instance with transaction capabilities.
-   *
-   * @docs
-   */
-  async start_transaction() {
-    if (!this.db.client) {
-      throw new import_errors.InvalidUsageError({
-        message: "Database client is not initialized, ensure the parent 'volt.Server' is initialized.",
-        reason: "client_not_connected"
-      });
-    }
-    if (!this.initialized) {
-      await this.init();
-    }
-    this.assert_init();
-    return new TransactionCollection({
-      derived_collection: this,
-      transaction_based: true
-    });
-  }
-  // ------------------- DEPRECATED -------------------------
-  /** Prepare a _path based regex operation. @deprecated */
-  prepare_path_regex_filter(path) {
-    while (path.length > 0 && path.charAt(path.length - 1) === "/") {
-      path = path.substring(0, path.length - 1);
-    }
-    if (path.length == 0) {
-      throw new import_errors.InvalidUsageError({
-        message: `Invalid path '${path}'`,
-        reason: "invalid_path"
-      });
-    }
-    if (path.length > 1e3) {
-      throw new import_errors.InvalidUsageError({
-        message: `Path too long (${path.length})`,
-        reason: "invalid_path"
-      });
-    }
-    const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const filter = {
-      _path: {
-        $regex: `^${escapeRegExp(path)}/`
-        // $options: 'i'  // Case insensitive for consistency
-      }
-    };
-    return filter;
-  }
-}
-(function(Collection2) {
-  let Retry;
-  (function(Retry2) {
-    function get_attempts(retry) {
-      return Math.max(1, Math.min(100, typeof retry === "number" ? retry : !retry ? 1 : retry.attempts));
-    }
-    Retry2.get_attempts = get_attempts;
-    function normalize(retry) {
-      const base = typeof retry === "number" ? { attempts: retry } : typeof retry === "object" ? retry ?? { attempts: 1 } : { attempts: 1 };
-      let attempts = Number(base.attempts);
-      if (!Number.isFinite(attempts))
-        attempts = 1;
-      attempts = Math.max(1, Math.min(100, attempts));
-      const initial_delay = base.initial_delay ?? 100;
-      const max_delay = base.max_delay ?? 1e3;
-      const backoff_factor = base.backoff_factor ?? 2;
-      const jitter_ratio = 0.2;
-      return {
-        attempts,
-        initial_delay,
-        max_delay,
-        backoff_factor,
-        jitter_ratio
-      };
-    }
-    Retry2.normalize = normalize;
-    function compute_backoff_delay(attempt_index, params) {
-      const base = Math.min(params.max_delay, (params.initial_delay <= 0 ? 0 : params.initial_delay) * Math.pow(Math.max(1, params.backoff_factor), attempt_index));
-      if (base <= 0)
-        return 0;
-      const jitter = (Math.random() * 2 - 1) * (params.jitter_ratio * base);
-      const delay = Math.max(0, Math.min(params.max_delay, base + jitter));
-      return Math.floor(delay);
-    }
-    Retry2.compute_backoff_delay = compute_backoff_delay;
-  })(Retry = Collection2.Retry || (Collection2.Retry = {}));
-  class OperationError extends Error {
-    /** The error message. */
-    message;
-    query;
-    reason;
-    /** An optional error that caused this error. */
-    cause;
-    /** Construct a not found error. */
-    constructor(opts) {
-      super(opts.message);
-      this.message = opts.message;
-      this.name = "OperationError";
-      this.query = opts.query;
-      this.reason = opts.reason;
-      this.cause = opts.cause;
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.OperationError = OperationError;
-  class NotFoundError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "NotFoundError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.NotFoundError = NotFoundError;
-  class OnTransformError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "OnTransformError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.OnTransformError = OnTransformError;
-  class OnLoadError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "OnLoadError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.OnLoadError = OnLoadError;
-  class CountError extends OperationError {
-    /**
-     * Construct a {@link CountError}.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "CountError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.CountError = CountError;
-  class ListError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "ListError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.ListError = ListError;
-  class ExistsError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "ExistsError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.ExistsError = ExistsError;
-  class LoadError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "LoadError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.LoadError = LoadError;
-  class SaveError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "SaveError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.SaveError = SaveError;
-  class DeleteError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "DeleteError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.DeleteError = DeleteError;
-  class BulkError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "BulkError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.BulkError = BulkError;
-  class AggregateError extends OperationError {
-    /**
-     * Constructor method.
-     * @param opts The error options, see {@link OperationError.Opts}.
-     */
-    constructor(opts) {
-      super(opts);
-      this.name = "AggregateError";
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  }
-  Collection2.AggregateError = AggregateError;
-  let Projection;
-  (function(Projection2) {
-    function init(projection) {
-      if (Array.isArray(projection)) {
-        const p = {};
-        for (let i = 0; i < projection.length; i++) {
-          p[projection[i]] = 1;
-        }
-        return p;
-      } else {
-        const p = projection;
-        let has_include = false;
-        let has_exclude = false;
-        for (const [k, v] of Object.entries(p)) {
-          if (v === 1 || v === true) {
-            if (k !== "_id")
-              has_include = true;
-          } else if (v === 0 || v === false) {
-            if (k !== "_id")
-              has_exclude = true;
-          } else {
-            throw new import_errors.InvalidUsageError({
-              message: `Invalid projection value for "${k}": expected 0, 1, true or false.`,
-              reason: "invalid_projection"
-            });
-          }
-          if (has_include && has_exclude) {
-            throw new import_errors.InvalidUsageError({
-              message: "Invalid projection: cannot mix inclusion and exclusion (except for _id).",
-              reason: "invalid_projection"
-            });
-          }
-        }
-        return p;
-      }
-    }
-    Projection2.init = init;
-  })(Projection = Collection2.Projection || (Collection2.Projection = {}));
-  {
-  }
-})(Collection || (Collection = {}));
-class TransactionCollection extends Collection {
-  /**
-   * Commit the current transaction.
-   * Implements retry logic for transient errors and unknown commit results.
-   * @throws {InvalidUsageError} If there is no active session or if the transaction has already been finalized.
-   * @throws {Error} If the commit fails after retries or encounters a non-retryable error.
-   *
-   * @docs
-   */
-  async commit() {
-    const session = this._session;
-    if (!session) {
-      throw new import_errors.InvalidUsageError({
-        message: "No active session for this transaction.",
-        reason: "no_session"
-      });
-    }
-    if (this.is_finalized_transaction) {
-      throw new import_errors.InvalidUsageError({
-        message: "Transaction has already been finalized.",
-        reason: "transaction_finalized"
-      });
-    }
-    const max_retries_unknown = 10;
-    const base_delay_ms = 20;
-    const max_delay_ms = 1e3;
-    for (let attempt = 0; attempt <= max_retries_unknown; attempt++) {
-      try {
-        await session.commitTransaction();
-        this.is_finalized_transaction = true;
-        try {
-          await session.endSession();
-        } finally {
-          this._session = void 0;
-        }
-        return;
-      } catch (err) {
-        const has_label = (label) => {
-          if (!err || typeof err !== "object") {
-            return false;
-          }
-          if (typeof err?.hasErrorLabel === "function") {
-            try {
-              return !!err.hasErrorLabel(label);
-            } catch {
-            }
-          }
-          return Array.isArray(err?.errorLabels) && err.errorLabels.includes(label);
-        };
-        const unknown_commit = has_label("UnknownTransactionCommitResult");
-        const transient = has_label("TransientTransactionError");
-        const is_networkish = err?.name === "MongoNetworkError" || err?.name === "MongoNetworkTimeoutError";
-        if ((unknown_commit || is_networkish) && attempt < max_retries_unknown) {
-          const delay = Math.min(max_delay_ms, base_delay_ms * Math.pow(2, attempt));
-          await new Promise((res) => setTimeout(res, delay));
-          continue;
-        }
-        if (transient) {
-          try {
-            await session.abortTransaction();
-          } catch {
-          }
-          this.is_finalized_transaction = true;
-          try {
-            await session.endSession();
-          } finally {
-            this._session = void 0;
-          }
-          const e = new Error(`TransientTransactionError during commit; transaction aborted. Retry the entire transaction. ${err?.message ?? ""}`);
-          e.codeName = err?.codeName;
-          e.errorLabels = err?.errorLabels;
-          throw e;
-        }
-        if ((unknown_commit || is_networkish) && attempt >= max_retries_unknown) {
-          this.is_finalized_transaction = true;
-          try {
-            await session.endSession();
-          } finally {
-            this._session = void 0;
-          }
-          const e = new Error(`Commit failed after ${attempt + 1} attempt(s) with unknown outcome; last error: ${err?.message ?? err}`);
-          e.codeName = err?.codeName;
-          e.errorLabels = err?.errorLabels;
-          throw e;
-        }
-        this.is_finalized_transaction = true;
-        try {
-          await session.endSession();
-        } finally {
-          this._session = void 0;
-        }
-        throw err;
-      }
-    }
-  }
-  /**
-   * Abort the current transaction.
-   * Implements retry logic for transient errors.
-   * @throws {InvalidUsageError} If there is no active session or if the transaction has already been finalized.
-   * @throws {Error} If the abort fails after retries or encounters a non-retryable error.
-   *
-   * @docs
-   */
-  async abort() {
-    const session = this._session;
-    if (!session) {
-      throw new import_errors.InvalidUsageError({
-        message: "No active session for this transaction.",
-        reason: "no_session"
-      });
-    }
-    if (this.is_finalized_transaction) {
-      throw new import_errors.InvalidUsageError({
-        message: "Transaction has already been finalized.",
-        reason: "transaction_finalized"
-      });
-    }
-    const max_retries = 5;
-    const base_delay_ms = 20;
-    const max_delay_ms = 500;
-    for (let attempt = 0; attempt <= max_retries; attempt++) {
-      try {
-        await session.abortTransaction();
-        this.is_finalized_transaction = true;
-        try {
-          await session.endSession();
-        } finally {
-          this._session = void 0;
-        }
-        return;
-      } catch (err) {
-        if (err?.codeName === "NoSuchTransaction") {
-          this.is_finalized_transaction = true;
-          try {
-            await session.endSession();
-          } finally {
-            this._session = void 0;
-          }
-          return;
-        }
-        const has_label = (label) => {
-          if (!err || typeof err !== "object") {
-            return false;
-          }
-          if (typeof err?.hasErrorLabel === "function") {
-            try {
-              return !!err.hasErrorLabel(label);
-            } catch {
-            }
-          }
-          return Array.isArray(err?.errorLabels) && err.errorLabels.includes(label);
-        };
-        const transient = has_label("TransientTransactionError");
-        const is_networkish = err?.name === "MongoNetworkError" || err?.name === "MongoNetworkTimeoutError";
-        if ((transient || is_networkish) && attempt < max_retries) {
-          const delay = Math.min(max_delay_ms, base_delay_ms * Math.pow(2, attempt));
-          await new Promise((res) => setTimeout(res, delay));
-          continue;
-        }
-        this.is_finalized_transaction = true;
-        try {
-          await session.endSession();
-        } finally {
-          this._session = void 0;
-        }
-        throw err;
-      }
-    }
-  }
-  /**
-   * Cleanup method for proper resource management
-   * Can be called manually or via async disposal
-   *
-   * @warning This method aborts the transaction if it is still active.
-   * @docs
-   */
-  async cleanup() {
-    if (this._session && !this.is_finalized_transaction) {
-      try {
-        await this.abort();
-      } catch (error) {
-        console.error("Failed to abort transaction during cleanup:", error);
-        if (this._session) {
-          try {
-            await this._session.endSession();
-          } catch (endError) {
-            console.error("Failed to end session during cleanup:", endError);
-          }
-        }
-      } finally {
-        this.is_finalized_transaction = true;
-      }
-    }
-  }
-  // Support for async disposal (TC39 proposal)
-  async [Symbol.asyncDispose]() {
-    await this.cleanup();
-  }
-  /**
-   * Check if the transaction is still active (not finalized).
-   * @returns True if the transaction is active, false otherwise.
-   * @docs
-   */
-  is_active() {
-    return this.is_transaction && !this.is_finalized_transaction && this._session != null;
-  }
-}
-async function test_save() {
-  const res = void await test_col.save(
-    { uid: "" },
-    // @ts-ignore
-    { uid: "" },
-    { return: true }
-  );
-  const res_no_throw = await test_col.save(
-    { uid: "" },
-    // @ts-ignore
-    { uid: "" },
-    { return: true, throw: false, bulk: false }
-  );
-  function init_save_opts(opts) {
-    return opts;
-  }
-  const a = init_save_opts({ bulk: true, upsert: true });
-  const b = init_save_opts({ return: false, upsert: true });
-  const b2 = init_save_opts({ return: false, throw: true });
-  const c = init_save_opts({ return: true, upsert: false, throw: false });
-  const e = init_save_opts({ return: true, upsert: true, bulk: true });
-  const res_bulk_op = await test_col.save({ uid: "" }, { uid: "" }, { bulk: true });
-  const res_undef = await test_col.save({ uid: "" }, { uid: "" });
-  const res_doc = await test_col.save({ uid: "" }, { uid: "" }, { return: true });
-  const res_doc_or_undef = await test_col.save({ uid: "" }, { uid: "" }, { return: true, throw: false, upsert: false });
-  async function save_wrapper(doc, bulk) {
-    return await test_col.save({ id: "test" }, { $set: doc }, { bulk });
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  Collection,
-  TransactionCollection
-});