monsqlize 3.3.0 → 3.3.2

package/dist/types/base.d.mts

@@ -25,7 +25,7 @@ export interface LoggerLike {
 export interface LoggerOptions {
     /** Enable structured (JSON) log output. */
     structured?: boolean;
-    /** Enable automatic trace ID injection into log entries. */
+    /** Attach the current trace ID to structured logs by default; false disables injection. */
     enableTraceId?: boolean;
 }
 

package/dist/types/base.d.ts

@@ -25,7 +25,7 @@ export interface LoggerLike {
 export interface LoggerOptions {
     /** Enable structured (JSON) log output. */
     structured?: boolean;
-    /** Enable automatic trace ID injection into log entries. */
+    /** Attach the current trace ID to structured logs by default; false disables injection. */
     enableTraceId?: boolean;
 }
 

package/dist/types/collection.d.mts

@@ -1,11 +1,9 @@
 import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb';
 import type {
-    AggregateOptions,
     MetaOptions,
     VectorSearchHit,
     VectorSearchOptions,
 } from './aggregation.mjs';
-
 export type {
     AggregateOptions,
     MetaOptions,
@@ -323,6 +321,8 @@ export interface FindPageOptions<TSchema = any> {
     cursorTypes?: Record<string, CursorValueType>;
     /** Custom cursor value normalizer. Receives the sort field name and decoded cursor value. */
     cursorValueNormalizer?: CursorValueNormalizer;
+    /** Stable strategy identity and version. A per-query normalizer needs its own explicit version. */
+    cursorValueNormalizerVersion?: string;
     options?: MongoFindOptions;
     /** Cursor-walking bookmark jump configuration */
     jump?: JumpOptions;
@@ -332,8 +332,8 @@ export interface FindPageOptions<TSchema = any> {
     hint?: Document | string;
     collation?: Document;
     batchSize?: number;
-    /** Cache TTL in milliseconds for the non-stream/non-explain page result */
-    cache?: number;
+    /** MongoDB expression variables; overrides `options.let` when both are supplied. */ let?: Document;
+    /** Cache TTL in milliseconds for the non-stream/non-explain page result */ cache?: number;
     /** Include timing/meta info in result — pass true or MetaOptions for sub-step detail */
     meta?: boolean | MetaOptions;
 }
@@ -365,7 +365,7 @@ export interface FindChain<TSchema = any, TPromise = TSchema[]> extends Promise<
     batchSize(value: number): FindChain<TSchema, TPromise>;
     explain(verbosity?: boolean | string): Promise<unknown>;
     stream(): NodeJS.ReadableStream;
-    toArray(): Promise<TSchema[]>;
+    toArray(): Promise<TPromise>;
 }
 
 export interface AggregateChain<TResult = unknown, TPromise = TResult[]> extends Promise<TPromise> {
@@ -377,7 +377,7 @@ export interface AggregateChain<TResult = unknown, TPromise = TResult[]> extends
     batchSize(value: number): AggregateChain<TResult, TPromise>;
     explain(verbosity?: boolean | string): Promise<unknown>;
     stream(): NodeJS.ReadableStream;
-    toArray(): Promise<TResult[]>;
+    toArray(): Promise<TPromise>;
 }
 
 /** Write concern options for batch operations. */
@@ -504,10 +504,10 @@ export interface UpdateBatchResult {
     errors: BatchErrorRecord[];
     /** Per-batch retry records. */
     retries: BatchRetryRecord[];
-    /** Number of documents skipped by strict model version conflict handling. */
-    conflictCount?: number;
-    /** Document ids skipped by strict model version conflict handling. */
-    conflictedIds?: unknown[];
+    /** Number of documents skipped by strict model version conflict handling. */ conflictCount?: number;
+    /** Document ids skipped by strict model version conflict handling. */ conflictedIds?: unknown[];
+    /** Selected model candidates that no longer match the filter or were removed before writing. */ skippedCount?: number;
+    skippedIds?: unknown[];
 }
 
 export interface DeleteBatchResult {

package/dist/types/collection.d.ts

@@ -1,11 +1,9 @@
 import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb';
 import type {
-    AggregateOptions,
     MetaOptions,
     VectorSearchHit,
     VectorSearchOptions,
 } from './aggregation';
-
 export type {
     AggregateOptions,
     MetaOptions,
@@ -323,6 +321,8 @@ export interface FindPageOptions<TSchema = any> {
     cursorTypes?: Record<string, CursorValueType>;
     /** Custom cursor value normalizer. Receives the sort field name and decoded cursor value. */
     cursorValueNormalizer?: CursorValueNormalizer;
+    /** Stable strategy identity and version. A per-query normalizer needs its own explicit version. */
+    cursorValueNormalizerVersion?: string;
     options?: MongoFindOptions;
     /** Cursor-walking bookmark jump configuration */
     jump?: JumpOptions;
@@ -332,8 +332,8 @@ export interface FindPageOptions<TSchema = any> {
     hint?: Document | string;
     collation?: Document;
     batchSize?: number;
-    /** Cache TTL in milliseconds for the non-stream/non-explain page result */
-    cache?: number;
+    /** MongoDB expression variables; overrides `options.let` when both are supplied. */ let?: Document;
+    /** Cache TTL in milliseconds for the non-stream/non-explain page result */ cache?: number;
     /** Include timing/meta info in result — pass true or MetaOptions for sub-step detail */
     meta?: boolean | MetaOptions;
 }
@@ -365,7 +365,7 @@ export interface FindChain<TSchema = any, TPromise = TSchema[]> extends Promise<
     batchSize(value: number): FindChain<TSchema, TPromise>;
     explain(verbosity?: boolean | string): Promise<unknown>;
     stream(): NodeJS.ReadableStream;
-    toArray(): Promise<TSchema[]>;
+    toArray(): Promise<TPromise>;
 }
 
 export interface AggregateChain<TResult = unknown, TPromise = TResult[]> extends Promise<TPromise> {
@@ -377,7 +377,7 @@ export interface AggregateChain<TResult = unknown, TPromise = TResult[]> extends
     batchSize(value: number): AggregateChain<TResult, TPromise>;
     explain(verbosity?: boolean | string): Promise<unknown>;
     stream(): NodeJS.ReadableStream;
-    toArray(): Promise<TResult[]>;
+    toArray(): Promise<TPromise>;
 }
 
 /** Write concern options for batch operations. */
@@ -504,10 +504,10 @@ export interface UpdateBatchResult {
     errors: BatchErrorRecord[];
     /** Per-batch retry records. */
     retries: BatchRetryRecord[];
-    /** Number of documents skipped by strict model version conflict handling. */
-    conflictCount?: number;
-    /** Document ids skipped by strict model version conflict handling. */
-    conflictedIds?: unknown[];
+    /** Number of documents skipped by strict model version conflict handling. */ conflictCount?: number;
+    /** Document ids skipped by strict model version conflict handling. */ conflictedIds?: unknown[];
+    /** Selected model candidates that no longer match the filter or were removed before writing. */ skippedCount?: number;
+    skippedIds?: unknown[];
 }
 
 export interface DeleteBatchResult {

package/dist/types/data-tasks.d.mts

@@ -155,6 +155,7 @@ export interface DataTaskPreviewOptions {
 }
 
 export interface DataTaskBackupRef {
+    /** Canonical EJSON backup manifest. BSON identities and payloads remain typed when reopened. */
     runId: string;
     manifestPath: string;
     checksum: string;

package/dist/types/data-tasks.d.ts

@@ -155,6 +155,7 @@ export interface DataTaskPreviewOptions {
 }
 
 export interface DataTaskBackupRef {
+    /** Canonical EJSON backup manifest. BSON identities and payloads remain typed when reopened. */
     runId: string;
     manifestPath: string;
     checksum: string;

package/dist/types/index.d.mts

@@ -17,7 +17,9 @@ export { default, MonSQLize } from './monsqlize.mjs';
 export { Model, generateQueryHash, validateSyncConfig } from './runtime.mjs';
 
 export type { Lock as LockContract } from './lock.mjs';
-export type { ModelInstance as ModelAccessor, ModelInstance } from './model.mjs';
+export type { ModelInstance as ModelAccessor } from './model.mjs';
+export type ModelInstance<TDocument = any> = import('./model.mjs').ModelInstance<TDocument>;
+export declare const ModelInstance: typeof import('./runtime.mjs').ModelInstance;
 export type { SyncTargetConfig as SyncTarget } from './sync.mjs';
 export type { Transaction as TransactionContract } from './transaction.mjs';
 export type { MonSQLizeOptions as BaseOptions } from './monsqlize.mjs';

package/dist/types/index.d.ts

@@ -17,7 +17,9 @@ export { default, MonSQLize } from './monsqlize';
 export { Model, generateQueryHash, validateSyncConfig } from './runtime';
 
 export type { Lock as LockContract } from './lock';
-export type { ModelInstance as ModelAccessor, ModelInstance } from './model';
+export type { ModelInstance as ModelAccessor } from './model';
+export type ModelInstance<TDocument = any> = import('./model').ModelInstance<TDocument>;
+export declare const ModelInstance: typeof import('./runtime').ModelInstance;
 export type { SyncTargetConfig as SyncTarget } from './sync';
 export type { Transaction as TransactionContract } from './transaction';
 export type { MonSQLizeOptions as BaseOptions } from './monsqlize';

package/dist/types/model.d.mts

@@ -206,6 +206,9 @@ export type ModelUpdateManyOptions = ModelWriteOptions & {
 export type ModelStrictUpdateManyResult = UpdateResult & {
     conflictCount: number;
     conflictedIds: unknown[];
+    /** Selected candidates no longer matching the business filter or removed before the write. */
+    skippedCount: number;
+    skippedIds: unknown[];
 };
 
 export type ModelIndexSource = 'definition' | 'softDelete';
@@ -405,6 +408,17 @@ type LegacyModelSyncTotalsInfo<TDocument = any> = unknown extends TDocument ? an
 });
 export type RestoreResult = Pick<UpdateResult, 'modifiedCount'> & Partial<UpdateResult>;
 
+export interface ModelPageResult<TDocument = any> {
+    items: Array<ModelDocument<TDocument>>;
+    pageInfo: LegacyModelPageInfo<TDocument>;
+    totals?: LegacyModelTotalsInfo<TDocument>;
+    meta?: import('./collection.mjs').MetaInfo;
+}
+
+export interface ModelSyncPageResult<TDocument = any> extends Omit<ModelPageResult<TDocument>, 'totals'> {
+    totals: LegacyModelSyncTotalsInfo<TDocument>;
+}
+
 export type ModelDocument<TDocument = any> = TDocument & Record<string, unknown> & {
     save(): Promise<ModelDocument<TDocument>>;
     remove(): Promise<boolean>;
@@ -467,18 +481,8 @@ export interface ModelInstance<TDocument = any> {
      * @param options Pagination options including `limit`, `cursor`/`page`, `filter`, and `sort`.
      * @returns Result object containing items, page information, and optional totals.
      */
-    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): PopulateProxy<{
-        items: Array<ModelDocument<TDocument>>;
-        pageInfo: LegacyModelPageInfo<TDocument>;
-        totals: LegacyModelSyncTotalsInfo<TDocument>;
-        meta?: import('./collection.mjs').MetaInfo;
-    }>;
-    findPage(options?: unknown): PopulateProxy<{
-        items: Array<ModelDocument<TDocument>>;
-        pageInfo: LegacyModelPageInfo<TDocument>;
-        totals?: LegacyModelTotalsInfo<TDocument>;
-        meta?: import('./collection.mjs').MetaInfo;
-    }>;
+    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): PopulateProxy<ModelSyncPageResult<TDocument>>;
+    findPage(options?: unknown): PopulateProxy<ModelPageResult<TDocument>>;
     /**
      * Finds documents and returns the unpaginated total count.
      * @param query Optional filter.

package/dist/types/model.d.ts

@@ -206,6 +206,9 @@ export type ModelUpdateManyOptions = ModelWriteOptions & {
 export type ModelStrictUpdateManyResult = UpdateResult & {
     conflictCount: number;
     conflictedIds: unknown[];
+    /** Selected candidates no longer matching the business filter or removed before the write. */
+    skippedCount: number;
+    skippedIds: unknown[];
 };
 
 export type ModelIndexSource = 'definition' | 'softDelete';
@@ -405,6 +408,17 @@ type LegacyModelSyncTotalsInfo<TDocument = any> = unknown extends TDocument ? an
 });
 export type RestoreResult = Pick<UpdateResult, 'modifiedCount'> & Partial<UpdateResult>;
 
+export interface ModelPageResult<TDocument = any> {
+    items: Array<ModelDocument<TDocument>>;
+    pageInfo: LegacyModelPageInfo<TDocument>;
+    totals?: LegacyModelTotalsInfo<TDocument>;
+    meta?: import('./collection').MetaInfo;
+}
+
+export interface ModelSyncPageResult<TDocument = any> extends Omit<ModelPageResult<TDocument>, 'totals'> {
+    totals: LegacyModelSyncTotalsInfo<TDocument>;
+}
+
 export type ModelDocument<TDocument = any> = TDocument & Record<string, unknown> & {
     save(): Promise<ModelDocument<TDocument>>;
     remove(): Promise<boolean>;
@@ -467,18 +481,8 @@ export interface ModelInstance<TDocument = any> {
      * @param options Pagination options including `limit`, `cursor`/`page`, `filter`, and `sort`.
      * @returns Result object containing items, page information, and optional totals.
      */
-    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): PopulateProxy<{
-        items: Array<ModelDocument<TDocument>>;
-        pageInfo: LegacyModelPageInfo<TDocument>;
-        totals: LegacyModelSyncTotalsInfo<TDocument>;
-        meta?: import('./collection').MetaInfo;
-    }>;
-    findPage(options?: unknown): PopulateProxy<{
-        items: Array<ModelDocument<TDocument>>;
-        pageInfo: LegacyModelPageInfo<TDocument>;
-        totals?: LegacyModelTotalsInfo<TDocument>;
-        meta?: import('./collection').MetaInfo;
-    }>;
+    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): PopulateProxy<ModelSyncPageResult<TDocument>>;
+    findPage(options?: unknown): PopulateProxy<ModelPageResult<TDocument>>;
     /**
      * Finds documents and returns the unpaginated total count.
      * @param query Optional filter.

package/dist/types/monsqlize.d.mts

@@ -24,6 +24,10 @@ export interface SSHConfig {
     readyTimeout?: number;
     /** Keep-alive interval in milliseconds (default: 30000). */
     keepaliveInterval?: number;
+    /** ssh2 host-key hash algorithm; pair with hostVerifier for pinned fingerprints. */
+    hostHash?: string;
+    /** Reject untrusted SSH server host keys by returning false. */
+    hostVerifier?: (key: string | Buffer) => boolean;
     /** Target database host as seen from the SSH server (default: auto-parsed from URI). */
     dstHost?: string;
     /** Target database port as seen from the SSH server (default: auto-parsed from URI). */
@@ -210,9 +214,9 @@ export interface MonSQLizeOptions {
         maxRetries?: number;
         retryDelay?: number;
         retryBackoff?: number;
-        /** Default transaction timeout in milliseconds. Alias: `maxDuration`. */
+        /** Default transaction work deadline before commit, in milliseconds. Alias: `maxDuration`. */
         defaultTimeout?: number;
-        /** Default transaction timeout in milliseconds. Alias: `defaultTimeout`. */
+        /** Default transaction work deadline before commit, in milliseconds. Alias: `defaultTimeout`. */
         maxDuration?: number;
         defaultReadConcern?: TransactionOptions['readConcern'];
         defaultWriteConcern?: TransactionOptions['writeConcern'];
@@ -257,6 +261,8 @@ export interface MonSQLizeOptions {
     cursorTypes?: Record<string, CursorValueType>;
     /** Global cursor value normalizer used when findPage decodes after/before tokens. @since v3.0.0 */
     cursorValueNormalizer?: CursorValueNormalizer;
+    /** Stable strategy identity and version, e.g. 'string-id:v1'; bump when conversion changes. */
+    cursorValueNormalizerVersion?: string;
     /** Logging tag configuration applied to slow-query event payloads. @since v1.3.0 */
     log?: { slowQueryTag?: { event?: string; code?: string;[key: string]: unknown }; formatSlowQuery?: (meta: unknown) => unknown; };
     /** Auto-convert valid 24-character hex strings to ObjectId across query/write paths. Pass `false` to disable, or use `excludeFields`, `maxDepth`, or `{ field: false }` escape hatches. Default: true for mongodb type. @since v1.3.0 */

package/dist/types/monsqlize.d.ts

@@ -24,6 +24,10 @@ export interface SSHConfig {
     readyTimeout?: number;
     /** Keep-alive interval in milliseconds (default: 30000). */
     keepaliveInterval?: number;
+    /** ssh2 host-key hash algorithm; pair with hostVerifier for pinned fingerprints. */
+    hostHash?: string;
+    /** Reject untrusted SSH server host keys by returning false. */
+    hostVerifier?: (key: string | Buffer) => boolean;
     /** Target database host as seen from the SSH server (default: auto-parsed from URI). */
     dstHost?: string;
     /** Target database port as seen from the SSH server (default: auto-parsed from URI). */
@@ -210,9 +214,9 @@ export interface MonSQLizeOptions {
         maxRetries?: number;
         retryDelay?: number;
         retryBackoff?: number;
-        /** Default transaction timeout in milliseconds. Alias: `maxDuration`. */
+        /** Default transaction work deadline before commit, in milliseconds. Alias: `maxDuration`. */
         defaultTimeout?: number;
-        /** Default transaction timeout in milliseconds. Alias: `defaultTimeout`. */
+        /** Default transaction work deadline before commit, in milliseconds. Alias: `defaultTimeout`. */
         maxDuration?: number;
         defaultReadConcern?: TransactionOptions['readConcern'];
         defaultWriteConcern?: TransactionOptions['writeConcern'];
@@ -257,6 +261,8 @@ export interface MonSQLizeOptions {
     cursorTypes?: Record<string, CursorValueType>;
     /** Global cursor value normalizer used when findPage decodes after/before tokens. @since v3.0.0 */
     cursorValueNormalizer?: CursorValueNormalizer;
+    /** Stable strategy identity and version, e.g. 'string-id:v1'; bump when conversion changes. */
+    cursorValueNormalizerVersion?: string;
     /** Logging tag configuration applied to slow-query event payloads. @since v1.3.0 */
     log?: { slowQueryTag?: { event?: string; code?: string;[key: string]: unknown }; formatSlowQuery?: (meta: unknown) => unknown; };
     /** Auto-convert valid 24-character hex strings to ObjectId across query/write paths. Pass `false` to disable, or use `excludeFields`, `maxDepth`, or `{ field: false }` escape hatches. Default: true for mongodb type. @since v1.3.0 */

package/dist/types/pool.d.mts

@@ -16,7 +16,9 @@ export interface PoolConfig {
     healthCheck?: {
         enabled?: boolean;
         interval?: number;
+        /** Logical deadline; a timed-out underlying ping still occupies its in-flight slot. */
         timeout?: number;
+        /** Completed failures required before the pool is marked down. */
         retries?: number;
     };
 }
@@ -79,6 +81,7 @@ export declare class ConnectionPoolManager {
     getPoolHealth(): Map<string, PoolHealthStatus>;
     getHealthStatus(): Record<string, PoolHealthStatus>;
     getPoolStats(): Record<string, PoolStats>;
+    /** Attempt all closes; retain failed clients for retry. Concurrent calls share the in-flight close. */
     close(): Promise<void>;
 }
 

package/dist/types/pool.d.ts

@@ -16,7 +16,9 @@ export interface PoolConfig {
     healthCheck?: {
         enabled?: boolean;
         interval?: number;
+        /** Logical deadline; a timed-out underlying ping still occupies its in-flight slot. */
         timeout?: number;
+        /** Completed failures required before the pool is marked down. */
         retries?: number;
     };
 }
@@ -79,6 +81,7 @@ export declare class ConnectionPoolManager {
     getPoolHealth(): Map<string, PoolHealthStatus>;
     getHealthStatus(): Record<string, PoolHealthStatus>;
     getPoolStats(): Record<string, PoolStats>;
+    /** Attempt all closes; retain failed clients for retry. Concurrent calls share the in-flight close. */
     close(): Promise<void>;
 }
 

package/dist/types/runtime.d.mts

@@ -1,5 +1,5 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, UpdateBatchResult, UpdateResult } from './collection.mjs';
-import type { LoggerLike, ExpressionFunction, ExpressionObject } from './base.mjs';
+import type { LoggerLike, LoggerOptions, ExpressionFunction, ExpressionObject } from './base.mjs';
 import type { ModelDefinition, ModelDescriptor, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model.mjs';
 import type { LockOptions, LockStats } from './lock.mjs';
 import type { ConnectionPoolManagerOptions, FallbackStrategy, PoolConfig, PoolHealthStatus, PoolRole, PoolStats, PoolStrategy } from './pool.mjs';
@@ -39,12 +39,18 @@ export { ChangeStreamSyncManager, ResumeTokenStore } from './sync.mjs';
 export { CacheLockManager, Transaction, TransactionManager } from './transaction.mjs';
 
 export declare class Logger {
-    constructor(logger?: LoggerLike | null);
+    constructor(logger?: LoggerLike | null, options?: LoggerOptions);
     debug(...args: unknown[]): void;
     info(...args: unknown[]): void;
     warn(...args: unknown[]): void;
     error(...args: unknown[]): void;
-    static create(logger?: LoggerLike | null): Logger;
+    static create(logger?: LoggerLike | null, options?: LoggerOptions): Logger;
+    static createSilent(): Pick<Logger, 'debug' | 'info' | 'warn' | 'error'>;
+    static generateTraceId(): string;
+    static isValidLogger(logger: unknown): boolean;
+    static withTraceId: ((fn: () => void | Promise<void>, traceId?: string) => void | Promise<void>) | undefined;
+    static getTraceId: (() => string | null) | undefined;
+    static createWithTimestamp(customLogger?: LoggerLike | null): Pick<Logger, 'debug' | 'info' | 'warn' | 'error'>;
 }
 
 export type CacheLockLike = HubCacheLockLike;
@@ -315,26 +321,8 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     findOneById(id: unknown, options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelDocument<TDocument> | null>;
     findById(id: unknown, options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelDocument<TDocument> | null>;
     findByIds(ids: unknown[], options?: unknown): import('./model.mjs').PopulateProxy<Array<import('./model.mjs').ModelDocument<TDocument>>>;
-    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model.mjs').PopulateProxy<{
-        items: Array<import('./model.mjs').ModelDocument<TDocument>>;
-        pageInfo: import('./model.mjs').ModelInstance<TDocument> extends {
-            findPage(options?: unknown): import('./model.mjs').PopulateProxy<infer TResult>;
-        } ? TResult extends { pageInfo: infer TPageInfo } ? TPageInfo : never : never;
-        totals: import('./model.mjs').ModelInstance<TDocument> extends {
-            findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model.mjs').PopulateProxy<infer TResult>;
-        } ? TResult extends { totals: infer TTotals } ? TTotals : never : never;
-        meta?: import('./collection.mjs').MetaInfo;
-    }>;
-    findPage(options?: unknown): import('./model.mjs').PopulateProxy<{
-        items: Array<import('./model.mjs').ModelDocument<TDocument>>;
-        pageInfo: import('./model.mjs').ModelInstance<TDocument> extends {
-            findPage(options?: unknown): import('./model.mjs').PopulateProxy<infer TResult>;
-        } ? TResult extends { pageInfo: infer TPageInfo } ? TPageInfo : never : never;
-        totals?: import('./model.mjs').ModelInstance<TDocument> extends {
-            findPage(options?: unknown): import('./model.mjs').PopulateProxy<infer TResult>;
-        } ? TResult extends { totals?: infer TTotals } ? TTotals : never : never;
-        meta?: import('./collection.mjs').MetaInfo;
-    }>;
+    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelSyncPageResult<TDocument>>;
+    findPage(options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelPageResult<TDocument>>;
     findAndCount(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<{ data: Array<import('./model.mjs').ModelDocument<TDocument>>; total: number; }>;
     vectorSearch(options: import('./model.mjs').ModelVectorSearchOptions): Promise<Array<import('./collection.mjs').VectorSearchHit<import('./model.mjs').ModelDocument<TDocument>>>>;
     count(query?: unknown, options?: unknown): Promise<number>;

package/dist/types/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, UpdateBatchResult, UpdateResult } from './collection';
-import type { LoggerLike, ExpressionFunction, ExpressionObject } from './base';
+import type { LoggerLike, LoggerOptions, ExpressionFunction, ExpressionObject } from './base';
 import type { ModelDefinition, ModelDescriptor, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model';
 import type { LockOptions, LockStats } from './lock';
 import type { ConnectionPoolManagerOptions, FallbackStrategy, PoolConfig, PoolHealthStatus, PoolRole, PoolStats, PoolStrategy } from './pool';
@@ -39,12 +39,18 @@ export { ChangeStreamSyncManager, ResumeTokenStore } from './sync';
 export { CacheLockManager, Transaction, TransactionManager } from './transaction';
 
 export declare class Logger {
-    constructor(logger?: LoggerLike | null);
+    constructor(logger?: LoggerLike | null, options?: LoggerOptions);
     debug(...args: unknown[]): void;
     info(...args: unknown[]): void;
     warn(...args: unknown[]): void;
     error(...args: unknown[]): void;
-    static create(logger?: LoggerLike | null): Logger;
+    static create(logger?: LoggerLike | null, options?: LoggerOptions): Logger;
+    static createSilent(): Pick<Logger, 'debug' | 'info' | 'warn' | 'error'>;
+    static generateTraceId(): string;
+    static isValidLogger(logger: unknown): boolean;
+    static withTraceId: ((fn: () => void | Promise<void>, traceId?: string) => void | Promise<void>) | undefined;
+    static getTraceId: (() => string | null) | undefined;
+    static createWithTimestamp(customLogger?: LoggerLike | null): Pick<Logger, 'debug' | 'info' | 'warn' | 'error'>;
 }
 
 export type CacheLockLike = HubCacheLockLike;
@@ -315,26 +321,8 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     findOneById(id: unknown, options?: unknown): import('./model').PopulateProxy<import('./model').ModelDocument<TDocument> | null>;
     findById(id: unknown, options?: unknown): import('./model').PopulateProxy<import('./model').ModelDocument<TDocument> | null>;
     findByIds(ids: unknown[], options?: unknown): import('./model').PopulateProxy<Array<import('./model').ModelDocument<TDocument>>>;
-    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model').PopulateProxy<{
-        items: Array<import('./model').ModelDocument<TDocument>>;
-        pageInfo: import('./model').ModelInstance<TDocument> extends {
-            findPage(options?: unknown): import('./model').PopulateProxy<infer TResult>;
-        } ? TResult extends { pageInfo: infer TPageInfo } ? TPageInfo : never : never;
-        totals: import('./model').ModelInstance<TDocument> extends {
-            findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model').PopulateProxy<infer TResult>;
-        } ? TResult extends { totals: infer TTotals } ? TTotals : never : never;
-        meta?: import('./collection').MetaInfo;
-    }>;
-    findPage(options?: unknown): import('./model').PopulateProxy<{
-        items: Array<import('./model').ModelDocument<TDocument>>;
-        pageInfo: import('./model').ModelInstance<TDocument> extends {
-            findPage(options?: unknown): import('./model').PopulateProxy<infer TResult>;
-        } ? TResult extends { pageInfo: infer TPageInfo } ? TPageInfo : never : never;
-        totals?: import('./model').ModelInstance<TDocument> extends {
-            findPage(options?: unknown): import('./model').PopulateProxy<infer TResult>;
-        } ? TResult extends { totals?: infer TTotals } ? TTotals : never : never;
-        meta?: import('./collection').MetaInfo;
-    }>;
+    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model').PopulateProxy<import('./model').ModelSyncPageResult<TDocument>>;
+    findPage(options?: unknown): import('./model').PopulateProxy<import('./model').ModelPageResult<TDocument>>;
     findAndCount(query?: unknown, options?: unknown): import('./model').PopulateProxy<{ data: Array<import('./model').ModelDocument<TDocument>>; total: number; }>;
     vectorSearch(options: import('./model').ModelVectorSearchOptions): Promise<Array<import('./collection').VectorSearchHit<import('./model').ModelDocument<TDocument>>>>;
     count(query?: unknown, options?: unknown): Promise<number>;

package/dist/types/slow-query-log.d.mts

@@ -66,12 +66,20 @@ export interface SlowQueryLogConfig {
         minExecutionTimeMs: number;
     };
     advanced: {
+        /** Includes initialization failures; throw waits for direct storage even when batching is enabled. */
         errorHandling: 'log' | 'throw' | 'silent';
+        /** False skips both TTL and unique-index creation without removing existing indexes. */
         autoCreateIndexes: boolean;
     };
 }
 
-export type SlowQueryLogConfigInput = boolean | Partial<SlowQueryLogConfig>;
+export type SlowQueryLogConfigInput = boolean | (
+    Omit<Partial<SlowQueryLogConfig>, 'batch' | 'filter' | 'advanced'> & {
+        batch?: Partial<SlowQueryLogConfig['batch']>;
+        filter?: Partial<SlowQueryLogConfig['filter']>;
+        advanced?: Partial<SlowQueryLogConfig['advanced']>;
+    }
+);
 
 export interface SlowQueryLogStorage {
     initialize(): Promise<void>;

package/dist/types/slow-query-log.d.ts

@@ -66,12 +66,20 @@ export interface SlowQueryLogConfig {
         minExecutionTimeMs: number;
     };
     advanced: {
+        /** Includes initialization failures; throw waits for direct storage even when batching is enabled. */
         errorHandling: 'log' | 'throw' | 'silent';
+        /** False skips both TTL and unique-index creation without removing existing indexes. */
         autoCreateIndexes: boolean;
     };
 }
 
-export type SlowQueryLogConfigInput = boolean | Partial<SlowQueryLogConfig>;
+export type SlowQueryLogConfigInput = boolean | (
+    Omit<Partial<SlowQueryLogConfig>, 'batch' | 'filter' | 'advanced'> & {
+        batch?: Partial<SlowQueryLogConfig['batch']>;
+        filter?: Partial<SlowQueryLogConfig['filter']>;
+        advanced?: Partial<SlowQueryLogConfig['advanced']>;
+    }
+);
 
 export interface SlowQueryLogStorage {
     initialize(): Promise<void>;

package/dist/types/sync.d.mts

@@ -39,6 +39,7 @@ export interface SyncTargetConfig {
 
 export interface SyncTargetApplyContext {
     targetName: string;
+    /** Versioned JSON tuple ["v2", keyPrefix, targetName, rawKey]; treat as opaque. */
     idempotencyKey?: string;
 }
 
@@ -55,13 +56,13 @@ export interface SyncIdempotencyConfig {
     enabled?: boolean;
     /** Optional durable store; when omitted, an in-memory store is used. */
     store?: SyncIdempotencyStoreLike;
-    /** Cache/store key prefix. Defaults to monsqlize:sync:idempotency. */
+    /** Logical prefix inside the versioned tuple. Defaults to monsqlize:sync:idempotency. */
     keyPrefix?: string;
     /** Marker TTL in milliseconds. Store implementations may ignore it. */
     ttl?: number;
     /** Mark after target success by default; start mode requires target-owned recovery for post-mark failures. */
     markMode?: SyncIdempotencyMarkMode;
-    /** Custom event key builder. Return null/undefined to disable idempotency for that event. */
+    /** Builds the raw event key; null/undefined/empty disables it. Inputs and raw return values are unchanged. */
     keyBuilder?: (event: SyncChangeEvent, targetName: string) => string | null | undefined;
 }
 
@@ -71,6 +72,7 @@ export interface ResumeTokenRedisLike {
     del?(key: string): Promise<unknown> | unknown;
 }
 
+/** Stores opaque raw event tokens or a versioned initial EJSON operation-time checkpoint. */
 export interface ResumeTokenConfig {
     storage?: 'file' | 'redis';
     path?: string;

package/dist/types/sync.d.ts

@@ -39,6 +39,7 @@ export interface SyncTargetConfig {
 
 export interface SyncTargetApplyContext {
     targetName: string;
+    /** Versioned JSON tuple ["v2", keyPrefix, targetName, rawKey]; treat as opaque. */
     idempotencyKey?: string;
 }
 
@@ -55,13 +56,13 @@ export interface SyncIdempotencyConfig {
     enabled?: boolean;
     /** Optional durable store; when omitted, an in-memory store is used. */
     store?: SyncIdempotencyStoreLike;
-    /** Cache/store key prefix. Defaults to monsqlize:sync:idempotency. */
+    /** Logical prefix inside the versioned tuple. Defaults to monsqlize:sync:idempotency. */
     keyPrefix?: string;
     /** Marker TTL in milliseconds. Store implementations may ignore it. */
     ttl?: number;
     /** Mark after target success by default; start mode requires target-owned recovery for post-mark failures. */
     markMode?: SyncIdempotencyMarkMode;
-    /** Custom event key builder. Return null/undefined to disable idempotency for that event. */
+    /** Builds the raw event key; null/undefined/empty disables it. Inputs and raw return values are unchanged. */
     keyBuilder?: (event: SyncChangeEvent, targetName: string) => string | null | undefined;
 }
 
@@ -71,6 +72,7 @@ export interface ResumeTokenRedisLike {
     del?(key: string): Promise<unknown> | unknown;
 }
 
+/** Stores opaque raw event tokens or a versioned initial EJSON operation-time checkpoint. */
 export interface ResumeTokenConfig {
     storage?: 'file' | 'redis';
     path?: string;