monsqlize 2.0.0 → 2.0.2

package/dist/types/collection.d.ts

@@ -1,40 +1,40 @@
-import type { ChangeStream, Document, FindOptions, Sort } from 'mongodb';
-
-/** Meta options for controlling timing/cache info in query results. */
-export interface MetaOptions {
-    /** 'op' = operation-level timing only; 'sub' = include sub-step timings (findPage only) */
-    level?: 'op' | 'sub';
-    /** Include cache hit/miss/ttl info in meta */
-    includeCache?: boolean;
-}
-
-/** Query options that request the v1 `{ data, meta }` wrapper. */
-export interface QueryMetaOption extends Record<string, unknown> {
-    /** Include operation timing metadata in the resolved query result. */
-    meta: true | MetaOptions;
-}
-
-/** Cursor-based page navigation info returned by findPage. */
-export interface PageInfo {
-    hasNext: boolean;
-    hasPrev: boolean;
-    startCursor: string | null;
-    endCursor: string | null;
-    /** Target logical page number (cursor/offset-jump modes only) */
-    currentPage?: number;
-}
-
-/** Totals/count info returned by findPage when totals mode is enabled. */
+import type { ChangeStream, Document, FindOptions, Sort } from 'mongodb';
+
+/** Meta options for controlling timing/cache info in query results. */
+export interface MetaOptions {
+    /** 'op' = operation-level timing only; 'sub' = include sub-step timings (findPage only) */
+    level?: 'op' | 'sub';
+    /** Include cache hit/miss/ttl info in meta */
+    includeCache?: boolean;
+}
+
+/** Query options that request the v1 `{ data, meta }` wrapper. */
+export interface QueryMetaOption extends Record<string, unknown> {
+    /** Include operation timing metadata in the resolved query result. */
+    meta: true | MetaOptions;
+}
+
+/** Cursor-based page navigation info returned by findPage. */
+export interface PageInfo {
+    hasNext: boolean;
+    hasPrev: boolean;
+    startCursor: string | null;
+    endCursor: string | null;
+    /** Target logical page number (cursor/offset-jump modes only) */
+    currentPage?: number;
+}
+
+/** Totals/count info returned by findPage when totals mode is enabled. */
 export interface TotalsInfo {
     mode: 'async' | 'sync' | 'approx';
-    /** async: null = not ready yet; approx: undefined = unknown/approximate */
-    total?: number | null;
-    totalPages?: number | null;
-    /** Short token for async totals polling */
-    token?: string;
-    /** Write timestamp (ms) if from cache */
-    ts?: number;
-    /** Error identifier for async mode failures */
+    /** async: null = not ready yet; approx: undefined = unknown/approximate */
+    total?: number | null;
+    totalPages?: number | null;
+    /** Short token for async totals polling */
+    token?: string;
+    /** Write timestamp (ms) if from cache */
+    ts?: number;
+    /** Error identifier for async mode failures */
     error?: string;
 }
 
@@ -46,132 +46,132 @@ type SyncTotalsInfo = TotalsInfo & {
     totalPages: number;
 };
 type LegacySyncTotalsInfo<TSchema = any> = unknown extends TSchema ? any : SyncTotalsInfo;
