monsqlize 3.3.1 → 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;
@@ -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. */

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;
@@ -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. */

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

@@ -408,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>;
@@ -470,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

@@ -408,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>;
@@ -470,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

@@ -214,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'];
@@ -261,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

@@ -214,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'];
@@ -261,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;

package/dist/types/transaction.d.mts

@@ -24,9 +24,9 @@ export interface TransactionOptions {
     };
     readPreference?: 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest';
     causalConsistency?: boolean;
-    /** Maximum transaction duration in milliseconds before an automatic abort. */
+    /** Maximum transaction work duration in milliseconds before commit begins. */
     maxDuration?: number;
-    /** @alias maxDuration — v1 compat field */
+    /** Deadline for transaction work before commit begins. Alias: `maxDuration`. */
     timeout?: number;
     enableRetry?: boolean;
     maxRetries?: number;
@@ -90,16 +90,18 @@ export declare class Transaction {
         cache?: CacheLike | null;
         logger?: LoggerLike | null;
         lockManager?: CacheLockManager | null;
+        /** Work deadline in milliseconds; the timer stops before commit is dispatched. */
         timeout?: number;
+        /** MongoDB transaction options, including driver commit limits such as `maxCommitTimeMS`. */
         transactionOptions?: Record<string, unknown>;
     });
     /** Begin the transaction (starts the MongoDB session transaction). */
     start(): Promise<void>;
-    /** Commit the transaction; replays recorded cache invalidations on success. */
+    /** Commit the transaction; flushes cache invalidations on success or an unknown commit result. */
     commit(): Promise<void>;
     /** Abort the transaction and discard pending cache invalidations. */
     abort(): Promise<void>;
-    /** Alias for `commit()` — v1 compat shorthand. */
+    /** End the session after pending lifecycle work; aborts an active transaction with a known outcome. */
     end(): Promise<void>;
     /** Record a cache-invalidation pattern to be replayed on commit. */
     recordInvalidation(pattern: string): Promise<void>;

package/dist/types/transaction.d.ts

@@ -24,9 +24,9 @@ export interface TransactionOptions {
     };
     readPreference?: 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest';
     causalConsistency?: boolean;
-    /** Maximum transaction duration in milliseconds before an automatic abort. */
+    /** Maximum transaction work duration in milliseconds before commit begins. */
     maxDuration?: number;
-    /** @alias maxDuration — v1 compat field */
+    /** Deadline for transaction work before commit begins. Alias: `maxDuration`. */
     timeout?: number;
     enableRetry?: boolean;
     maxRetries?: number;
@@ -90,16 +90,18 @@ export declare class Transaction {
         cache?: CacheLike | null;
         logger?: LoggerLike | null;
         lockManager?: CacheLockManager | null;
+        /** Work deadline in milliseconds; the timer stops before commit is dispatched. */
         timeout?: number;
+        /** MongoDB transaction options, including driver commit limits such as `maxCommitTimeMS`. */
         transactionOptions?: Record<string, unknown>;
     });
     /** Begin the transaction (starts the MongoDB session transaction). */
     start(): Promise<void>;
-    /** Commit the transaction; replays recorded cache invalidations on success. */
+    /** Commit the transaction; flushes cache invalidations on success or an unknown commit result. */
     commit(): Promise<void>;
     /** Abort the transaction and discard pending cache invalidations. */
     abort(): Promise<void>;
