monsqlize 2.0.5 → 2.0.6

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

@@ -0,0 +1,126 @@
+import type { LoggerLike } from './base.mjs';
+
+export interface SlowQueryLogEntry {
+    database: string;
+    collection: string;
+    operation: string;
+    durationMs: number;
+    query?: unknown;
+    timestamp?: Date;
+    queryHash?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface SlowQueryLogRecord {
+    queryHash: string;
+    database: string;
+    collection: string;
+    operation: string;
+    count: number;
+    totalTimeMs: number;
+    avgTimeMs: number;
+    maxTimeMs: number;
+    minTimeMs: number;
+    firstSeen: Date;
+    lastSeen: Date;
+    sampleQuery?: unknown;
+    metadata?: Record<string, unknown>;
+}
+
+export interface SlowQueryLogFilter {
+    database?: string;
+    collection?: string;
+    operation?: string;
+    queryHash?: string;
+}
+
+export interface SlowQueryLogQueryOptions {
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+}
+
+export interface SlowQueryLogStorageConfig {
+    type?: 'memory' | 'mongodb';
+    useBusinessConnection?: boolean;
+    uri?: string | null;
+    database?: string;
+    collection?: string;
+    ttl?: number;
+    options?: Record<string, unknown>;
+}
+
+export interface SlowQueryLogConfig {
+    enabled: boolean;
+    storage: SlowQueryLogStorageConfig;
+    batch: {
+        enabled: boolean;
+        size: number;
+        interval: number;
+        maxBufferSize: number;
+    };
+    filter: {
+        excludeDatabases: string[];
+        excludeCollections: string[];
+        excludeOperations: string[];
+        minExecutionTimeMs: number;
+    };
+    advanced: {
+        errorHandling: 'log' | 'throw' | 'silent';
+        autoCreateIndexes: boolean;
+    };
+}
+
+export type SlowQueryLogConfigInput = boolean | Partial<SlowQueryLogConfig>;
+
+export interface SlowQueryLogStorage {
+    initialize(): Promise<void>;
+    save(log: SlowQueryLogEntry): Promise<void>;
+    saveBatch(logs: SlowQueryLogEntry[]): Promise<void>;
+    query(filter?: SlowQueryLogFilter, options?: SlowQueryLogQueryOptions): Promise<SlowQueryLogRecord[]>;
+    close(): Promise<void>;
+}
+
+export declare const DEFAULT_SLOW_QUERY_LOG_CONFIG: SlowQueryLogConfig;
+export declare function generateQueryHash(input: unknown): string;
+
+export declare class BatchQueue {
+    constructor(storage: Pick<SlowQueryLogStorage, 'saveBatch'>, options?: Partial<SlowQueryLogConfig['batch']>, logger?: LoggerLike | null);
+    add(log: SlowQueryLogEntry): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+
+export declare class SlowQueryLogMemoryStorage implements SlowQueryLogStorage {
+    initialize(): Promise<void>;
+    save(log: SlowQueryLogEntry): Promise<void>;
+    saveBatch(logs: SlowQueryLogEntry[]): Promise<void>;
+    query(filter?: SlowQueryLogFilter, options?: SlowQueryLogQueryOptions): Promise<SlowQueryLogRecord[]>;
+    close(): Promise<void>;
+}
+
+export declare class MongoDBSlowQueryLogStorage implements SlowQueryLogStorage {
+    constructor(config?: SlowQueryLogStorageConfig, businessClient?: unknown, logger?: LoggerLike | null);
+    initialize(): Promise<void>;
+    save(log: SlowQueryLogEntry): Promise<void>;
+    saveBatch(logs: SlowQueryLogEntry[]): Promise<void>;
+    query(filter?: SlowQueryLogFilter, options?: SlowQueryLogQueryOptions): Promise<SlowQueryLogRecord[]>;
+    close(): Promise<void>;
+}
+
+export declare class SlowQueryLogConfigManager {
+    static mergeConfig(userConfig?: SlowQueryLogConfigInput, businessType?: string): SlowQueryLogConfig;
+    static validate(config: SlowQueryLogConfig, businessType?: string): boolean;
+}
+
+export declare class SlowQueryLogManager {
+    readonly config: SlowQueryLogConfig;
+    readonly storage: SlowQueryLogStorage;
+    readonly queue: BatchQueue | null;
+    constructor(userConfig?: SlowQueryLogConfigInput, businessClient?: unknown, businessType?: string, logger?: LoggerLike | null);
+    initialize(): Promise<void>;
+    save(log: SlowQueryLogEntry): Promise<void>;
+    query(filter?: SlowQueryLogFilter, options?: SlowQueryLogQueryOptions): Promise<SlowQueryLogRecord[]>;
+    close(): Promise<void>;
+}
+

package/dist/types/sync.d.mts

@@ -0,0 +1,103 @@
+import type { ChangeStreamDocument, Document, MongoClientOptions } from 'mongodb';
+
+import type { LoggerLike } from './base.mjs';
+
+export type SyncChangeEvent<TDocument extends Document = Document> = ChangeStreamDocument<TDocument> & {
+    _id?: unknown;
+    operationType: 'insert' | 'update' | 'replace' | 'delete';
+    ns: {
+        db: string;
+        coll: string;
+    };
+    documentKey?: Record<string, unknown>;
+    fullDocument?: TDocument;
+};
+
+export interface SyncTargetHealthCheckConfig {
+    /** Whether to enable health checks; defaults to true. */
+    enabled?: boolean;
+    /** Health check interval in milliseconds; defaults to 30000. */
+    interval?: number;
+    /** Timeout for a single health check in milliseconds; defaults to 5000. */
+    timeout?: number;
+    /** Number of retries after failure; defaults to 3. */
+    retries?: number;
+}
+
+export interface SyncTargetConfig {
+    name: string;
+    uri?: string;
+    pool?: string;
+    databaseName?: string;
+    collections?: string[];
+    options?: MongoClientOptions;
+    apply?: (event: SyncChangeEvent, document: Record<string, unknown> | undefined) => Promise<void>;
+    /** Target node health check configuration. @since v1.0.8 */
+    healthCheck?: SyncTargetHealthCheckConfig;
+}
+
+export interface ResumeTokenRedisLike {
+    get(key: string): Promise<string | null> | string | null;
+    set(key: string, value: string): Promise<unknown> | unknown;
+    del?(key: string): Promise<unknown> | unknown;
+}
+
+export interface ResumeTokenConfig {
+    storage?: 'file' | 'redis';
+    path?: string;
+    redis?: ResumeTokenRedisLike;
+    key?: string;
+}
+
+export interface SyncConfig {
+    enabled: boolean;
+    targets: SyncTargetConfig[];
+    collections?: string[];
+    resumeToken?: ResumeTokenConfig;
+    filter?: (event: SyncChangeEvent) => boolean;
+    /**
+     * Transform a change-stream document before forwarding to sync targets.
+     * v1 form took a single argument (`doc => ...`); v2 added a second `event` argument.
+     * Signature is permissive (`any`) to accept both forms — v1 was never typed.
+     */
+    transform?: (document: any, event?: SyncChangeEvent) => any;
+}
+
+export interface SyncStats {
+    isRunning: boolean;
+    eventCount: number;
+    syncedCount: number;
+    errorCount: number;
+    startTime: Date | null;
+    lastEventTime: Date | null;
+    targets: Array<{
+        name: string;
+        syncCount: number;
+        errorCount: number;
+        lastSyncTime: Date | null;
+        lastError: Error | null;
+        successRate: string;
+    }>;
+}
+
+export declare function validateSyncConfig(config: SyncConfig): void;
+
+export declare class ResumeTokenStore {
+    constructor(options?: ResumeTokenConfig & { logger?: LoggerLike | null; });
+    load(): Promise<unknown | null>;
+    save(token: unknown): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export declare class ChangeStreamSyncManager {
+    constructor(options: {
+        db: unknown;
+        poolManager?: unknown;
+        config: SyncConfig;
+        logger?: LoggerLike | null;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStats(): SyncStats;
+}
+

package/dist/types/transaction.d.mts

@@ -0,0 +1,144 @@
+import type { CacheLike } from './runtime.mjs';
+import type { LoggerLike } from './base.mjs';
+
+/** Minimal MongoDB session contract used by the transaction layer. */
+export interface MongoSession {
+    id: unknown;
+    inTransaction(): boolean;
+    startTransaction(options?: Record<string, unknown>): void;
+    commitTransaction(): Promise<void>;
+    abortTransaction(): Promise<void>;
+    endSession(): Promise<void>;
+    /** v1 compat — v1 callers read `session.transaction?.state`; populated by the underlying driver. */
+    transaction?: { state?: string;[key: string]: unknown };
+}
+
+/** Options forwarded to the MongoDB driver when starting a transaction session. */
+export interface TransactionOptions {
+    readConcern?: {
+        level: 'local' | 'majority' | 'snapshot' | 'linearizable' | 'available';
+    };
+    readPreference?: 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest';
+    causalConsistency?: boolean;
+    /** Maximum transaction duration in milliseconds before an automatic abort. */
+    maxDuration?: number;
+    /** @alias maxDuration — v1 compat field */
+    timeout?: number;
+    enableRetry?: boolean;
+    maxRetries?: number;
+    retryDelay?: number;
+    retryBackoff?: number;
+    enableCacheLock?: boolean;
+    lockCleanupInterval?: number;
+    writeConcern?: Record<string, unknown>;
+}
+
+/** Snapshot of a transaction's current state. */
+export interface TransactionInfo {
+    id: string;
+    status: 'pending' | 'started' | 'committed' | 'aborted';
+    duration: number;
+    sessionId: string;
+}
+
+/** Aggregate statistics for all transactions managed by a `TransactionManager`. */
+export interface TransactionStats {
+    totalTransactions: number;
+    successfulTransactions: number;
+    failedTransactions: number;
+    readOnlyTransactions: number;
+    writeTransactions: number;
+    activeTransactions: number;
+    averageDuration: number;
+    p95Duration: number;
+    p99Duration: number;
+    successRate: string;
+    readOnlyRatio: string;
+    sampleCount: number;
+}
+
+/**
+ * In-memory lock tracker used to serialise cache invalidation across transaction boundaries.
+ * Attached to `TransactionManager`; locks are auto-released when a transaction commits or aborts.
+ */
+export declare class CacheLockManager {
+    constructor(options?: { logger?: LoggerLike | null; maxDuration?: number; cleanupInterval?: number; });
+    /** Register a lock for `key` owned by `owner`. */
+    addLock(key: string, owner: { id?: unknown; } | string): void;
+    /** Return `true` if `key` is currently locked. */
+    isLocked(key: string): boolean;
+    /** Release all locks held by `owner`. */
+    releaseLocks(owner: { id?: unknown; } | string): void;
+    /** Return lock usage statistics. */
+    getStats(): { totalLocks: number; activeLocks: number; maxDuration: number; };
+    /** Release all locks immediately. */
+    clear(): void;
+    /** Stop the background cleanup timer. */
+    stop(): void;
+}
+
+/** Represents a single MongoDB transaction session with optional cache-lock integration. */
+export declare class Transaction {
+    readonly id: string;
+    readonly session: MongoSession;
+    readonly state: 'pending' | 'active' | 'committed' | 'aborted';
+    constructor(session: MongoSession, options?: {
+        cache?: CacheLike | null;
+        logger?: LoggerLike | null;
+        lockManager?: CacheLockManager | null;
+        timeout?: number;
+        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(): Promise<void>;
+    /** Abort the transaction and discard pending cache invalidations. */
+    abort(): Promise<void>;
+    /** Alias for `commit()` — v1 compat shorthand. */
+    end(): Promise<void>;
+    /** Record a cache-invalidation pattern to be replayed on commit. */
+    recordInvalidation(pattern: string): Promise<void>;
+    /** Return the elapsed duration in milliseconds since the transaction started. */
+    getDuration(): number;
+    /** Return a snapshot of the transaction's current state and metadata. */
+    getInfo(): TransactionInfo;
+    /** Return v1-compatible per-transaction statistics. */
+    getStats(): {
+        id: string;
+        state: 'pending' | 'active' | 'committed' | 'aborted';
+        duration: number;
+        hasWriteOperation: boolean;
+        operationCount: number;
+        lockedKeysCount: number;
+    };
+}
+
+/** Manages the lifecycle of MongoDB transactions, including retry and session pooling. */
+export declare class TransactionManager {
+    constructor(options: {
+        client: unknown;
+        cache?: CacheLike | null;
+        logger?: LoggerLike | null;
+        lockManager?: CacheLockManager | null;
+        maxDuration?: number;
+        enableRetry?: boolean;
+        maxRetries?: number;
+        retryDelay?: number;
+        retryBackoff?: number;
+        defaultReadConcern?: TransactionOptions['readConcern'];
+        defaultWriteConcern?: TransactionOptions['writeConcern'];
+        defaultReadPreference?: TransactionOptions['readPreference'];
+        maxStatsSamples?: number;
+    });
+    /** Open a new transaction session. */
+    startSession(options?: TransactionOptions): Promise<Transaction>;
+    /** Execute `callback` inside a transaction; commits on success, aborts on failure. */
+    withTransaction<T>(callback: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /** Return all currently active (uncommitted) transactions. */
+    getActiveTransactions(): Transaction[];
+    /** Abort all active transactions immediately. */
+    abortAll(): Promise<void>;
+    /** Return aggregate transaction statistics. */
+    getStats(): TransactionStats;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monsqlize",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "TypeScript-native MongoDB ODM with multi-level caching (cache-hub), distributed locks, Saga orchestration, unified expression system (122 operators), connection pool management, ChangeStream sync, slow-query logging, and full v1 API compatibility",
   "type": "commonjs",
   "main": "./dist/cjs/index.cjs",
@@ -8,7 +8,10 @@
   "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
+      "types": {
+        "import": "./dist/types/index.d.mts",
+        "require": "./dist/types/index.d.ts"
+      },
       "require": "./dist/cjs/index.cjs",
       "import": "./dist/esm/index.mjs"
     },
@@ -18,6 +21,8 @@
     "dist/**/*.cjs",
     "dist/**/*.mjs",
     "dist/**/*.d.ts",
+    "dist/**/*.d.mts",
+    "changelogs/v2.0.6.md",
     "changelogs/v2.0.5.md",
     "changelogs/v2.0.4.md",
     "changelogs/v2.0.3.md",
@@ -117,7 +122,7 @@
     "cache-hub": "2.2.4",
     "ioredis": "5.8.2",
     "mongodb": "6.21.0",
-    "schema-dsl": "2.0.10",
+    "schema-dsl": "2.0.11",
     "ssh2": "1.17.0"
   }
 }