-
-/** Timing/meta info returned by findPage when the meta option is enabled. */
-export interface MetaInfo {
-    op: string;
-    ns: { iid: string; type: string; db: string; coll: string };
-    db?: string;
-    collection?: string;
-    timestamp?: number;
-    startTs: number;
-    endTs: number;
-    durationMs: number;
-    maxTimeMS?: number;
-    fromCache?: boolean;
-    cacheHit?: boolean;
-    cacheTtl?: number;
-    keyHash?: string;
-    page?: number;
-    after?: boolean;
-    before?: boolean;
-    hops?: number;
-    step?: number;
-    /** Sub-step timings (level='sub' only) */
-    steps?: Array<{ phase: 'hop' | 'offset' | 'fetch' | 'totals'; name: string; index?: number; durationMs: number }>;
-    error?: { code?: string; message: string };
-}
-
-/** Bookmark/cursor jump configuration for deep pagination. */
-export interface JumpOptions {
-    /** Bookmark density: store bookmark every N pages (default 10) */
-    step?: number;
-    /** Max cursor-walking hops per jump (default 20) */
-    maxHops?: number;
-    /** Optional custom key dimensions for bookmark keying */
-    keyDims?: object;
-    /** Custom bookmark reader — returns cursor string or null */
-    getBookmark?: (params: { keyDims: unknown; page: number }) => Promise<string | null>;
-    /** Custom bookmark writer */
-    saveBookmark?: (params: { keyDims: unknown; page: number; cursor: string; ttlMs?: number }) => Promise<void>;
-}
-
-/** Offset-based fallback configuration for small-range pages in findPage. */
-export interface OffsetJumpOptions {
-    /** Enable offset fallback when skip <= maxSkip (default false) */
-    enable?: boolean;
-    /** Max skip before falling back to cursor-jump (default 50000) */
-    maxSkip?: number;
-}
-
-/** Totals/count mode configuration for findPage. */
-export interface TotalsOptions {
-    /** Counting strategy (default 'none') */
-    mode?: 'none' | 'async' | 'approx' | 'sync';
-    /** Timeout for countDocuments (sync/async modes, ms) */
-    maxTimeMS?: number;
-    /** Cache TTL for totals (async/approx modes, ms; default 10 min) */
-    ttlMs?: number;
-    /** Index hint for count query */
-    hint?: unknown;
-    /** Collation for count query */
-    collation?: unknown;
-}
-
-/** Stream query options for collection.stream(). */
-export interface StreamOptions {
-    projection?: Record<string, unknown> | string[];
-    sort?: Record<string, 1 | -1>;
-    limit?: number;
-    skip?: number;
-    /** Cursor batch size (default 1000) */
-    batchSize?: number;
-    maxTimeMS?: number;
-    hint?: unknown;
-    collation?: unknown;
-    noCursorTimeout?: boolean;
-}
-
-/** Explain/query plan options for collection.explain(). */
-export interface ExplainOptions {
-    projection?: Record<string, unknown>;
-    sort?: Record<string, 1 | -1>;
-    limit?: number;
-    skip?: number;
-    maxTimeMS?: number;
-    hint?: unknown;
-    collation?: unknown;
-    /** Verbosity level (default 'queryPlanner') */
-    verbosity?: 'queryPlanner' | 'executionStats' | 'allPlansExecution';
-}
-
-/** MongoDB query execution plan result returned by collection.explain(). */
-export interface ExplainResult {
-    queryPlanner: {
-        plannerVersion: number;
-        namespace: string;
-        indexFilterSet: boolean;
-        parsedQuery?: unknown;
-        winningPlan: unknown;
-        rejectedPlans: unknown[];
-    };
-    executionStats?: {
-        executionSuccess: boolean;
-        nReturned: number;
-        executionTimeMillis: number;
-        totalKeysExamined: number;
-        totalDocsExamined: number;
-        executionStages: unknown;
-        allPlansExecution?: unknown[];
-    };
-    serverInfo?: {
-        host: string;
-        port: number;
-        version: string;
-        gitVersion: string;
-    };
-    ok: number;
-}
-
-export interface HealthView {
-    status: 'up' | 'down';
-    connected: boolean;
-    /** @since v1 — driver connection state alias */
-    driver?: { connected: boolean };
-    defaults?: Record<string, unknown>;
-    cache?: Record<string, unknown>;
-}
-
+
+/** Timing/meta info returned by findPage when the meta option is enabled. */
+export interface MetaInfo {
+    op: string;
+    ns: { iid: string; type: string; db: string; coll: string };
+    db?: string;
+    collection?: string;
+    timestamp?: number;
+    startTs: number;
+    endTs: number;
+    durationMs: number;
+    maxTimeMS?: number;
+    fromCache?: boolean;
+    cacheHit?: boolean;
+    cacheTtl?: number;
+    keyHash?: string;
+    page?: number;
+    after?: boolean;
+    before?: boolean;
+    hops?: number;
+    step?: number;
+    /** Sub-step timings (level='sub' only) */
+    steps?: Array<{ phase: 'hop' | 'offset' | 'fetch' | 'totals'; name: string; index?: number; durationMs: number }>;
+    error?: { code?: string; message: string };
+}
+
+/** Bookmark/cursor jump configuration for deep pagination. */
+export interface JumpOptions {
+    /** Bookmark density: store bookmark every N pages (default 10) */
+    step?: number;
+    /** Max cursor-walking hops per jump (default 20) */
+    maxHops?: number;
+    /** Optional custom key dimensions for bookmark keying */
+    keyDims?: object;
+    /** Custom bookmark reader — returns cursor string or null */
+    getBookmark?: (params: { keyDims: unknown; page: number }) => Promise<string | null>;
+    /** Custom bookmark writer */
+    saveBookmark?: (params: { keyDims: unknown; page: number; cursor: string; ttlMs?: number }) => Promise<void>;
+}
+
+/** Offset-based fallback configuration for small-range pages in findPage. */
+export interface OffsetJumpOptions {
+    /** Enable offset fallback when skip <= maxSkip (default false) */
+    enable?: boolean;
+    /** Max skip before falling back to cursor-jump (default 50000) */
+    maxSkip?: number;
+}
+
+/** Totals/count mode configuration for findPage. */
+export interface TotalsOptions {
+    /** Counting strategy (default 'none') */
+    mode?: 'none' | 'async' | 'approx' | 'sync';
+    /** Timeout for countDocuments (sync/async modes, ms) */
+    maxTimeMS?: number;
+    /** Cache TTL for totals (async/approx modes, ms; default 10 min) */
+    ttlMs?: number;
+    /** Index hint for count query */
+    hint?: unknown;
+    /** Collation for count query */
+    collation?: unknown;
+}
+
+/** Stream query options for collection.stream(). */
+export interface StreamOptions {
+    projection?: Record<string, unknown> | string[];
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+    /** Cursor batch size (default 1000) */
+    batchSize?: number;
+    maxTimeMS?: number;
+    hint?: unknown;
+    collation?: unknown;
+    noCursorTimeout?: boolean;
+}
+
+/** Explain/query plan options for collection.explain(). */
+export interface ExplainOptions {
+    projection?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+    maxTimeMS?: number;
+    hint?: unknown;
+    collation?: unknown;
+    /** Verbosity level (default 'queryPlanner') */
+    verbosity?: 'queryPlanner' | 'executionStats' | 'allPlansExecution';
+}
+
+/** MongoDB query execution plan result returned by collection.explain(). */
+export interface ExplainResult {
+    queryPlanner: {
+        plannerVersion: number;
+        namespace: string;
+        indexFilterSet: boolean;
+        parsedQuery?: unknown;
+        winningPlan: unknown;
+        rejectedPlans: unknown[];
+    };
+    executionStats?: {
+        executionSuccess: boolean;
+        nReturned: number;
+        executionTimeMillis: number;
+        totalKeysExamined: number;
+        totalDocsExamined: number;
+        executionStages: unknown;
+        allPlansExecution?: unknown[];
+    };
+    serverInfo?: {
+        host: string;
+        port: number;
+        version: string;
+        gitVersion: string;
+    };
+    ok: number;
+}
+
+export interface HealthView {
+    status: 'up' | 'down';
+    connected: boolean;
+    /** @since v1 — driver connection state alias */
+    driver?: { connected: boolean };
+    defaults?: Record<string, unknown>;
+    cache?: Record<string, unknown>;
+}
+
 export interface InsertOneResult {
     acknowledged: boolean;
     insertedId: any;
@@ -182,7 +182,7 @@ export interface InsertManyResult {
     insertedCount: number;
     insertedIds: Record<number, any>;
 }
-
+
 export interface UpdateResult {
     acknowledged: boolean;
     matchedCount: number;
@@ -190,42 +190,42 @@ export interface UpdateResult {
     upsertedCount: number;
     upsertedId: any;
 }
-
-export interface DeleteResult {
-    acknowledged: boolean;
-    deletedCount: number;
-}
-
+
+export interface DeleteResult {
+    acknowledged: boolean;
+    deletedCount: number;
+}
+
 export interface FindPageOptions<TSchema = any> {
-    query?: Document;
-    page?: number;
-    limit?: number;
-    after?: string;
-    before?: string;
-    sort?: Sort;
-    projection?: Document;
-    pipeline?: Document[];
-    /** Totals/count configuration */
-    totals?: TotalsOptions;
-    stream?: boolean;
-    explain?: boolean | string;
-    /** Query comment for server-side profiling. v1 compat — top-level shortcut for `options.comment`. */
-    comment?: string;
-    options?: FindOptions;
-    /** Cursor-walking bookmark jump configuration */
-    jump?: JumpOptions;
-    /** Offset-based fallback for small page ranges */
-    offsetJump?: OffsetJumpOptions;
-    maxTimeMS?: number;
-    hint?: Document | string;
-    collation?: Document;
-    batchSize?: number;
-    /** Cache TTL in milliseconds */
-    cache?: number;
-    /** Include timing/meta info in result — pass true or MetaOptions for sub-step detail */
-    meta?: boolean | MetaOptions;
-}
-
+    query?: Document;
+    page?: number;
+    limit?: number;
+    after?: string;
+    before?: string;
+    sort?: Sort;
+    projection?: Document;
+    pipeline?: Document[];
+    /** Totals/count configuration */
+    totals?: TotalsOptions;
+    stream?: boolean;
+    explain?: boolean | string;
+    /** Query comment for server-side profiling. v1 compat — top-level shortcut for `options.comment`. */
+    comment?: string;
+    options?: FindOptions;
+    /** Cursor-walking bookmark jump configuration */
+    jump?: JumpOptions;
+    /** Offset-based fallback for small page ranges */
+    offsetJump?: OffsetJumpOptions;
+    maxTimeMS?: number;
+    hint?: Document | string;
+    collation?: Document;
+    batchSize?: number;
+    /** Cache TTL in milliseconds */
+    cache?: number;
+    /** Include timing/meta info in result — pass true or MetaOptions for sub-step detail */
+    meta?: boolean | MetaOptions;
+}
+
 export interface FindPageResult<TSchema = any> {
     items: TSchema[];
     pageInfo: LegacyPageInfo<TSchema>;
@@ -236,796 +236,796 @@ export interface FindPageResult<TSchema = any> {
 
 export interface FindAndCountResult<TSchema = any> {
     data: TSchema[];
-    total: number;
-    /** @deprecated Use `data`. v1 backward-compat alias — will be removed in a future major. */
-    documents?: TSchema[];
-}
-
+    total: number;
+    /** @deprecated Use `data`. v1 backward-compat alias — will be removed in a future major. */
+    documents?: TSchema[];
+}
+
 export interface FindChain<TSchema = any, TPromise = TSchema[]> extends Promise<TPromise> {
-    limit(value: number): FindChain<TSchema, TPromise>;
-    skip(value: number): FindChain<TSchema, TPromise>;
-    sort(value: Sort | Record<string, 1 | -1>): FindChain<TSchema, TPromise>;
-    project(value: Document): FindChain<TSchema, TPromise>;
-    hint(value: unknown): FindChain<TSchema, TPromise>;
-    collation(value: Record<string, unknown>): FindChain<TSchema, TPromise>;
-    comment(value: string): FindChain<TSchema, TPromise>;
-    maxTimeMS(value: number): FindChain<TSchema, TPromise>;
-    batchSize(value: number): FindChain<TSchema, TPromise>;
-    explain(verbosity?: boolean | string): Promise<unknown>;
-    stream(): NodeJS.ReadableStream;
-    toArray(): Promise<TSchema[]>;
-}
-
-export interface AggregateChain<TResult = unknown, TPromise = TResult[]> extends Promise<TPromise> {
-    hint(value: unknown): AggregateChain<TResult, TPromise>;
-    collation(value: Record<string, unknown>): AggregateChain<TResult, TPromise>;
-    comment(value: string): AggregateChain<TResult, TPromise>;
-    maxTimeMS(value: number): AggregateChain<TResult, TPromise>;
-    allowDiskUse(value: boolean): AggregateChain<TResult, TPromise>;
-    batchSize(value: number): AggregateChain<TResult, TPromise>;
-    explain(verbosity?: boolean | string): Promise<unknown>;
-    stream(): NodeJS.ReadableStream;
-    toArray(): Promise<TResult[]>;
-}
-
-/** Write concern options for batch operations. */
-export interface WriteConcern {
-    /** Write acknowledgement level (default: 1). */
-    w?: number | 'majority';
-    /** Wait for journal flush before acknowledging (default: false). */
-    j?: boolean;
-    /** Write timeout in milliseconds. */
-    wtimeout?: number;
-}
-
-/** Per-batch retry record appended to batch result `retries` arrays. */
-export interface BatchRetryRecord {
-    batchIndex: number;
-    attempt: number;
-    /** @alias attempt — v1 compat: v1 runtime emitted `attempts` (plural). */
-    attempts?: number;
-    maxAttempts: number;
-    delay: number;
-    /** @since v1 — always `false` on retry records (the attempt that triggered the retry failed). */
-    success?: boolean;
-    error?: Error;
-}
-
-/** Progress callback payload delivered for each completed batch. */
-export interface BatchProgress {
-    currentBatch: number;
-    totalBatches: number;
-    inserted?: number;
-    modified?: number;
-    deleted?: number;
-    /** Total document count (null when not yet known). */
-    total: number | null;
-    /** Completion percentage (null when total is unknown). */
-    percentage: number | null;
-    errors: number;
-    retries: number;
-}
-
-/** Payload supplied to the `onRetry` callback for each retry attempt. */
-export interface RetryInfo {
-    batchIndex: number;
-    attempt: number;
-    maxAttempts: number;
-    error: Error;
-}
-
-/** Options for insertBatch operations. */
-export interface InsertBatchOptions {
-    /** Number of documents per batch (default: 1000). */
-    batchSize?: number;
-    /** Maximum number of concurrent batch writes. */
-    concurrency?: number;
-    /** Ordered inserts — stop on first error when true. */
-    ordered?: boolean;
-    /** Progress callback invoked after each batch. */
-    onProgress?: (progress: BatchProgress) => void;
-    /** Error handling strategy. */
-    onError?: 'stop' | 'skip' | 'collect' | 'retry';
-    /** Number of retry attempts per batch on transient failure. */
-    retryAttempts?: number;
-    /** Delay between retries in milliseconds. */
-    retryDelay?: number;
-    /** Retry callback invoked before each retry attempt. */
-    onRetry?: (retryInfo: RetryInfo) => void;
-    /** MongoDB write concern. */
-    writeConcern?: WriteConcern;
-    /** Skip MongoDB document validation. */
-    bypassDocumentValidation?: boolean;
-    /** Query comment for server-side profiling. */
-    comment?: string;
-}
-
-/** Options for deleteBatch operations. */
-export interface DeleteBatchOptions {
-    /** Number of documents per batch (default: 1000). */
-    batchSize?: number;
-    /** Estimate total for progress reporting. */
-    estimateProgress?: boolean;
-    /** Progress callback invoked after each batch. */
-    onProgress?: (progress: BatchProgress) => void;
-    /** Error handling strategy. */
-    onError?: 'stop' | 'skip' | 'collect' | 'retry';
-    /** Number of retry attempts per batch on transient failure. */
-    retryAttempts?: number;
-    /** Delay between retries in milliseconds. */
-    retryDelay?: number;
-    /** Retry callback invoked before each retry attempt. */
-    onRetry?: (retryInfo: RetryInfo) => void;
-    /** MongoDB write concern. */
-    writeConcern?: WriteConcern;
-    /** Query comment for server-side profiling. */
-    comment?: string;
-}
-
-export interface BatchErrorRecord {
-    batchIndex: number;
-    message: string;
-    /** Additional error details. */
-    details?: unknown;
-}
-
-export interface InsertBatchResult {
-    acknowledged: boolean;
-    /** Total document count processed (never null for insert). */
-    totalCount: number;
-    insertedCount: number;
-    batchCount: number;
-    errors: BatchErrorRecord[];
-    insertedIds: Record<number, unknown>;
-    /** Per-batch retry records. */
-    retries: BatchRetryRecord[];
-}
-
-export interface UpdateBatchResult {
-    acknowledged: boolean;
-    totalCount: number | null;
-    matchedCount: number;
-    modifiedCount: number;
-    /** Number of documents upserted across all batches. */
-    upsertedCount: number;
-    batchCount: number;
-    errors: BatchErrorRecord[];
-    /** Per-batch retry records. */
-    retries: BatchRetryRecord[];
-}
-
-export interface DeleteBatchResult {
-    acknowledged: boolean;
-    totalCount: number | null;
-    deletedCount: number;
-    batchCount: number;
-    errors: BatchErrorRecord[];
-    /** Per-batch retry records. */
-    retries: BatchRetryRecord[];
-}
-
-export interface BatchWriteOptions {
-    batchSize?: number;
-    ordered?: boolean;
-    concurrency?: number;
-    onProgress?: (progress: BatchProgress) => void;
-    onError?: 'stop' | 'skip' | 'collect' | 'retry';
-    retryAttempts?: number;
-    retryDelay?: number;
-    onRetry?: (retryInfo: RetryInfo) => void;
-}
-
-/** Options for updateBatch operations. */
-export interface UpdateBatchOptions {
-    /** Number of documents per batch (default: 1000). */
-    batchSize?: number;
-    /** Estimate total for progress reporting. */
-    estimateProgress?: boolean;
-    /** Progress callback invoked after each batch. */
-    onProgress?: (progress: BatchProgress) => void;
-    /** Error handling strategy. */
-    onError?: 'stop' | 'skip' | 'collect' | 'retry';
-    /** Number of retry attempts per batch on transient failure. */
-    retryAttempts?: number;
-    /** Delay between retries in milliseconds. */
-    retryDelay?: number;
-    /** Retry callback invoked before each retry attempt. */
-    onRetry?: (retryInfo: RetryInfo) => void;
-    /** MongoDB write concern. */
-    writeConcern?: WriteConcern;
-    /** Upsert documents that do not match the filter. */
-    upsert?: boolean;
-    /** Array filters for nested array updates. */
-    arrayFilters?: unknown[];
-    /** Query comment for server-side profiling. */
-    comment?: string;
-    /** Sort order used to paginate through batch cursor. */
-    sort?: Record<string, 1 | -1>;
-}
-
-export interface IncrementOneOptions extends Record<string, unknown> {
-    returnDocument?: 'before' | 'after';
-    projection?: Record<string, unknown>;
-    $set?: Record<string, unknown>;
-}
-
-/**
- * Result returned by {@link Collection.incrementOne}.
- * The updated document is available via `.value` (or `null` if not found).
- */
-export interface IncrementOneResult<TSchema = unknown> {
-    acknowledged: boolean;
-    matchedCount: number;
-    modifiedCount: number;
-    /** The document after the increment (or null when no match). */
-    value: TSchema | null;
-}
-
-export interface IndexCreateResult {
-    name: string;
-}
-
-export interface BookmarkPrewarmResult {
-    warmed: number;
-    failed: number;
-    keys: string[];
-}
-
-export interface BookmarkListResult {
-    count: number;
-    pages: number[];
-    keys: string[];
-}
-
-export interface BookmarkClearResult {
-    cleared: number;
-    pattern: string;
-    keysBefore: number;
-}
-
-export interface BookmarkKeyDims<TSchema = unknown> extends Omit<FindPageOptions<TSchema>, 'page'> { }
-
-export interface BookmarkCacheLike {
-    set(key: string, value: unknown): void | boolean | Promise<void> | Promise<boolean>;
-    get(key: string): unknown | Promise<unknown>;
-    delete?(key: string): boolean | Promise<boolean>;
-    keys?(pattern: string): string[] | Promise<string[]>;
-    delPattern?(pattern: string): number | Promise<number>;
-}
-
-export interface AdminBuildInfoView {
-    version?: string;
-    versionArray?: number[];
-    gitVersion?: string;
-    bits?: number;
-    debug?: boolean;
-    maxBsonObjectSize?: number;
-}
-
-export interface ServerStatusView {
-    connections: {
-        current?: number;
-        available?: number;
-        totalCreated?: number;
-    };
-    mem: {
-        resident?: number;
-        virtual?: number;
-        mapped?: number;
-    };
-    opcounters: {
-        insert?: number;
-        query?: number;
-        update?: number;
-        delete?: number;
-        getmore?: number;
-        command?: number;
-    };
-    network: {
-        bytesIn?: number;
-        bytesOut?: number;
-        numRequests?: number;
-    };
-    uptime?: number;
-    localTime?: Date;
-    version?: string;
-    process?: string;
-}
-
-export interface DbStatsView {
-    db?: string;
-    collections?: number;
-    views?: number;
-    objects?: number;
-    avgObjSize?: number;
-    dataSize?: number;
-    storageSize?: number;
-    indexes?: number;
-    indexSize?: number;
-    totalSize?: number;
-    scaleFactor?: number;
-}
-
-export interface AdminAccessor {
-    /** Pings the MongoDB server and returns true when reachable. */
-    ping(): Promise<boolean>;
-    /** Returns MongoDB server build information. */
-    buildInfo(): Promise<AdminBuildInfoView>;
-    /**
-     * Returns current server status metrics.
-     * @param options - Optional scale factor for byte values.
-     * @returns Server status snapshot.
-     */
-    serverStatus(options?: { scale?: number; }): Promise<ServerStatusView>;
-    /**
-     * Returns database storage statistics.
-     * @param options - Optional scale factor for byte values.
-     * @returns Database stats view.
-     */
-    stats(options?: { scale?: number; }): Promise<DbStatsView>;
-}
-
+    limit(value: number): FindChain<TSchema, TPromise>;
+    skip(value: number): FindChain<TSchema, TPromise>;
+    sort(value: Sort | Record<string, 1 | -1>): FindChain<TSchema, TPromise>;
+    project(value: Document): FindChain<TSchema, TPromise>;
+    hint(value: unknown): FindChain<TSchema, TPromise>;
+    collation(value: Record<string, unknown>): FindChain<TSchema, TPromise>;
+    comment(value: string): FindChain<TSchema, TPromise>;
+    maxTimeMS(value: number): FindChain<TSchema, TPromise>;
+    batchSize(value: number): FindChain<TSchema, TPromise>;
+    explain(verbosity?: boolean | string): Promise<unknown>;
+    stream(): NodeJS.ReadableStream;
+    toArray(): Promise<TSchema[]>;
+}
+
+export interface AggregateChain<TResult = unknown, TPromise = TResult[]> extends Promise<TPromise> {
+    hint(value: unknown): AggregateChain<TResult, TPromise>;
+    collation(value: Record<string, unknown>): AggregateChain<TResult, TPromise>;
+    comment(value: string): AggregateChain<TResult, TPromise>;
+    maxTimeMS(value: number): AggregateChain<TResult, TPromise>;
+    allowDiskUse(value: boolean): AggregateChain<TResult, TPromise>;
+    batchSize(value: number): AggregateChain<TResult, TPromise>;
+    explain(verbosity?: boolean | string): Promise<unknown>;
+    stream(): NodeJS.ReadableStream;
+    toArray(): Promise<TResult[]>;
+}
+
+/** Write concern options for batch operations. */
+export interface WriteConcern {
+    /** Write acknowledgement level (default: 1). */
+    w?: number | 'majority';
+    /** Wait for journal flush before acknowledging (default: false). */
+    j?: boolean;
+    /** Write timeout in milliseconds. */
+    wtimeout?: number;
+}
+
+/** Per-batch retry record appended to batch result `retries` arrays. */
+export interface BatchRetryRecord {
+    batchIndex: number;
+    attempt: number;
+    /** @alias attempt — v1 compat: v1 runtime emitted `attempts` (plural). */
+    attempts?: number;
+    maxAttempts: number;
+    delay: number;
+    /** @since v1 — always `false` on retry records (the attempt that triggered the retry failed). */
+    success?: boolean;
+    error?: Error;
+}
+
+/** Progress callback payload delivered for each completed batch. */
+export interface BatchProgress {
+    currentBatch: number;
+    totalBatches: number;
+    inserted?: number;
+    modified?: number;
+    deleted?: number;
+    /** Total document count (null when not yet known). */
+    total: number | null;
+    /** Completion percentage (null when total is unknown). */
+    percentage: number | null;
+    errors: number;
+    retries: number;
+}
+
+/** Payload supplied to the `onRetry` callback for each retry attempt. */
+export interface RetryInfo {
+    batchIndex: number;
+    attempt: number;
+    maxAttempts: number;
+    error: Error;
+}
+
+/** Options for insertBatch operations. */
+export interface InsertBatchOptions {
+    /** Number of documents per batch (default: 1000). */
+    batchSize?: number;
+    /** Maximum number of concurrent batch writes. */
+    concurrency?: number;
+    /** Ordered inserts — stop on first error when true. */
+    ordered?: boolean;
+    /** Progress callback invoked after each batch. */
+    onProgress?: (progress: BatchProgress) => void;
+    /** Error handling strategy. */
+    onError?: 'stop' | 'skip' | 'collect' | 'retry';
+    /** Number of retry attempts per batch on transient failure. */
+    retryAttempts?: number;
+    /** Delay between retries in milliseconds. */
+    retryDelay?: number;
+    /** Retry callback invoked before each retry attempt. */
+    onRetry?: (retryInfo: RetryInfo) => void;
+    /** MongoDB write concern. */
+    writeConcern?: WriteConcern;
+    /** Skip MongoDB document validation. */
+    bypassDocumentValidation?: boolean;
+    /** Query comment for server-side profiling. */
+    comment?: string;
+}
+
+/** Options for deleteBatch operations. */
+export interface DeleteBatchOptions {
+    /** Number of documents per batch (default: 1000). */
+    batchSize?: number;
+    /** Estimate total for progress reporting. */
+    estimateProgress?: boolean;
+    /** Progress callback invoked after each batch. */
+    onProgress?: (progress: BatchProgress) => void;
+    /** Error handling strategy. */
+    onError?: 'stop' | 'skip' | 'collect' | 'retry';
+    /** Number of retry attempts per batch on transient failure. */
+    retryAttempts?: number;
+    /** Delay between retries in milliseconds. */
+    retryDelay?: number;
+    /** Retry callback invoked before each retry attempt. */
+    onRetry?: (retryInfo: RetryInfo) => void;
+    /** MongoDB write concern. */
+    writeConcern?: WriteConcern;
+    /** Query comment for server-side profiling. */
+    comment?: string;
+}
+
+export interface BatchErrorRecord {
+    batchIndex: number;
+    message: string;
+    /** Additional error details. */
+    details?: unknown;
+}
+
+export interface InsertBatchResult {
+    acknowledged: boolean;
+    /** Total document count processed (never null for insert). */
+    totalCount: number;
+    insertedCount: number;
+    batchCount: number;
+    errors: BatchErrorRecord[];
+    insertedIds: Record<number, unknown>;
+    /** Per-batch retry records. */
+    retries: BatchRetryRecord[];
+}
+
+export interface UpdateBatchResult {
+    acknowledged: boolean;
+    totalCount: number | null;
+    matchedCount: number;
+    modifiedCount: number;
+    /** Number of documents upserted across all batches. */
+    upsertedCount: number;
+    batchCount: number;
+    errors: BatchErrorRecord[];
+    /** Per-batch retry records. */
+    retries: BatchRetryRecord[];
+}
+
+export interface DeleteBatchResult {
+    acknowledged: boolean;
+    totalCount: number | null;
+    deletedCount: number;
+    batchCount: number;
+    errors: BatchErrorRecord[];
+    /** Per-batch retry records. */
+    retries: BatchRetryRecord[];
+}
+
+export interface BatchWriteOptions {
+    batchSize?: number;
+    ordered?: boolean;
+    concurrency?: number;
+    onProgress?: (progress: BatchProgress) => void;
+    onError?: 'stop' | 'skip' | 'collect' | 'retry';
+    retryAttempts?: number;
+    retryDelay?: number;
+    onRetry?: (retryInfo: RetryInfo) => void;
+}
+
+/** Options for updateBatch operations. */
+export interface UpdateBatchOptions {
+    /** Number of documents per batch (default: 1000). */
+    batchSize?: number;
+    /** Estimate total for progress reporting. */
+    estimateProgress?: boolean;
+    /** Progress callback invoked after each batch. */
+    onProgress?: (progress: BatchProgress) => void;
+    /** Error handling strategy. */
+    onError?: 'stop' | 'skip' | 'collect' | 'retry';
+    /** Number of retry attempts per batch on transient failure. */
+    retryAttempts?: number;
+    /** Delay between retries in milliseconds. */
+    retryDelay?: number;
+    /** Retry callback invoked before each retry attempt. */
+    onRetry?: (retryInfo: RetryInfo) => void;
+    /** MongoDB write concern. */
+    writeConcern?: WriteConcern;
+    /** Upsert documents that do not match the filter. */
+    upsert?: boolean;
+    /** Array filters for nested array updates. */
+    arrayFilters?: unknown[];
+    /** Query comment for server-side profiling. */
+    comment?: string;
+    /** Sort order used to paginate through batch cursor. */
+    sort?: Record<string, 1 | -1>;
+}
+
+export interface IncrementOneOptions extends Record<string, unknown> {
+    returnDocument?: 'before' | 'after';
+    projection?: Record<string, unknown>;
+    $set?: Record<string, unknown>;
+}
+
+/**
+ * Result returned by {@link Collection.incrementOne}.
+ * The updated document is available via `.value` (or `null` if not found).
+ */
+export interface IncrementOneResult<TSchema = unknown> {
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    /** The document after the increment (or null when no match). */
+    value: TSchema | null;
+}
+
+export interface IndexCreateResult {
+    name: string;
+}
+
+export interface BookmarkPrewarmResult {
+    warmed: number;
+    failed: number;
+    keys: string[];
+}
+
+export interface BookmarkListResult {
+    count: number;
+    pages: number[];
+    keys: string[];
+}
+
+export interface BookmarkClearResult {
+    cleared: number;
+    pattern: string;
+    keysBefore: number;
+}
+
+export interface BookmarkKeyDims<TSchema = unknown> extends Omit<FindPageOptions<TSchema>, 'page'> { }
+
+export interface BookmarkCacheLike {
+    set(key: string, value: unknown): void | boolean | Promise<void> | Promise<boolean>;
+    get(key: string): unknown | Promise<unknown>;
+    delete?(key: string): boolean | Promise<boolean>;
+    keys?(pattern: string): string[] | Promise<string[]>;
+    delPattern?(pattern: string): number | Promise<number>;
+}
+
+export interface AdminBuildInfoView {
+    version?: string;
+    versionArray?: number[];
+    gitVersion?: string;
+    bits?: number;
+    debug?: boolean;
+    maxBsonObjectSize?: number;
+}
+
+export interface ServerStatusView {
+    connections: {
+        current?: number;
+        available?: number;
+        totalCreated?: number;
+    };
+    mem: {
+        resident?: number;
+        virtual?: number;
+        mapped?: number;
+    };
+    opcounters: {
+        insert?: number;
+        query?: number;
+        update?: number;
+        delete?: number;
+        getmore?: number;
+        command?: number;
+    };
+    network: {
+        bytesIn?: number;
+        bytesOut?: number;
+        numRequests?: number;
+    };
+    uptime?: number;
+    localTime?: Date;
+    version?: string;
+    process?: string;
+}
+
+export interface DbStatsView {
+    db?: string;
+    collections?: number;
+    views?: number;
+    objects?: number;
+    avgObjSize?: number;
+    dataSize?: number;
+    storageSize?: number;
+    indexes?: number;
+    indexSize?: number;
+    totalSize?: number;
+    scaleFactor?: number;
+}
+
+export interface AdminAccessor {
+    /** Pings the MongoDB server and returns true when reachable. */
+    ping(): Promise<boolean>;
+    /** Returns MongoDB server build information. */
+    buildInfo(): Promise<AdminBuildInfoView>;
+    /**
+     * Returns current server status metrics.
+     * @param options - Optional scale factor for byte values.
+     * @returns Server status snapshot.
+     */
+    serverStatus(options?: { scale?: number; }): Promise<ServerStatusView>;
+    /**
+     * Returns database storage statistics.
+     * @param options - Optional scale factor for byte values.
+     * @returns Database stats view.
+     */
+    stats(options?: { scale?: number; }): Promise<DbStatsView>;
+}
+
 export interface Collection<TSchema = any> {
-    /** Returns the namespace descriptor (iid, db, collection) for this collection. */
-    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; };
-    /** Returns the underlying native MongoDB Collection object. */
-    raw(): unknown;
-    /**
-     * Finds the first document matching the query.
-     * @param query - MongoDB filter query.
-     * @param options - MongoDB FindOptions.
-     * @returns The matched document, or null when not found.
-     */
+    /** Returns the namespace descriptor (iid, db, collection) for this collection. */
+    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; };
+    /** Returns the underlying native MongoDB Collection object. */
+    raw(): unknown;
+    /**
+     * Finds the first document matching the query.
+     * @param query - MongoDB filter query.
+     * @param options - MongoDB FindOptions.
+     * @returns The matched document, or null when not found.
+     */
     findOne(query: unknown | undefined, options: QueryMetaOption): Promise<ResultWithMeta<TSchema | null>>;
     findOne(query?: unknown, options?: unknown): Promise<TSchema | null>;