-    /** Alias for `commit()` — v1 compat shorthand. */
+    /** End the session after pending lifecycle work; aborts an active transaction with a known outcome. */
     end(): Promise<void>;
     /** Record a cache-invalidation pattern to be replayed on commit. */
     recordInvalidation(pattern: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "monsqlize",
-    "version": "3.3.1",
+    "version": "3.3.2",
     "description": "TypeScript production data runtime layer for MongoDB today, with cache, transactions, pools, models, sync, and observability",
     "type": "commonjs",
     "main": "./dist/cjs/index.cjs",
@@ -21,6 +21,7 @@
         "./package.json": "./package.json"
     },
     "files": [
+        "changelogs/v3.3.2.md",
         "changelogs/v3.3.1.md",
         "changelogs/v3.3.0.md",
         "changelogs/v3.2.0.md",
@@ -112,8 +113,8 @@
         "check:sizes:strict": "node scripts/check-file-sizes.cjs --strict",
         "build": "node scripts/build-p1.cjs",
         "build:tests": "node scripts/compile-tests.cjs",
-        "lint": "eslint . --ignore-pattern .generated/** --ignore-pattern dist/** --ignore-pattern .devcodex/**",
-        "lint:fix": "eslint . --fix --ignore-pattern .generated/** --ignore-pattern dist/** --ignore-pattern .devcodex/**",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
         "test:runtime": "npm run build && npm run build:tests && node --test .generated/test-dist/test/smoke/root-cjs.test.js .generated/test-dist/test/smoke/root-esm.test.js .generated/test-dist/test/smoke/pack-artifacts.test.js",
         "test:compatibility": "npm run build && npm run build:tests && node --test .generated/test-dist/test/compatibility/exports/exports.test.js .generated/test-dist/test/compatibility/matrix.test.js",
         "probe:server-matrix": "node scripts/validation/probe-memory-server-matrix.cjs",
@@ -122,7 +123,7 @@
         "test:examples": "npm run build && tsc -p tsconfig.examples.json && node scripts/run-examples.cjs",
         "test:performance": "npm run build && npm run build:tests && node .generated/test-dist/test/performance/baselines/function-cache.benchmark.js",
         "test:unit": "npm run build && npm run build:tests && node test/run-tests.cjs unit",
-        "test:integration": "npm run build && npm run build:tests && node --test --test-concurrency=1 .generated/test-dist/test/integration/cache/cache.test.js .generated/test-dist/test/integration/cache/cache-behavior.test.js .generated/test-dist/test/integration/mongodb/connect.test.js .generated/test-dist/test/integration/mongodb/queries.test.js .generated/test-dist/test/integration/mongodb/management.test.js .generated/test-dist/test/integration/mongodb/writes-batch.test.js .generated/test-dist/test/integration/mongodb/find.test.js .generated/test-dist/test/integration/mongodb/find-one.test.js .generated/test-dist/test/integration/mongodb/find-page.test.js .generated/test-dist/test/integration/mongodb/aggregate.test.js .generated/test-dist/test/integration/mongodb/chaining.test.js .generated/test-dist/test/integration/mongodb/insert.test.js .generated/test-dist/test/integration/mongodb/update.test.js .generated/test-dist/test/integration/mongodb/delete.test.js .generated/test-dist/test/integration/mongodb/update-pipeline.test.js .generated/test-dist/test/integration/model/model-features.test.js .generated/test-dist/test/integration/transaction/transaction.test.js .generated/test-dist/test/integration/pool/pool.test.js .generated/test-dist/test/integration/pool/pool-behavior.test.js .generated/test-dist/test/integration/watch/watch-native.test.js .generated/test-dist/test/integration/runtime/runtime-core-regression.test.js .generated/test-dist/test/integration/sync/sync.test.js .generated/test-dist/test/integration/slow-query-log/slow-query-log.test.js .generated/test-dist/test/integration/model/model-crud-extended.test.js .generated/test-dist/test/integration/mongodb/management-complete.test.js .generated/test-dist/test/integration/runtime/runtime-methods-extended.test.js .generated/test-dist/test/integration/mongodb/find-page-advanced.test.js",
+        "test:integration": "npm run build && npm run build:tests && node --test --test-concurrency=1 .generated/test-dist/test/integration/cache/cache.test.js .generated/test-dist/test/integration/cache/cache-behavior.test.js .generated/test-dist/test/integration/mongodb/connect.test.js .generated/test-dist/test/integration/mongodb/queries.test.js .generated/test-dist/test/integration/mongodb/management.test.js .generated/test-dist/test/integration/mongodb/writes-batch.test.js .generated/test-dist/test/integration/mongodb/find.test.js .generated/test-dist/test/integration/mongodb/find-one.test.js .generated/test-dist/test/integration/mongodb/find-page.test.js .generated/test-dist/test/integration/mongodb/aggregate.test.js .generated/test-dist/test/integration/mongodb/chaining.test.js .generated/test-dist/test/integration/mongodb/insert.test.js .generated/test-dist/test/integration/mongodb/update.test.js .generated/test-dist/test/integration/mongodb/delete.test.js .generated/test-dist/test/integration/mongodb/update-pipeline.test.js .generated/test-dist/test/integration/model/model-features.test.js .generated/test-dist/test/integration/transaction/transaction.test.js .generated/test-dist/test/integration/pool/pool.test.js .generated/test-dist/test/integration/pool/pool-behavior.test.js .generated/test-dist/test/integration/watch/watch-native.test.js .generated/test-dist/test/integration/runtime/runtime-core-regression.test.js .generated/test-dist/test/integration/runtime/review-regressions.test.js .generated/test-dist/test/integration/sync/sync.test.js .generated/test-dist/test/integration/slow-query-log/slow-query-log.test.js .generated/test-dist/test/integration/model/model-crud-extended.test.js .generated/test-dist/test/integration/mongodb/management-complete.test.js .generated/test-dist/test/integration/runtime/runtime-methods-extended.test.js .generated/test-dist/test/integration/mongodb/find-page-advanced.test.js .generated/test-dist/test/integration/mongodb/review-repair-regressions.test.js .generated/test-dist/test/integration/model/review-model-regressions.test.js .generated/test-dist/test/integration/slow-query-log/review-storage-regressions.test.js",
         "test:data-tasks:integration": "npm run build && npm run build:tests && node test/run-tests.cjs data-tasks-integration",
         "test:data-task-cli": "npm run build && npm run build:tests && node test/run-tests.cjs data-task-cli",
         "test:pack-install": "npm run build && node scripts/pack-install-smoke.cjs",