@atscript/db-mongo 0.1.39 → 0.1.41

package/dist/index.d.cts

@@ -0,0 +1,344 @@
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
+import { AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
+import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+
+//#region src/lib/collection-patcher.d.ts
+/**
+ * Context interface for CollectionPatcher.
+ * Decouples the patcher from AsCollection, allowing MongoAdapter to provide this.
+ */
+interface TCollectionPatcherContext {
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  prepareId(id: any): any;
+  createValidator(opts?: Partial<TValidatorOptions>): Validator<any>;
+}
+/**
+ * CollectionPatcher is a small helper that converts a *patch payload* produced
+ * by Atscript into a shape that the official MongoDB driver understands – a
+ * triple of `(filter, update, options)` to be fed to `collection.updateOne()`.
+ *
+ * Supported high‑level operations for *top‑level arrays* (see the attached
+ * spreadsheet in the chat):
+ *
+ * | Payload field | MongoDB operator        | Purpose                                |
+ * |-------------- |-------------------------|----------------------------------------|
+ * | `$replace`    | full `$set`             | Replace the whole array.               |
+ * | `$insert`     | `$push`                 | Append new items (duplicates allowed). |
+ * | `$upsert`     | custom                  | Insert or update by *key* (see TODO).  |
+ * | `$update`     | `$set` + `arrayFilters` | Update array elements matched by *key* |
+ * | `$remove`     | `$pullAll` / `$pull`    | Remove by value or by *key*.           |
+ *
+ * The class walks through the incoming payload, detects which of the above
+ * operations applies to each top‑level array and builds the corresponding
+ * MongoDB update document. Primitive fields are flattened into a regular
+ * `$set` map.
+ */
+declare class CollectionPatcher {
+  private collection;
+  private payload;
+  private ops?;
+  constructor(collection: TCollectionPatcherContext, payload: any, ops?: TFieldOps | undefined);
+  static getKeyProps: typeof getKeyProps;
+  /**
+   * Internal accumulator: filter passed to `updateOne()`.
+   * Filled only with the `_id` field right now.
+   */
+  private filterObj;
+  /** MongoDB *update* document being built. */
+  private updatePipeline;
+  /** Current `$set` stage being populated. */
+  private currentSetStage;
+  /** Additional *options* (mainly `arrayFilters`). */
+  private optionsObj;
+  /**
+   * Entry point – walk the payload, build `filter`, `update` and `options`.
+   *
+   * @returns Helper object exposing both individual parts and
+   *          a `.toArgs()` convenience callback.
+   */
+  preparePatch(): {
+    toArgs: () => [Filter<any>, UpdateFilter<any> | Document[], UpdateOptions];
+    filter: Filter<any>;
+    updateFilter: Document[];
+    updateOptions: UpdateOptions;
+  };
+  /** Builds a MongoDB aggregation expression for an $inc or $mul field op. */
+  private _fieldOpExpr;
+  /**
+   * Helper – lazily create `$set` section and assign *key* → *value*.
+   *
+   * @param key Fully‑qualified dotted path
+   * @param val Value to be written
+   * @private
+   */
+  private _set;
+  /**
+   * Recursively walk through the patch *payload* and convert it into `$set`/…
+   * statements. Top‑level arrays are delegated to {@link parseArrayPatch}.
+   *
+   * @param payload Current payload chunk
+   * @param prefix  Dotted path accumulated so far
+   * @private
+   */
+  private flattenPayload;
+  /**
+   * Dispatch a *single* array patch. Exactly one of `$replace`, `$insert`,
+   * `$upsert`, `$update`, `$remove` must be present – otherwise we throw.
+   *
+   * @param key   Dotted path to the array field
+   * @param value Payload slice for that field
+   * @private
+   */
+  private parseArrayPatch;
+  /**
+   * Build an *aggregation‐expression* that checks equality by **all** keys in
+   * `keys`.  Example output for keys `["id", "lang"]` and bases `a`, `b`:
+   * ```json
+   * { "$and": [ { "$eq": ["$$a.id", "$$b.id"] }, { "$eq": ["$$a.lang", "$$b.lang"] } ] }
+   * ```
+   *
+   * @param keys  Ordered list of key property names
+   * @param left  Base token for *left* expression (e.g. `"$$el"`)
+   * @param right Base token for *right* expression (e.g. `"$$this"`)
+   */
+  private _keysEqual;
+  /**
+   * `$replace` – overwrite the entire array with `input`.
+   *
+   * @param key   Dotted path to the array
+   * @param input New array value (may be `undefined`)
+   * @private
+   */
+  private _replace;
+  /**
+   * `$insert`
+   * - plain append      → $concatArrays
+   * - unique / keyed    → delegate to _upsert (insert-or-update)
+   */
+  private _insert;
+  /**
+   * `$upsert`
+   * - keyed  → remove existing matching by key(s) then append candidate
+   * - unique → $setUnion (deep equality)
+   */
+  private _upsert;
+  /**
+   * `$update`
+   * - keyed       → map array and merge / replace matching element(s)
+   * - non-keyed   → behave like `$addToSet` (insert only when not present)
+   */
+  private _update;
+  /**
+   * `$remove`
+   * - keyed     → filter out any element whose key set matches a payload item
+   * - non-keyed → deep equality remove (`$setDifference`)
+   */
+  private _remove;
+}
+//#endregion
+//#region src/lib/mongo-types.d.ts
+interface TPlainIndex {
+  key: string;
+  name: string;
+  type: "plain" | "unique" | "text";
+  fields: Record<string, 1 | "text">;
+  weights: Record<string, number>;
+}
+interface TSearchIndex {
+  key: string;
+  name: string;
+  type: "dynamic_text" | "search_text" | "vector";
+  definition: TMongoSearchIndexDefinition;
+}
+type TMongoIndex = TPlainIndex | TSearchIndex;
+type TVectorSimilarity = "cosine" | "euclidean" | "dotProduct";
+interface TMongoSearchIndexDefinition {
+  mappings?: {
+    dynamic?: boolean;
+    fields?: Record<string, {
+      type: string;
+      analyzer?: string;
+    }>;
+  };
+  fields?: Array<{
+    path: string;
+    type: "filter" | "vector";
+    similarity?: TVectorSimilarity;
+    numDimensions?: number;
+  }>;
+  analyzer?: string;
+  text?: {
+    fuzzy?: {
+      maxEdits: number;
+    };
+  };
+}
+//#endregion
+//#region src/lib/mongo-adapter.d.ts
+declare class MongoAdapter extends BaseDbAdapter {
+  protected readonly db: Db;
+  protected readonly client?: MongoClient | undefined;
+  private _collection?;
+  /** MongoDB-specific indexes (search, vector) — separate from table.indexes. */
+  protected _mongoIndexes: Map<string, TMongoIndex>;
+  /** Vector search filter associations built during flattening. */
+  protected _vectorFilters: Map<string, string>;
+  /** Default similarity thresholds per vector index (from @db.search.vector.threshold). */
+  protected _vectorThresholds: Map<string, number>;
+  /** Cached search index lookup. */
+  protected _searchIndexesMap?: Map<string, TMongoIndex>;
+  /** Physical field names with @db.default.increment → optional start value. */
+  protected _incrementFields: Map<string, number | undefined>;
+  /** Physical field names that have a non-binary collation (nocase/unicode). */
+  private _collateFields?;
+  /** Capped collection options from @db.mongo.capped. */
+  protected _cappedOptions?: {
+    size: number;
+    max?: number;
+  };
+  /** Whether the schema explicitly defines _id (via @db.mongo.collection or manual _id field). */
+  protected _hasExplicitId: boolean;
+  /** Unique fields accumulated during onFieldScanned, returned via getMetadataOverrides. */
+  private _pendingUniqueFields;
+  constructor(db: Db, client?: MongoClient | undefined);
+  private get _client();
+  /**
+   * Per-client cache: whether transactions are unavailable (standalone MongoDB).
+   * Shared across all adapter instances for the same client so topology is probed once.
+   */
+  private static readonly _txDisabledClients;
+  private get _txDisabled();
+  private set _txDisabled(value);
+  /**
+   * Uses MongoDB's Convenient Transaction API (`session.withTransaction()`).
+   * This handles txnNumber management and automatic retry for
+   * `TransientTransactionError` / `UnknownTransactionCommitResult`.
+   */
+  withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+  private static readonly _noSession;
+  /** Returns `{ session }` opts if inside a transaction, empty object otherwise. */
+  protected _getSessionOpts(): {
+    session: ClientSession;
+  } | Record<string, never>;
+  get collection(): Collection<any>;
+  aggregatePipeline(pipeline: Document[]): AggregationCursor;
+  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  get idType(): "string" | "number" | "objectId";
+  prepareId(id: unknown, _fieldType: unknown): unknown;
+  /**
+   * Convenience method that uses `idType` to transform an ID value.
+   * For use in controllers that don't have access to the field type.
+   */
+  prepareIdFromIdType<D = string | number | ObjectId>(id: string | number | ObjectId): D;
+  supportsNestedObjects(): boolean;
+  supportsNativePatch(): boolean;
+  getValidatorPlugins(): ReturnType<BaseDbAdapter["getValidatorPlugins"]>;
+  getAdapterTableName(_type: unknown): string | undefined;
+  supportsNativeRelations(): boolean;
+  loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], relations: ReadonlyMap<string, TDbRelation>, foreignKeys: ReadonlyMap<string, TDbForeignKey>, tableResolver?: TTableResolver): Promise<void>;
+  /** Returns the context object used by CollectionPatcher. */
+  getPatcherContext(): TCollectionPatcherContext;
+  nativePatch(filter: FilterExpr, patch: unknown, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  onBeforeFlatten(_type: unknown): void;
+  onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
+  getMetadataOverrides(meta: TableMetadata): TMetadataOverrides;
+  onAfterFlatten(): void;
+  /** Returns MongoDB-specific search index map (internal). */
+  getMongoSearchIndexes(): Map<string, TMongoIndex>;
+  /** Returns a specific MongoDB search index by name. */
+  getMongoSearchIndex(name?: string): TMongoIndex | undefined;
+  /** Returns the default similarity threshold for a vector index (from @db.search.vector.threshold). */
+  getVectorThreshold(indexName?: string): number | undefined;
+  getSearchIndexes(): TSearchIndexInfo[];
+  isVectorSearchable(): boolean;
+  search(text: string, query: DbQuery, indexName?: string): Promise<Record<string, unknown>[]>;
+  searchWithCount(text: string, query: DbQuery, indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  vectorSearch(vector: number[], query: DbQuery, indexName?: string): Promise<Record<string, unknown>[]>;
+  vectorSearchWithCount(vector: number[], query: DbQuery, indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  findManyWithCount(query: DbQuery): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  collectionExists(): Promise<boolean>;
+  ensureCollectionExists(): Promise<void>;
+  /**
+   * Wraps an async operation to catch MongoDB duplicate key errors
+   * (code 11000) and rethrow as structured `DbError`.
+   */
+  private _wrapDuplicateKeyError;
+  insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
+  insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
+  findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  count(query: DbQuery): Promise<number>;
+  updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
+  updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  clearCollectionCache(): void;
+  tableExists(): Promise<boolean>;
+  ensureTable(): Promise<void>;
+  syncIndexes(): Promise<void>;
+  syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
+  dropColumns(columns: string[]): Promise<void>;
+  renameTable(oldName: string): Promise<void>;
+  recreateTable(): Promise<void>;
+  dropTable(): Promise<void>;
+  dropViewByName(viewName: string): Promise<void>;
+  dropTableByName(tableName: string): Promise<void>;
+  getDesiredTableOptions(): TExistingTableOption[];
+  getExistingTableOptions(): Promise<TExistingTableOption[]>;
+  destructiveOptionKeys(): ReadonlySet<string>;
+  /** Returns the counters collection used for atomic auto-increment. */
+  protected get _countersCollection(): Collection<{
+    _id: string;
+    seq: number;
+  }>;
+  /** Returns physical field names of increment fields that are undefined in the data. */
+  private _fieldsNeedingIncrement;
+  /**
+   * Atomically allocates `count` sequential values for each increment field
+   * using a counter collection. Returns a map of field → first allocated value.
+   */
+  private _allocateIncrementValues;
+  /** Reads current max value for a single field via $group aggregation. */
+  private _getCurrentFieldMax;
+  /** Allocates increment values for a batch of items, assigning in order. */
+  private _assignBatchIncrements;
+  private _buildFindOptions;
+  /**
+   * Returns MongoDB collation options if any filter field has a non-binary collation.
+   * Uses pre-computed insights when available, falls back to computing them on demand.
+   * Maps: nocase → strength 2 (case-insensitive), unicode → strength 1 (case+accent-insensitive).
+   */
+  private _getCollationOpts;
+  protected _addMongoIndexField(type: TPlainIndex["type"], name: string, field: string, weight?: number): void;
+  protected _setSearchIndex(type: TSearchIndex["type"], name: string | undefined, definition: TMongoSearchIndexDefinition): void;
+  protected _addFieldToSearchIndex(type: TSearchIndex["type"], _name: string | undefined, fieldName: string, analyzer?: string): void;
+}
+//#endregion
+//#region src/lib/mongo-filter.d.ts
+/**
+ * Translates a generic {@link FilterExpr} into a MongoDB-compatible
+ * {@link Filter} document.
+ *
+ * MongoDB's query language is nearly identical to the `FilterExpr` structure,
+ * so this is largely a structural pass-through via the `walkFilter` visitor.
+ */
+declare function buildMongoFilter(filter: FilterExpr): Filter<any>;
+//#endregion
+//#region src/lib/validate-plugins.d.ts
+declare const validateMongoIdPlugin: TValidatorPlugin;
+//#endregion
+//#region src/lib/index.d.ts
+declare function createAdapter(connection: string, _options?: Record<string, unknown>): DbSpace;
+//#endregion
+export { CollectionPatcher, MongoAdapter, TCollectionPatcherContext, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, createAdapter, validateMongoIdPlugin };

package/dist/index.d.mts

@@ -0,0 +1,344 @@
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
+import { AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
+import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+
+//#region src/lib/collection-patcher.d.ts
+/**
+ * Context interface for CollectionPatcher.
+ * Decouples the patcher from AsCollection, allowing MongoAdapter to provide this.
+ */
+interface TCollectionPatcherContext {
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  prepareId(id: any): any;
+  createValidator(opts?: Partial<TValidatorOptions>): Validator<any>;
+}
+/**
+ * CollectionPatcher is a small helper that converts a *patch payload* produced
+ * by Atscript into a shape that the official MongoDB driver understands – a
+ * triple of `(filter, update, options)` to be fed to `collection.updateOne()`.
+ *
+ * Supported high‑level operations for *top‑level arrays* (see the attached
+ * spreadsheet in the chat):
+ *
+ * | Payload field | MongoDB operator        | Purpose                                |
+ * |-------------- |-------------------------|----------------------------------------|
+ * | `$replace`    | full `$set`             | Replace the whole array.               |
+ * | `$insert`     | `$push`                 | Append new items (duplicates allowed). |
+ * | `$upsert`     | custom                  | Insert or update by *key* (see TODO).  |
+ * | `$update`     | `$set` + `arrayFilters` | Update array elements matched by *key* |
+ * | `$remove`     | `$pullAll` / `$pull`    | Remove by value or by *key*.           |
+ *
+ * The class walks through the incoming payload, detects which of the above
+ * operations applies to each top‑level array and builds the corresponding
+ * MongoDB update document. Primitive fields are flattened into a regular
+ * `$set` map.
+ */
+declare class CollectionPatcher {
+  private collection;
+  private payload;
+  private ops?;
+  constructor(collection: TCollectionPatcherContext, payload: any, ops?: TFieldOps | undefined);
+  static getKeyProps: typeof getKeyProps;
+  /**
+   * Internal accumulator: filter passed to `updateOne()`.
+   * Filled only with the `_id` field right now.
+   */
+  private filterObj;
+  /** MongoDB *update* document being built. */
+  private updatePipeline;
+  /** Current `$set` stage being populated. */
+  private currentSetStage;
+  /** Additional *options* (mainly `arrayFilters`). */
+  private optionsObj;
+  /**
+   * Entry point – walk the payload, build `filter`, `update` and `options`.
+   *
+   * @returns Helper object exposing both individual parts and
+   *          a `.toArgs()` convenience callback.
+   */
+  preparePatch(): {
+    toArgs: () => [Filter<any>, UpdateFilter<any> | Document[], UpdateOptions];
+    filter: Filter<any>;
+    updateFilter: Document[];
+    updateOptions: UpdateOptions;
+  };
+  /** Builds a MongoDB aggregation expression for an $inc or $mul field op. */
+  private _fieldOpExpr;
+  /**
+   * Helper – lazily create `$set` section and assign *key* → *value*.
+   *
+   * @param key Fully‑qualified dotted path
+   * @param val Value to be written
+   * @private
+   */
+  private _set;
+  /**
+   * Recursively walk through the patch *payload* and convert it into `$set`/…
+   * statements. Top‑level arrays are delegated to {@link parseArrayPatch}.
+   *
+   * @param payload Current payload chunk
+   * @param prefix  Dotted path accumulated so far
+   * @private
+   */
+  private flattenPayload;
+  /**
+   * Dispatch a *single* array patch. Exactly one of `$replace`, `$insert`,
+   * `$upsert`, `$update`, `$remove` must be present – otherwise we throw.
+   *
+   * @param key   Dotted path to the array field
+   * @param value Payload slice for that field
+   * @private
+   */
+  private parseArrayPatch;
+  /**
+   * Build an *aggregation‐expression* that checks equality by **all** keys in
+   * `keys`.  Example output for keys `["id", "lang"]` and bases `a`, `b`:
+   * ```json
+   * { "$and": [ { "$eq": ["$$a.id", "$$b.id"] }, { "$eq": ["$$a.lang", "$$b.lang"] } ] }
+   * ```
+   *
+   * @param keys  Ordered list of key property names
+   * @param left  Base token for *left* expression (e.g. `"$$el"`)
+   * @param right Base token for *right* expression (e.g. `"$$this"`)
+   */
+  private _keysEqual;
+  /**
+   * `$replace` – overwrite the entire array with `input`.
+   *
+   * @param key   Dotted path to the array
+   * @param input New array value (may be `undefined`)
+   * @private
+   */
+  private _replace;
+  /**
+   * `$insert`
+   * - plain append      → $concatArrays
+   * - unique / keyed    → delegate to _upsert (insert-or-update)
+   */
+  private _insert;
+  /**
+   * `$upsert`
+   * - keyed  → remove existing matching by key(s) then append candidate
+   * - unique → $setUnion (deep equality)
+   */
+  private _upsert;
+  /**
+   * `$update`
+   * - keyed       → map array and merge / replace matching element(s)
+   * - non-keyed   → behave like `$addToSet` (insert only when not present)
+   */
+  private _update;
+  /**
+   * `$remove`
+   * - keyed     → filter out any element whose key set matches a payload item
+   * - non-keyed → deep equality remove (`$setDifference`)
+   */
+  private _remove;
+}
+//#endregion
+//#region src/lib/mongo-types.d.ts
+interface TPlainIndex {
+  key: string;
+  name: string;
+  type: "plain" | "unique" | "text";
+  fields: Record<string, 1 | "text">;
+  weights: Record<string, number>;
+}
+interface TSearchIndex {
+  key: string;
+  name: string;
+  type: "dynamic_text" | "search_text" | "vector";
+  definition: TMongoSearchIndexDefinition;
+}
+type TMongoIndex = TPlainIndex | TSearchIndex;
+type TVectorSimilarity = "cosine" | "euclidean" | "dotProduct";
+interface TMongoSearchIndexDefinition {
+  mappings?: {
+    dynamic?: boolean;
+    fields?: Record<string, {
+      type: string;
+      analyzer?: string;
+    }>;
+  };
+  fields?: Array<{
+    path: string;
+    type: "filter" | "vector";
+    similarity?: TVectorSimilarity;
+    numDimensions?: number;
+  }>;
+  analyzer?: string;
+  text?: {
+    fuzzy?: {
+      maxEdits: number;
+    };
+  };
+}
+//#endregion
+//#region src/lib/mongo-adapter.d.ts
+declare class MongoAdapter extends BaseDbAdapter {
+  protected readonly db: Db;
+  protected readonly client?: MongoClient | undefined;
+  private _collection?;
+  /** MongoDB-specific indexes (search, vector) — separate from table.indexes. */
+  protected _mongoIndexes: Map<string, TMongoIndex>;
+  /** Vector search filter associations built during flattening. */
+  protected _vectorFilters: Map<string, string>;
+  /** Default similarity thresholds per vector index (from @db.search.vector.threshold). */
+  protected _vectorThresholds: Map<string, number>;
+  /** Cached search index lookup. */
+  protected _searchIndexesMap?: Map<string, TMongoIndex>;
+  /** Physical field names with @db.default.increment → optional start value. */
+  protected _incrementFields: Map<string, number | undefined>;
+  /** Physical field names that have a non-binary collation (nocase/unicode). */
+  private _collateFields?;
+  /** Capped collection options from @db.mongo.capped. */
+  protected _cappedOptions?: {
+    size: number;
+    max?: number;
+  };
+  /** Whether the schema explicitly defines _id (via @db.mongo.collection or manual _id field). */
+  protected _hasExplicitId: boolean;
+  /** Unique fields accumulated during onFieldScanned, returned via getMetadataOverrides. */
+  private _pendingUniqueFields;
+  constructor(db: Db, client?: MongoClient | undefined);
+  private get _client();
+  /**
+   * Per-client cache: whether transactions are unavailable (standalone MongoDB).
+   * Shared across all adapter instances for the same client so topology is probed once.
+   */
+  private static readonly _txDisabledClients;
+  private get _txDisabled();
+  private set _txDisabled(value);
+  /**
+   * Uses MongoDB's Convenient Transaction API (`session.withTransaction()`).
+   * This handles txnNumber management and automatic retry for
+   * `TransientTransactionError` / `UnknownTransactionCommitResult`.
+   */
+  withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+  private static readonly _noSession;
+  /** Returns `{ session }` opts if inside a transaction, empty object otherwise. */
+  protected _getSessionOpts(): {
+    session: ClientSession;
+  } | Record<string, never>;
+  get collection(): Collection<any>;
+  aggregatePipeline(pipeline: Document[]): AggregationCursor;
+  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  get idType(): "string" | "number" | "objectId";
+  prepareId(id: unknown, _fieldType: unknown): unknown;
+  /**
+   * Convenience method that uses `idType` to transform an ID value.
+   * For use in controllers that don't have access to the field type.
+   */
+  prepareIdFromIdType<D = string | number | ObjectId>(id: string | number | ObjectId): D;
+  supportsNestedObjects(): boolean;
+  supportsNativePatch(): boolean;
+  getValidatorPlugins(): ReturnType<BaseDbAdapter["getValidatorPlugins"]>;
+  getAdapterTableName(_type: unknown): string | undefined;
+  supportsNativeRelations(): boolean;
+  loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], relations: ReadonlyMap<string, TDbRelation>, foreignKeys: ReadonlyMap<string, TDbForeignKey>, tableResolver?: TTableResolver): Promise<void>;
+  /** Returns the context object used by CollectionPatcher. */
+  getPatcherContext(): TCollectionPatcherContext;
+  nativePatch(filter: FilterExpr, patch: unknown, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  onBeforeFlatten(_type: unknown): void;
+  onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
+  getMetadataOverrides(meta: TableMetadata): TMetadataOverrides;
+  onAfterFlatten(): void;
+  /** Returns MongoDB-specific search index map (internal). */
+  getMongoSearchIndexes(): Map<string, TMongoIndex>;
+  /** Returns a specific MongoDB search index by name. */
+  getMongoSearchIndex(name?: string): TMongoIndex | undefined;
+  /** Returns the default similarity threshold for a vector index (from @db.search.vector.threshold). */
+  getVectorThreshold(indexName?: string): number | undefined;
+  getSearchIndexes(): TSearchIndexInfo[];
+  isVectorSearchable(): boolean;
+  search(text: string, query: DbQuery, indexName?: string): Promise<Record<string, unknown>[]>;
+  searchWithCount(text: string, query: DbQuery, indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  vectorSearch(vector: number[], query: DbQuery, indexName?: string): Promise<Record<string, unknown>[]>;
+  vectorSearchWithCount(vector: number[], query: DbQuery, indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  findManyWithCount(query: DbQuery): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  collectionExists(): Promise<boolean>;
+  ensureCollectionExists(): Promise<void>;
+  /**
+   * Wraps an async operation to catch MongoDB duplicate key errors
+   * (code 11000) and rethrow as structured `DbError`.
+   */
+  private _wrapDuplicateKeyError;
+  insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
+  insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
+  findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  count(query: DbQuery): Promise<number>;
+  updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
+  updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  clearCollectionCache(): void;
+  tableExists(): Promise<boolean>;
+  ensureTable(): Promise<void>;
+  syncIndexes(): Promise<void>;
+  syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
+  dropColumns(columns: string[]): Promise<void>;
+  renameTable(oldName: string): Promise<void>;
+  recreateTable(): Promise<void>;
+  dropTable(): Promise<void>;
+  dropViewByName(viewName: string): Promise<void>;
+  dropTableByName(tableName: string): Promise<void>;
+  getDesiredTableOptions(): TExistingTableOption[];
+  getExistingTableOptions(): Promise<TExistingTableOption[]>;
+  destructiveOptionKeys(): ReadonlySet<string>;
+  /** Returns the counters collection used for atomic auto-increment. */
+  protected get _countersCollection(): Collection<{
+    _id: string;
+    seq: number;
+  }>;
+  /** Returns physical field names of increment fields that are undefined in the data. */
+  private _fieldsNeedingIncrement;
+  /**
+   * Atomically allocates `count` sequential values for each increment field
+   * using a counter collection. Returns a map of field → first allocated value.
+   */
+  private _allocateIncrementValues;
+  /** Reads current max value for a single field via $group aggregation. */
+  private _getCurrentFieldMax;
+  /** Allocates increment values for a batch of items, assigning in order. */
+  private _assignBatchIncrements;
+  private _buildFindOptions;
+  /**
+   * Returns MongoDB collation options if any filter field has a non-binary collation.
+   * Uses pre-computed insights when available, falls back to computing them on demand.
+   * Maps: nocase → strength 2 (case-insensitive), unicode → strength 1 (case+accent-insensitive).
+   */
+  private _getCollationOpts;
+  protected _addMongoIndexField(type: TPlainIndex["type"], name: string, field: string, weight?: number): void;
+  protected _setSearchIndex(type: TSearchIndex["type"], name: string | undefined, definition: TMongoSearchIndexDefinition): void;
+  protected _addFieldToSearchIndex(type: TSearchIndex["type"], _name: string | undefined, fieldName: string, analyzer?: string): void;
+}
+//#endregion
+//#region src/lib/mongo-filter.d.ts
+/**
+ * Translates a generic {@link FilterExpr} into a MongoDB-compatible
+ * {@link Filter} document.
+ *
+ * MongoDB's query language is nearly identical to the `FilterExpr` structure,
+ * so this is largely a structural pass-through via the `walkFilter` visitor.
+ */
+declare function buildMongoFilter(filter: FilterExpr): Filter<any>;
+//#endregion
+//#region src/lib/validate-plugins.d.ts
+declare const validateMongoIdPlugin: TValidatorPlugin;
+//#endregion
+//#region src/lib/index.d.ts
+declare function createAdapter(connection: string, _options?: Record<string, unknown>): DbSpace;
+//#endregion
+export { CollectionPatcher, MongoAdapter, TCollectionPatcherContext, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, createAdapter, validateMongoIdPlugin };