-    /**
-     * Returns a chainable cursor over documents matching the query.
-     * @param query - MongoDB filter query.
-     * @param options - MongoDB FindOptions.
-     * @returns A chainable FindChain that resolves to an array.
-     */
+    /**
+     * Returns a chainable cursor over documents matching the query.
+     * @param query - MongoDB filter query.
+     * @param options - MongoDB FindOptions.
+     * @returns A chainable FindChain that resolves to an array.
+     */
     find(query: unknown | undefined, options: QueryMetaOption): FindChain<TSchema, ResultWithMeta<TSchema[]>>;
     find(query: unknown | undefined, projection: unknown, options?: unknown): FindChain<TSchema>;
     find(query?: unknown, options?: unknown): FindChain<TSchema>;
-    /**
-     * Finds a single document by its `_id` value.
-     * @param id - The `_id` value to look up.
-     * @param options - MongoDB FindOptions.
-     * @returns The matched document, or null when not found.
-     */
-    findOneById(id: unknown, options?: unknown): Promise<TSchema | null>;
-    /**
-     * Fetches multiple documents by their `_id` values in a single query.
-     * @param ids - Array of `_id` values to look up.
-     * @param options - MongoDB FindOptions.
-     * @returns Array of matched documents (order not guaranteed).
-     */
-    findByIds(ids: unknown[], options?: unknown): Promise<TSchema[]>;
-    /**
-     * Finds documents matching the query and returns both the data array and
-     * the total count unaffected by limit/skip.
-     * @param query - MongoDB filter query.
-     * @param options - MongoDB FindOptions.
-     * @returns Object with `data` array and `total` count.
-     */
-    findAndCount(query?: unknown, options?: unknown): Promise<FindAndCountResult<TSchema>>;
-    /**
-     * Returns a Node.js ReadableStream of documents matching the query.
-     * @param query - MongoDB filter query.
-     * @param options - StreamOptions (projection, sort, limit, batchSize, …).
-     * @returns Readable object-mode stream emitting one document per chunk.
-     */
-    stream(query?: unknown, options?: unknown): NodeJS.ReadableStream;
-    /**
-     * Returns the MongoDB query execution plan without running the full query.
-     * @param query - MongoDB filter query.
-     * @param options - ExplainOptions including verbosity level.
-     * @returns Raw explain output from MongoDB.
-     */
-    explain(query?: unknown, options?: unknown): Promise<unknown>;
-    /**
-     * Counts documents matching the query.
-     * @param query - MongoDB filter query.
-     * @param options - MongoDB CountDocumentsOptions.
-     * @returns Number of matched documents.
-     */
-    count(query: unknown | undefined, options: QueryMetaOption): Promise<ResultWithMeta<number>>;
-    count(query?: unknown, options?: unknown): Promise<number>;
-    /**
-     * Inserts a single document into the collection.
-     * @param document - Document to insert.
-     * @param options - InsertOneSimplifiedOptions or InsertOneOptions.
-     * @returns Acknowledged result with the inserted `_id`.
-     * @since v1.0.0
-     */
-    insertOne(document?: unknown, options?: unknown): Promise<InsertOneResult>;
-    /**
-     * Inserts multiple documents into the collection in a single operation.
-     * @param documents - Array of documents to insert.
-     * @param options - InsertManySimplifiedOptions or InsertManyOptions.
-     * @returns Acknowledged result with inserted count and `_id` map.
-     * @since v1.0.0
-     */
-    insertMany(documents?: unknown[], options?: unknown): Promise<InsertManyResult>;
-    /**
-     * Updates the first document matching the filter.
-     * @param filter - MongoDB filter query.
-     * @param update - Update operators (e.g. `$set`, `$inc`).
-     * @param options - MongoDB UpdateOptions.
-     * @returns Update result with matched/modified counts.
-     * @since v1.0.0
-     */
-    updateOne(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
-    /**
-     * Updates all documents matching the filter.
-     * @param filter - MongoDB filter query.
-     * @param update - Update operators.
-     * @param options - MongoDB UpdateOptions.
-     * @returns Update result with matched/modified counts.
-     * @since v1.0.0
-     */
-    updateMany(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
-    /**
-     * Replaces the first document matching the filter with a new document.
-     * @param filter - MongoDB filter query.
-     * @param replacement - Full replacement document (no update operators).
-     * @param options - MongoDB ReplaceOptions.
-     * @returns Update result indicating match and modification.
-     * @since v1.0.0
-     */
-    replaceOne(filter?: unknown, replacement?: unknown, options?: unknown): Promise<UpdateResult>;
-    /**
-     * Atomically finds the first matching document, replaces it, and returns a document.
-     * @param filter - MongoDB filter query.
-     * @param replacement - Full replacement document.
-     * @param options - MongoDB FindOneAndReplaceOptions.
-     * @returns The document before or after replacement, or null when not found.
-     * @since v1.0.0
-     */
-    findOneAndReplace(filter?: unknown, replacement?: unknown, options?: unknown): Promise<TSchema | null>;
-    /**
-     * Atomically finds the first matching document, applies an update, and returns a document.
-     * @param filter - MongoDB filter query.
-     * @param update - Update operators.
-     * @param options - MongoDB FindOneAndUpdateOptions.
-     * @returns The document before or after the update, or null when not found.
-     * @since v1.0.0
-     */
-    findOneAndUpdate(filter?: unknown, update?: unknown, options?: unknown): Promise<TSchema | null>;
-    /**
-     * Atomically finds the first matching document, deletes it, and returns it.
-     * @param filter - MongoDB filter query.
-     * @param options - MongoDB FindOneAndDeleteOptions.
-     * @returns The deleted document, or null when not found.
-     * @since v1.0.0
-     */
-    findOneAndDelete(filter?: unknown, options?: unknown): Promise<TSchema | null>;
-    /**
-     * Updates the first matching document or inserts it when no match exists.
-     * @param filter - MongoDB filter query.
-     * @param update - Update operators.
-     * @param options - MongoDB UpdateOptions (upsert is forced true).
-     * @returns Update result; `upsertedId` is set when a new document was inserted.
-     * @since v1.0.0
-     */
-    upsertOne(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
-    /**
-     * Deletes the first document matching the filter.
-     * @param filter - MongoDB filter query.
-     * @param options - MongoDB DeleteOptions.
-     * @returns Delete result with the deleted document count.
-     * @since v1.0.0
-     */
-    deleteOne(filter?: unknown, options?: unknown): Promise<DeleteResult>;
-    /**
-     * Deletes all documents matching the filter.
-     * @param filter - MongoDB filter query.
-     * @param options - MongoDB DeleteOptions.
-     * @returns Delete result with the total deleted count.
-     * @since v1.0.0
-     */
-    deleteMany(filter?: unknown, options?: unknown): Promise<DeleteResult>;
-    /**
-     * Inserts a large document array in configurable batches with progress and retry support.
-     * @param documents - Documents to insert.
-     * @param options - InsertBatchOptions (batchSize, concurrency, onProgress, …).
-     * @returns Aggregated insert result across all batches.
-     * @since v1.2.0
-     */
-    insertBatch(documents?: unknown[], options?: unknown): Promise<InsertBatchResult>;
-    /**
-     * Updates matched documents in configurable batches, walking via a cursor.
-     * @param filter - MongoDB filter query.
-     * @param update - Update operators.
-     * @param options - UpdateBatchOptions (batchSize, upsert, onProgress, …).
-     * @returns Aggregated update result across all batches.
-     * @since v1.2.0
-     */
-    updateBatch(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateBatchResult>;
-    /**
-     * Deletes matched documents in configurable batches.
-     * @param filter - MongoDB filter query.
-     * @param options - DeleteBatchOptions (batchSize, onProgress, …).
-     * @returns Aggregated delete result across all batches.
-     * @since v1.2.0
-     */
-    deleteBatch(filter?: unknown, options?: unknown): Promise<DeleteBatchResult>;
-    /**
-     * Atomically increments a numeric field on the first matching document.
-     * @param filter - MongoDB filter query.
-     * @param field - Field name (string) or a `{ field: delta }` map for multi-field increments.
-     * @param incrementOrOptions - Numeric delta when `field` is a string, or IncrementOneOptions.
-     * @param maybeOptions - IncrementOneOptions when the third argument is the delta.
-     * @returns Result containing matched/modified counts and the returned document value.
-     * @since v1.1.0
-     */
-    incrementOne(filter?: unknown, field?: string | Record<string, number>, incrementOrOptions?: unknown, maybeOptions?: unknown): Promise<IncrementOneResult<TSchema>>;
-    /**
-     * Creates a single index on the collection.
-     * @param keys - Index key specification.
-     * @param options - MongoDB CreateIndexesOptions (name, unique, sparse, …).
-     * @returns Object containing the created index name.
-     * @since v1.0.0
-     */
-    createIndex(keys: unknown, options?: unknown): Promise<IndexCreateResult>;
-    /**
-     * Creates multiple indexes on the collection in one operation.
-     * @param specs - Array of index specifications (each must include a `key` field).
-     * @returns Array of created index names.
-     * @since v1.0.0
-     */
-    createIndexes(specs: Array<{ key: unknown; } & Record<string, unknown>>): Promise<string[]>;
-    /**
-     * Lists all indexes defined on the collection.
-     * @returns Array of index descriptor objects as returned by MongoDB.
-     */
-    listIndexes(): Promise<Record<string, unknown>[]>;
-    /**
-     * Drops the named index from the collection.
-     * @param name - The index name to drop.
-     * @since v1.0.0
-     */
-    dropIndex(name: string): Promise<unknown>;
-    /**
-     * Drops all non-`_id` indexes from the collection.
-     * @since v1.0.0
-     */
-    dropIndexes(): Promise<unknown>;
-    prewarmBookmarks(keyDims?: unknown, pages?: number[]): Promise<BookmarkPrewarmResult>;
-    listBookmarks(keyDims?: unknown): Promise<BookmarkListResult>;
-    clearBookmarks(keyDims?: unknown): Promise<BookmarkClearResult>;
-    /**
-     * Returns the distinct values for the specified field across matching documents.
-     * @param key - Field path to collect distinct values from.
-     * @param query - Optional MongoDB filter query.
-     * @param options - MongoDB DistinctOptions.
-     * @returns Array of unique field values.
-     */
-    distinct(key: string, query: unknown | undefined, options: QueryMetaOption): Promise<ResultWithMeta<unknown[]>>;
-    distinct(key: string, query?: unknown, options?: unknown): Promise<unknown[]>;
-    /**
-     * Builds and executes an aggregation pipeline, returning a chainable object.
-     * @param pipeline - Array of aggregation stage documents.
-     * @param options - MongoDB AggregateOptions.
-     * @returns AggregateChain that resolves to the result array.
-     */
-    aggregate<TResult = unknown>(pipeline: unknown[] | undefined, options: QueryMetaOption): AggregateChain<TResult, ResultWithMeta<TResult[]>>;
-    aggregate<TResult = unknown>(pipeline?: unknown[], options?: unknown): AggregateChain<TResult>;
+    /**
+     * Finds a single document by its `_id` value.
+     * @param id - The `_id` value to look up.
+     * @param options - MongoDB FindOptions.
+     * @returns The matched document, or null when not found.
+     */
+    findOneById(id: unknown, options?: unknown): Promise<TSchema | null>;
+    /**
+     * Fetches multiple documents by their `_id` values in a single query.
+     * @param ids - Array of `_id` values to look up.
+     * @param options - MongoDB FindOptions.
+     * @returns Array of matched documents (order not guaranteed).
+     */
+    findByIds(ids: unknown[], options?: unknown): Promise<TSchema[]>;
+    /**
+     * Finds documents matching the query and returns both the data array and
+     * the total count unaffected by limit/skip.
+     * @param query - MongoDB filter query.
+     * @param options - MongoDB FindOptions.
+     * @returns Object with `data` array and `total` count.
+     */
+    findAndCount(query?: unknown, options?: unknown): Promise<FindAndCountResult<TSchema>>;
+    /**
+     * Returns a Node.js ReadableStream of documents matching the query.
+     * @param query - MongoDB filter query.
+     * @param options - StreamOptions (projection, sort, limit, batchSize, …).
+     * @returns Readable object-mode stream emitting one document per chunk.
+     */
+    stream(query?: unknown, options?: unknown): NodeJS.ReadableStream;
+    /**
+     * Returns the MongoDB query execution plan without running the full query.
+     * @param query - MongoDB filter query.
+     * @param options - ExplainOptions including verbosity level.
+     * @returns Raw explain output from MongoDB.
+     */
+    explain(query?: unknown, options?: unknown): Promise<unknown>;
+    /**
+     * Counts documents matching the query.
+     * @param query - MongoDB filter query.
+     * @param options - MongoDB CountDocumentsOptions.
+     * @returns Number of matched documents.
+     */
+    count(query: unknown | undefined, options: QueryMetaOption): Promise<ResultWithMeta<number>>;
+    count(query?: unknown, options?: unknown): Promise<number>;
+    /**
+     * Inserts a single document into the collection.
+     * @param document - Document to insert.
+     * @param options - InsertOneSimplifiedOptions or InsertOneOptions.
+     * @returns Acknowledged result with the inserted `_id`.
+     * @since v1.0.0
+     */
+    insertOne(document?: unknown, options?: unknown): Promise<InsertOneResult>;
+    /**
+     * Inserts multiple documents into the collection in a single operation.
+     * @param documents - Array of documents to insert.
+     * @param options - InsertManySimplifiedOptions or InsertManyOptions.
+     * @returns Acknowledged result with inserted count and `_id` map.
+     * @since v1.0.0
+     */
+    insertMany(documents?: unknown[], options?: unknown): Promise<InsertManyResult>;
+    /**
+     * Updates the first document matching the filter.
+     * @param filter - MongoDB filter query.
+     * @param update - Update operators (e.g. `$set`, `$inc`).
+     * @param options - MongoDB UpdateOptions.
+     * @returns Update result with matched/modified counts.
+     * @since v1.0.0
+     */
+    updateOne(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    /**
+     * Updates all documents matching the filter.
+     * @param filter - MongoDB filter query.
+     * @param update - Update operators.
+     * @param options - MongoDB UpdateOptions.
+     * @returns Update result with matched/modified counts.
+     * @since v1.0.0
+     */
+    updateMany(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    /**
+     * Replaces the first document matching the filter with a new document.
+     * @param filter - MongoDB filter query.
+     * @param replacement - Full replacement document (no update operators).
+     * @param options - MongoDB ReplaceOptions.
+     * @returns Update result indicating match and modification.
+     * @since v1.0.0
+     */
+    replaceOne(filter?: unknown, replacement?: unknown, options?: unknown): Promise<UpdateResult>;
+    /**
+     * Atomically finds the first matching document, replaces it, and returns a document.
+     * @param filter - MongoDB filter query.
+     * @param replacement - Full replacement document.
+     * @param options - MongoDB FindOneAndReplaceOptions.
+     * @returns The document before or after replacement, or null when not found.
+     * @since v1.0.0
+     */
+    findOneAndReplace(filter?: unknown, replacement?: unknown, options?: unknown): Promise<TSchema | null>;
+    /**
+     * Atomically finds the first matching document, applies an update, and returns a document.
+     * @param filter - MongoDB filter query.
+     * @param update - Update operators.
+     * @param options - MongoDB FindOneAndUpdateOptions.
+     * @returns The document before or after the update, or null when not found.
+     * @since v1.0.0
+     */
+    findOneAndUpdate(filter?: unknown, update?: unknown, options?: unknown): Promise<TSchema | null>;
+    /**
+     * Atomically finds the first matching document, deletes it, and returns it.
+     * @param filter - MongoDB filter query.
+     * @param options - MongoDB FindOneAndDeleteOptions.
+     * @returns The deleted document, or null when not found.
+     * @since v1.0.0
+     */
+    findOneAndDelete(filter?: unknown, options?: unknown): Promise<TSchema | null>;
+    /**
+     * Updates the first matching document or inserts it when no match exists.
+     * @param filter - MongoDB filter query.
+     * @param update - Update operators.
+     * @param options - MongoDB UpdateOptions (upsert is forced true).
+     * @returns Update result; `upsertedId` is set when a new document was inserted.
+     * @since v1.0.0
+     */
+    upsertOne(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    /**
+     * Deletes the first document matching the filter.
+     * @param filter - MongoDB filter query.
+     * @param options - MongoDB DeleteOptions.
+     * @returns Delete result with the deleted document count.
+     * @since v1.0.0
+     */
+    deleteOne(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    /**
+     * Deletes all documents matching the filter.
+     * @param filter - MongoDB filter query.
+     * @param options - MongoDB DeleteOptions.
+     * @returns Delete result with the total deleted count.
+     * @since v1.0.0
+     */
+    deleteMany(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    /**
+     * Inserts a large document array in configurable batches with progress and retry support.
+     * @param documents - Documents to insert.
+     * @param options - InsertBatchOptions (batchSize, concurrency, onProgress, …).
+     * @returns Aggregated insert result across all batches.
+     * @since v1.2.0
+     */
+    insertBatch(documents?: unknown[], options?: unknown): Promise<InsertBatchResult>;
+    /**
+     * Updates matched documents in configurable batches, walking via a cursor.
+     * @param filter - MongoDB filter query.
+     * @param update - Update operators.
+     * @param options - UpdateBatchOptions (batchSize, upsert, onProgress, …).
+     * @returns Aggregated update result across all batches.
+     * @since v1.2.0
+     */
+    updateBatch(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateBatchResult>;
+    /**
+     * Deletes matched documents in configurable batches.
+     * @param filter - MongoDB filter query.
+     * @param options - DeleteBatchOptions (batchSize, onProgress, …).
+     * @returns Aggregated delete result across all batches.
+     * @since v1.2.0
+     */
+    deleteBatch(filter?: unknown, options?: unknown): Promise<DeleteBatchResult>;
+    /**
+     * Atomically increments a numeric field on the first matching document.
+     * @param filter - MongoDB filter query.
+     * @param field - Field name (string) or a `{ field: delta }` map for multi-field increments.
+     * @param incrementOrOptions - Numeric delta when `field` is a string, or IncrementOneOptions.
+     * @param maybeOptions - IncrementOneOptions when the third argument is the delta.
+     * @returns Result containing matched/modified counts and the returned document value.
+     * @since v1.1.0
+     */
+    incrementOne(filter?: unknown, field?: string | Record<string, number>, incrementOrOptions?: unknown, maybeOptions?: unknown): Promise<IncrementOneResult<TSchema>>;
+    /**
+     * Creates a single index on the collection.
+     * @param keys - Index key specification.
+     * @param options - MongoDB CreateIndexesOptions (name, unique, sparse, …).
+     * @returns Object containing the created index name.
+     * @since v1.0.0
+     */
+    createIndex(keys: unknown, options?: unknown): Promise<IndexCreateResult>;
+    /**
+     * Creates multiple indexes on the collection in one operation.
+     * @param specs - Array of index specifications (each must include a `key` field).
+     * @returns Array of created index names.
+     * @since v1.0.0
+     */
+    createIndexes(specs: Array<{ key: unknown; } & Record<string, unknown>>): Promise<string[]>;
+    /**
+     * Lists all indexes defined on the collection.
+     * @returns Array of index descriptor objects as returned by MongoDB.
+     */
+    listIndexes(): Promise<Record<string, unknown>[]>;
+    /**
+     * Drops the named index from the collection.
+     * @param name - The index name to drop.
+     * @since v1.0.0
+     */
+    dropIndex(name: string): Promise<unknown>;
+    /**
+     * Drops all non-`_id` indexes from the collection.
+     * @since v1.0.0
+     */
+    dropIndexes(): Promise<unknown>;
+    prewarmBookmarks(keyDims?: unknown, pages?: number[]): Promise<BookmarkPrewarmResult>;
+    listBookmarks(keyDims?: unknown): Promise<BookmarkListResult>;
+    clearBookmarks(keyDims?: unknown): Promise<BookmarkClearResult>;
+    /**
+     * Returns the distinct values for the specified field across matching documents.
+     * @param key - Field path to collect distinct values from.
+     * @param query - Optional MongoDB filter query.
+     * @param options - MongoDB DistinctOptions.
+     * @returns Array of unique field values.
+     */
+    distinct(key: string, query: unknown | undefined, options: QueryMetaOption): Promise<ResultWithMeta<unknown[]>>;
+    distinct(key: string, query?: unknown, options?: unknown): Promise<unknown[]>;
+    /**
+     * Builds and executes an aggregation pipeline, returning a chainable object.
+     * @param pipeline - Array of aggregation stage documents.
+     * @param options - MongoDB AggregateOptions.
+     * @returns AggregateChain that resolves to the result array.
+     */
+    aggregate<TResult = unknown>(pipeline: unknown[] | undefined, options: QueryMetaOption): AggregateChain<TResult, ResultWithMeta<TResult[]>>;
+    aggregate<TResult = unknown>(pipeline?: unknown[], options?: unknown): AggregateChain<TResult>;
     /** Stream mode: returns a readable stream of page documents when `stream: true`. */
     findPage(options: FindPageOptions<TSchema> & { stream: true }): NodeJS.ReadableStream;
     /** Sync totals mode guarantees `totals.total` and `totals.totalPages` are immediately available. */
     findPage(options: FindPageOptions<TSchema> & { totals: { mode: 'sync'; } & Record<string, unknown> }): Promise<Omit<FindPageResult<TSchema>, 'totals'> & { totals: LegacySyncTotalsInfo<TSchema> }>;
     /** Returns a cursor-based paginated result set. */
     findPage(options?: FindPageOptions<TSchema>): Promise<FindPageResult<TSchema>>;
-    /**
-     * Opens a MongoDB change stream to listen for collection-level change events.
-     * @param pipeline - Optional aggregation pipeline to filter/transform events.
-     * @param options - MongoDB ChangeStreamOptions.
-     * @returns A ChangeStream instance emitting change event documents.
-     */
-    watch(pipeline?: unknown[], options?: unknown): ChangeStream;
-    /**
-     * Manually invalidates cached query results for the specified operation type.
-     * @param op - Operation whose cache entries to clear; omit to clear all.
-     * @returns Number of cache entries removed.
-     * @since v1.3.0
-     */
-    invalidate(op?: 'find' | 'findOne' | 'count' | 'findPage' | 'aggregate' | 'distinct'): Promise<number>;
-    /**
-     * Drops the entire collection from the database.
-     * @returns True when the collection was dropped successfully.
-     * @since v1.3.0
-     */
-    dropCollection(): Promise<boolean>;
-    /**
-     * Creates a new collection (or capped collection) in the database.
-     * @param name - Collection name; defaults to the current collection name when omitted.
-     * @param options - MongoDB CreateCollectionOptions (capped, size, validator, …).
-     * @returns True when the collection was created successfully.
-     * @since v1.3.0
-     */
-    createCollection(name?: string, options?: Record<string, unknown>): Promise<boolean>;
-    /**
-     * Creates a MongoDB view backed by an aggregation pipeline over a source collection.
-     * @param name - Name of the view to create.
-     * @param source - Name of the source collection.
-     * @param pipeline - Optional aggregation pipeline defining the view.
-     * @returns True when the view was created successfully.
-     * @since v1.3.0
-     */
-    createView(name: string, source: string, pipeline?: unknown[]): Promise<boolean>;
-    /**
-     * Returns index usage statistics for all indexes on the collection.
-     * @returns Array of `$indexStats` documents from MongoDB.
-     * @since v1.3.0
-     */
-    indexStats(): Promise<unknown[]>;
-    /**
-     * Sets the JSON Schema validator and optional validation settings.
-     * @since v1.3.0
-     */
-    setValidator(validator: unknown, options?: { validationLevel?: string; validationAction?: string }): Promise<{ ok: number; collection: string }>;
-    /** Sets the collection validation level. @since v1.3.0 */
-    setValidationLevel(level: 'off' | 'moderate' | 'strict' | string): Promise<{ ok: number; validationLevel: string }>;
-    /** Sets the collection validation action. @since v1.3.0 */
-    setValidationAction(action: 'error' | 'warn' | string): Promise<{ ok: number; validationAction: string }>;
-    /** Reads the current collection validator and validation settings. @since v1.3.0 */
-    getValidator(): Promise<{ validator: Record<string, unknown> | null; validationLevel: string; validationAction: string }>;
-    /** Returns collection storage and index statistics. @since v1.3.0 */
-    stats(options?: { scale?: number }): Promise<{ ns: string; count: number; size: number; storageSize: number; totalIndexSize: number; nindexes: number; avgObjSize?: number; scaleFactor?: number }>;
-    /** Renames the collection, optionally dropping an existing target. @since v1.3.0 */
-    renameCollection(newName: string, options?: { dropTarget?: boolean }): Promise<{ renamed: boolean; from: string; to: string }>;
-    /** Runs a `collMod` command against the collection. @since v1.3.0 */
-    collMod(modifications: Record<string, unknown>): Promise<Record<string, unknown>>;
-    /** Converts the collection to capped storage. @since v1.3.0 */
-    convertToCapped(size: number, options?: { max?: number }): Promise<{ ok: number; collection: string; capped: boolean; size: number }>;
-}
-
+    /**
+     * Opens a MongoDB change stream to listen for collection-level change events.
+     * @param pipeline - Optional aggregation pipeline to filter/transform events.
+     * @param options - MongoDB ChangeStreamOptions.
+     * @returns A ChangeStream instance emitting change event documents.
+     */
+    watch(pipeline?: unknown[], options?: unknown): ChangeStream;
+    /**
+     * Manually invalidates cached query results for the specified operation type.
+     * @param op - Operation whose cache entries to clear; omit to clear all.
+     * @returns Number of cache entries removed.
+     * @since v1.3.0
+     */
+    invalidate(op?: 'find' | 'findOne' | 'count' | 'findPage' | 'aggregate' | 'distinct'): Promise<number>;
+    /**
+     * Drops the entire collection from the database.
+     * @returns True when the collection was dropped successfully.
+     * @since v1.3.0
+     */
+    dropCollection(): Promise<boolean>;
+    /**
+     * Creates a new collection (or capped collection) in the database.
+     * @param name - Collection name; defaults to the current collection name when omitted.
+     * @param options - MongoDB CreateCollectionOptions (capped, size, validator, …).
+     * @returns True when the collection was created successfully.
+     * @since v1.3.0
+     */
+    createCollection(name?: string, options?: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Creates a MongoDB view backed by an aggregation pipeline over a source collection.
+     * @param name - Name of the view to create.
+     * @param source - Name of the source collection.
+     * @param pipeline - Optional aggregation pipeline defining the view.
+     * @returns True when the view was created successfully.
+     * @since v1.3.0
+     */
+    createView(name: string, source: string, pipeline?: unknown[]): Promise<boolean>;
+    /**
+     * Returns index usage statistics for all indexes on the collection.
+     * @returns Array of `$indexStats` documents from MongoDB.
+     * @since v1.3.0
+     */
+    indexStats(): Promise<unknown[]>;
+    /**
+     * Sets the JSON Schema validator and optional validation settings.
+     * @since v1.3.0
+     */
+    setValidator(validator: unknown, options?: { validationLevel?: string; validationAction?: string }): Promise<{ ok: number; collection: string }>;
+    /** Sets the collection validation level. @since v1.3.0 */
+    setValidationLevel(level: 'off' | 'moderate' | 'strict' | string): Promise<{ ok: number; validationLevel: string }>;
+    /** Sets the collection validation action. @since v1.3.0 */
+    setValidationAction(action: 'error' | 'warn' | string): Promise<{ ok: number; validationAction: string }>;
+    /** Reads the current collection validator and validation settings. @since v1.3.0 */
+    getValidator(): Promise<{ validator: Record<string, unknown> | null; validationLevel: string; validationAction: string }>;
+    /** Returns collection storage and index statistics. @since v1.3.0 */
+    stats(options?: { scale?: number }): Promise<{ ns: string; count: number; size: number; storageSize: number; totalIndexSize: number; nindexes: number; avgObjSize?: number; scaleFactor?: number }>;
+    /** Renames the collection, optionally dropping an existing target. @since v1.3.0 */
+    renameCollection(newName: string, options?: { dropTarget?: boolean }): Promise<{ renamed: boolean; from: string; to: string }>;
+    /** Runs a `collMod` command against the collection. @since v1.3.0 */
+    collMod(modifications: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Converts the collection to capped storage. @since v1.3.0 */
+    convertToCapped(size: number, options?: { max?: number }): Promise<{ ok: number; collection: string; capped: boolean; size: number }>;
+}
+
 export interface DbAccessor {
-    /**
-     * Returns a typed Collection accessor for the named collection.
-     * @param name - MongoDB collection name.
-     * @returns Collection instance bound to the specified collection.
-     */
+    /**
+     * Returns a typed Collection accessor for the named collection.
+     * @param name - MongoDB collection name.
+     * @returns Collection instance bound to the specified collection.
+     */
     collection<TSchema = any>(name: string): Collection<TSchema>;
-    /** Returns the underlying native MongoDB Db object. */
-    raw(): unknown;
-    /** Returns an AdminAccessor for server-level administrative operations. */
-    admin(): AdminAccessor;
-    /**
-     * Lists all databases available on the server.
-     * @param options - Pass `nameOnly: true` to return string names instead of full descriptors.
-     * @returns Array of database descriptor objects, or string names when `nameOnly` is true.
-     * @since v1.3.0
-     */
-    listDatabases(options?: { nameOnly?: boolean }): Promise<Array<{ name: string; sizeOnDisk: number; empty: boolean }> | string[]>;
-    /**
-     * Drops the current database; requires explicit confirmation to prevent accidental data loss.
-     * @param options - Must include `confirm: true`; optionally restrict to non-production environments.
-     * @returns Result object with the dropped database name and timestamp.
-     * @since v1.3.0
-     */
-    dropDatabase(options?: { confirm: boolean; allowProduction?: boolean; user?: string }): Promise<{ dropped: boolean; database: string; timestamp: Date }>;
-    /**
-     * Lists collections (and views) in the current database.
-     * @param filter - Optional MongoDB filter applied to the collection list.
-     * @param options - MongoDB ListCollectionsOptions.
-     * @returns Array of objects with `name` and `type` fields.
-     * @since v1.3.0
-     */
-    listCollections(filter?: Record<string, unknown>, options?: Record<string, unknown>): Promise<Array<{ name: string; type: string }>>;
-    /**
-     * Runs an arbitrary command against the current database.
-     * @param command - Command document (e.g. `{ ping: 1 }`).
-     * @param options - MongoDB RunCommandOptions.
-     * @returns Raw command result document from MongoDB.
-     * @since v1.3.0
-     */
-    runCommand(command: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
-}
-
-// ---------------------------------------------------------------------------
-// v1 backward-compat name aliases
-// ---------------------------------------------------------------------------
-
-/** @alias FindPageResult — v1 called the findPage result PageResult */
+    /** Returns the underlying native MongoDB Db object. */
+    raw(): unknown;
+    /** Returns an AdminAccessor for server-level administrative operations. */
+    admin(): AdminAccessor;
+    /**
+     * Lists all databases available on the server.
+     * @param options - Pass `nameOnly: true` to return string names instead of full descriptors.
+     * @returns Array of database descriptor objects, or string names when `nameOnly` is true.
+     * @since v1.3.0
+     */
+    listDatabases(options?: { nameOnly?: boolean }): Promise<Array<{ name: string; sizeOnDisk: number; empty: boolean }> | string[]>;
+    /**
+     * Drops the current database; requires explicit confirmation to prevent accidental data loss.
+     * @param options - Must include `confirm: true`; optionally restrict to non-production environments.
+     * @returns Result object with the dropped database name and timestamp.
+     * @since v1.3.0
+     */
+    dropDatabase(options?: { confirm: boolean; allowProduction?: boolean; user?: string }): Promise<{ dropped: boolean; database: string; timestamp: Date }>;
+    /**
+     * Lists collections (and views) in the current database.
+     * @param filter - Optional MongoDB filter applied to the collection list.
+     * @param options - MongoDB ListCollectionsOptions.
+     * @returns Array of objects with `name` and `type` fields.
+     * @since v1.3.0
+     */
+    listCollections(filter?: Record<string, unknown>, options?: Record<string, unknown>): Promise<Array<{ name: string; type: string }>>;
+    /**
+     * Runs an arbitrary command against the current database.
+     * @param command - Command document (e.g. `{ ping: 1 }`).
+     * @param options - MongoDB RunCommandOptions.
+     * @returns Raw command result document from MongoDB.
+     * @since v1.3.0
+     */
+    runCommand(command: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+// ---------------------------------------------------------------------------
+// v1 backward-compat name aliases
+// ---------------------------------------------------------------------------
+
+/** @alias FindPageResult — v1 called the findPage result PageResult */
 export type PageResult<T = any> = FindPageResult<T>;
-
-/** @alias BookmarkPrewarmResult — v1 name */
-export type PrewarmBookmarksResult = BookmarkPrewarmResult;
-
-/** @alias BookmarkListResult — v1 name */
-export type ListBookmarksResult = BookmarkListResult;
-
-/** @alias BookmarkClearResult — v1 name */
-export type ClearBookmarksResult = BookmarkClearResult;
-
-// ---------------------------------------------------------------------------
-// Write options (v1 parity)
-// ---------------------------------------------------------------------------
-
-/** Simplified insertOne options (used for the shorthand call form). */
-export interface InsertOneSimplifiedOptions {
-    writeConcern?: WriteConcern;
-    bypassDocumentValidation?: boolean;
-    comment?: string;
-    session?: unknown;
-    /** Invalidate query cache on success. @since v1.1.5 */
-    autoInvalidate?: boolean;
-}
-
-/** Full insertOne options (document + write configuration). */
-export interface InsertOneOptions {
-    document: unknown;
-    writeConcern?: WriteConcern;
-    bypassDocumentValidation?: boolean;
-    comment?: string;
-}
-
-/** Simplified insertMany options (used for the shorthand call form). */
-export interface InsertManySimplifiedOptions {
-    ordered?: boolean;
-    writeConcern?: WriteConcern;
-    bypassDocumentValidation?: boolean;
-    comment?: string;
-    session?: unknown;
-    /** Invalidate query cache on success. @since v1.1.5 */
-    autoInvalidate?: boolean;
-}
-
-/** Full insertMany options (documents array + write configuration). */
-export interface InsertManyOptions {
-    documents: unknown[];
-    ordered?: boolean;
-    writeConcern?: WriteConcern;
-    bypassDocumentValidation?: boolean;
-    comment?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Chain helpers (v1 parity)
-// ---------------------------------------------------------------------------
-
-/**
- * Collation options for locale-aware string comparison.
- * @since v1.0.0
- */
-export interface CollationOptions {
-    /** IETF language tag, e.g. 'en', 'zh'. */
-    locale: string;
-    /** Comparison strength: 1=base, 2=accent, 3=case. */
-    strength?: number;
-    /** Distinguish uppercase from lowercase at strength < 3. */
-    caseLevel?: boolean;
-    /** Which case is sorted first when cases are equal. */
-    caseFirst?: 'upper' | 'lower';
-    /** Sort numeric strings numerically, not lexicographically. */
-    numericOrdering?: boolean;
-    /** How spaces and punctuation are handled. */
-    alternate?: 'non-ignorable' | 'shifted';
-    /** Highest ignored character category. */
-    maxVariable?: 'punct' | 'space';
-    /** Sort secondary weights in reverse order. */
-    backwards?: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Pagination helpers (v1 parity)
-// ---------------------------------------------------------------------------
-
-/**
- * Query result with attached metadata (timing, cache, totals).
- * @since v1.3.0
- */
-export interface ResultWithMeta<T = unknown> {
-    data: T;
-    meta: MetaInfo;
-}
-
-// ---------------------------------------------------------------------------
-// Collection accessor alias (v1 parity)
-// ---------------------------------------------------------------------------
-
-/** @alias Collection — v1 called the collection accessor CollectionAccessor */
+
+/** @alias BookmarkPrewarmResult — v1 name */
+export type PrewarmBookmarksResult = BookmarkPrewarmResult;
+
+/** @alias BookmarkListResult — v1 name */
+export type ListBookmarksResult = BookmarkListResult;
+
+/** @alias BookmarkClearResult — v1 name */
+export type ClearBookmarksResult = BookmarkClearResult;
+
+// ---------------------------------------------------------------------------
+// Write options (v1 parity)
+// ---------------------------------------------------------------------------
+
+/** Simplified insertOne options (used for the shorthand call form). */
+export interface InsertOneSimplifiedOptions {
+    writeConcern?: WriteConcern;
+    bypassDocumentValidation?: boolean;
+    comment?: string;
+    session?: unknown;
+    /** Invalidate query cache on success. @since v1.1.5 */
+    autoInvalidate?: boolean;
+}
+
+/** Full insertOne options (document + write configuration). */
+export interface InsertOneOptions {
+    document: unknown;
+    writeConcern?: WriteConcern;
+    bypassDocumentValidation?: boolean;
+    comment?: string;
+}
+
+/** Simplified insertMany options (used for the shorthand call form). */
+export interface InsertManySimplifiedOptions {
+    ordered?: boolean;
+    writeConcern?: WriteConcern;
+    bypassDocumentValidation?: boolean;
+    comment?: string;
+    session?: unknown;
+    /** Invalidate query cache on success. @since v1.1.5 */
+    autoInvalidate?: boolean;
+}
+
+/** Full insertMany options (documents array + write configuration). */
+export interface InsertManyOptions {
+    documents: unknown[];
+    ordered?: boolean;
+    writeConcern?: WriteConcern;
+    bypassDocumentValidation?: boolean;
+    comment?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Chain helpers (v1 parity)
+// ---------------------------------------------------------------------------
+
+/**
+ * Collation options for locale-aware string comparison.
+ * @since v1.0.0
+ */
+export interface CollationOptions {
+    /** IETF language tag, e.g. 'en', 'zh'. */
+    locale: string;
+    /** Comparison strength: 1=base, 2=accent, 3=case. */
+    strength?: number;
+    /** Distinguish uppercase from lowercase at strength < 3. */
+    caseLevel?: boolean;
+    /** Which case is sorted first when cases are equal. */
+    caseFirst?: 'upper' | 'lower';
+    /** Sort numeric strings numerically, not lexicographically. */
+    numericOrdering?: boolean;
+    /** How spaces and punctuation are handled. */
+    alternate?: 'non-ignorable' | 'shifted';
+    /** Highest ignored character category. */
+    maxVariable?: 'punct' | 'space';
+    /** Sort secondary weights in reverse order. */
+    backwards?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Pagination helpers (v1 parity)
+// ---------------------------------------------------------------------------
+
+/**
+ * Query result with attached metadata (timing, cache, totals).
+ * @since v1.3.0
+ */
+export interface ResultWithMeta<T = unknown> {
+    data: T;
+    meta: MetaInfo;
+}
+
+// ---------------------------------------------------------------------------
+// Collection accessor alias (v1 parity)
+// ---------------------------------------------------------------------------
+
+/** @alias Collection — v1 called the collection accessor CollectionAccessor */
 export type CollectionAccessor<TSchema = any> = Collection<TSchema>;
-
+