monsqlize 1.3.1 → 2.0.0

package/dist/types/sync.d.ts

@@ -0,0 +1,103 @@
+import type { ChangeStreamDocument, Document, MongoClientOptions } from 'mongodb';
+
+import type { LoggerLike } from './base';
+
+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.ts

@@ -0,0 +1,132 @@
+import type { CacheLike } from './runtime';
+import type { LoggerLike } from './base';
+
+/** 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;
+    activeTransactions: number;
+    averageDuration: 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;
+    });
+    /** 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;
+    });
+    /** 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,24 +1,26 @@
 {
   "name": "monsqlize",
-  "version": "1.3.1",
-  "description": "A lightweight MongoDB ORM with multi-level caching, transaction support, and distributed features",
-  "main": "lib/index.js",
-  "module": "index.mjs",
+  "version": "2.0.0",
+  "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",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
-      "require": "./lib/index.js",
-      "import": "./index.mjs",
-      "types": "./index.d.ts"
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "import": "./dist/esm/index.mjs"
     },
     "./package.json": "./package.json"
-  },
-  "types": "./index.d.ts",
-  "files": [
-    "lib/",
-    "index.d.ts",
-    "README.md",
-    "LICENSE",
+  },
+  "files": [
+    "dist/**/*.cjs",
+    "dist/**/*.mjs",
+    "dist/**/*.d.ts",
+    "changelogs/v2.0.0.md",
+    "README.md",
+    "LICENSE",
     "CHANGELOG.md"
   ],
   "keywords": [
@@ -36,82 +38,82 @@
     "api"
   ],
   "author": "vext.js Team",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vextjs/monSQLize.git"
+    "url": "git+https://github.com/vextjs/monSQLize.git"
   },
   "bugs": {
     "url": "https://github.com/vextjs/monSQLize/issues"
   },
-  "homepage": "https://github.com/vextjs/monSQLize#readme",
+  "homepage": "https://vextjs.github.io/monSQLize/",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node test/run-tests.js",
-    "test:unit": "node test/run-tests.js",
-    "test:performance": "node test/performance/transaction-benchmark.js",
-    "test:coverage": "nyc --reporter=text --reporter=lcov node test/run-tests.js",
-    "coverage": "nyc --reporter=text --reporter=lcov --reporter=html node test/run-tests.js",
-    "benchmark": "node test/benchmark/run-benchmarks.js",
-    "test:compatibility": "node test/compatibility/run-node-test.js",
-    "test:compatibility:node": "node scripts/test-node-versions.js",
-    "test:compatibility:driver": "node scripts/test-driver-versions-simple.js",
-    "test:compatibility:driver:full": "node scripts/test-driver-versions-simple.js --drivers=4.17.2,5.9.2,6.17.0,7.0.0",
-    "test:compatibility:driver:quick": "node test/compatibility/run-driver-test.js",
-    "test:compatibility:server": "node scripts/test-server-versions.js --use-memory-server",
-    "test:compatibility:server:quick": "node test/compatibility/run-server-test.js",
-    "test:compatibility:server:docker": "node scripts/test-server-versions.js",
-    "lint": "eslint lib/ test/ --ext .js",
-    "lint:fix": "eslint lib/ test/ --ext .js --fix",
-    "type-check": "tsc",
-    "postpublish": "echo '✅ 发布成功！请创建 GitHub Release: https://github.com/vextjs/monSQLize/releases/new?tag=v'$npm_package_version"
-  },
+    "check:sizes": "node scripts/check-file-sizes.cjs",
+    "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/**",
+    "lint:fix": "eslint . --fix --ignore-pattern .generated/** --ignore-pattern dist/**",
+    "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",
+    "test:server-matrix": "node scripts/validation/run-memory-server-matrix.cjs",
+    "test:real-env:private": "node scripts/validation/run-private-real-env-checks.cjs",
+    "test:examples": "npm run build && tsc -p tsconfig.examples.json && node .generated/examples-dist/examples/quick-start/basic-connect.js && node .generated/examples-dist/examples/cache/with-cache.js && node .generated/examples-dist/examples/docs/insert.js && node .generated/examples-dist/examples/docs/insert-many.js && node .generated/examples-dist/examples/docs/update.js && node .generated/examples-dist/examples/docs/update-one.js && node .generated/examples-dist/examples/docs/delete.js && node .generated/examples-dist/examples/docs/delete-many.js && node .generated/examples-dist/examples/docs/upsert.js && node .generated/examples-dist/examples/docs/upsert-one.js && node .generated/examples-dist/examples/docs/find.js && node .generated/examples-dist/examples/docs/find-one.js && node .generated/examples-dist/examples/docs/find-one-by-id.js && node .generated/examples-dist/examples/docs/find-by-ids.js && node .generated/examples-dist/examples/docs/find-page.js && node .generated/examples-dist/examples/docs/find-and-count.js && node .generated/examples-dist/examples/docs/count.js && node .generated/examples-dist/examples/docs/distinct.js && node .generated/examples-dist/examples/docs/explain.js && node .generated/examples-dist/examples/docs/aggregate.js && node .generated/examples-dist/examples/docs/chaining-api.js && node .generated/examples-dist/examples/docs/expression-functions.js && node .generated/examples-dist/examples/docs/model.js && node .generated/examples-dist/examples/docs/collection-management.js && node .generated/examples-dist/examples/docs/bookmarks.js && node .generated/examples-dist/examples/docs/transaction.js && node .generated/examples-dist/examples/docs/transaction-rollback.js && node .generated/examples-dist/examples/docs/slow-query-log.js && node .generated/examples-dist/examples/docs/watch.js && node .generated/examples-dist/examples/docs/aggregate-advanced.js && node .generated/examples-dist/examples/docs/batch-operations.js && node .generated/examples-dist/examples/docs/soft-delete.js && node .generated/examples-dist/examples/docs/increment-one.js && node .generated/examples-dist/examples/docs/populate-relations.js && node .generated/examples-dist/examples/docs/saga.js && node .generated/examples-dist/examples/docs/lock.js && node .generated/examples-dist/examples/docs/lock-timeout.js && node .generated/examples-dist/examples/docs/cache-multilevel.js && node .generated/examples-dist/examples/docs/objectid.js && node .generated/examples-dist/examples/docs/pool.js && node .generated/examples-dist/examples/docs/pool-fallback.js && node .generated/examples-dist/examples/docs/sync.js && node .generated/examples-dist/examples/docs/sync-target-failure.js",
+    "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 .generated/test-dist/test/unit/expression/expression.test.js .generated/test-dist/test/unit/expression/operators.test.js .generated/test-dist/test/unit/errors/errors.test.js .generated/test-dist/test/unit/management/management.test.js .generated/test-dist/test/unit/writes/batch.test.js .generated/test-dist/test/unit/cache/cache.test.js .generated/test-dist/test/unit/cache/cache-refactor-guard.test.js .generated/test-dist/test/unit/coverage/core-helpers.test.js .generated/test-dist/test/unit/function-cache/function-cache.test.js .generated/test-dist/test/unit/model/model-registry.test.js .generated/test-dist/test/unit/lock/lock.test.js .generated/test-dist/test/unit/transaction/transaction.test.js .generated/test-dist/test/unit/pool/pool.test.js .generated/test-dist/test/unit/runtime/runtime-compat.test.js .generated/test-dist/test/unit/sync/sync.test.js .generated/test-dist/test/unit/slow-query-log/slow-query-log.test.js .generated/test-dist/test/unit/slow-query-log/slow-query-log-behavior.test.js .generated/test-dist/test/unit/saga/saga.test.js .generated/test-dist/test/unit/count-queue/count-queue.test.js .generated/test-dist/test/unit/model/model-softdelete-versioning.test.js .generated/test-dist/test/unit/function-cache/function-cache-behavior.test.js .generated/test-dist/test/unit/saga/saga-behavior.test.js .generated/test-dist/test/unit/lock/lock-distributed.test.js .generated/test-dist/test/unit/coverage/capability-wiring.test.js .generated/test-dist/test/unit/pool/pool-stats.test.js .generated/test-dist/test/unit/coverage/pure-functions.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/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:refactor-guard": "npm run build && npm run build:tests && node --test --test-concurrency=1 .generated/test-dist/test/compatibility/exports/exports.test.js .generated/test-dist/test/integration/model/model-features.test.js .generated/test-dist/test/integration/runtime/runtime-core-regression.test.js .generated/test-dist/test/integration/sync/sync.test.js",
+    "test:refactor-guard:cache": "npm run build && npm run build:tests && node --test .generated/test-dist/test/unit/cache/cache-refactor-guard.test.js",
+    "test:coverage": "npm run build && npm run build:tests && c8 --reporter=text --reporter=lcov --reporter=json-summary --check-coverage --lines 95 --statements 95 --functions 95 --branches 95 node test/run-tests.cjs",
+    "test": "npm run build && npm run build:tests && node test/run-tests.cjs",
+    "type-check": "npm run build && tsc -p tsconfig.json --noEmit && tsd --files test/types/root-import.test-d.ts --files test/types/cache-usage.test-d.ts --files test/types/model-usage.test-d.ts --files test/types/pool-usage.test-d.ts --files test/types/sync-usage.test-d.ts --files test/types/slow-query-log-usage.test-d.ts --files test/types/saga-usage.test-d.ts",
+    "check:test-language": "node scripts/check-test-language.cjs",
+    "verify:fast": "npm run lint && npm run type-check && npm run check:sizes:strict && npm run test:runtime && npm run test:compatibility && npm run test:refactor-guard && npm run test:refactor-guard:cache",
+    "verify:full": "npm run lint && npm run type-check && npm run check:sizes:strict && npm run test:coverage && npm run test:examples && npm run test:server-matrix",
+    "verify:release": "npm run verify:full && npm run test:real-env:private",
+    "verify": "npm run verify:full",
+    "release:preflight": "node scripts/release-preflight.cjs",
+    "prepublishOnly": "npm run release:preflight",
+    "release:publish": "npm run release:preflight && npm publish --ignore-scripts",
+    "postpublish": "echo '✅ 发布成功！请创建 GitHub Release: https://github.com/vextjs/monSQLize/releases/new?tag=v'$npm_package_version"
+  },
   "peerDependenciesMeta": {
     "ioredis": {
       "optional": true
+    },
+    "ssh2": {
+      "optional": true
     }
   },
   "optionalDependencies": {
-    "ioredis": "^5.8.2"
+    "ioredis": "^5.8.2",
+    "ssh2": "^1.17.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/node": "^25.0.1",
-    "benchmark": "^2.1.4",
-    "chai": "^6.2.1",
+    "@types/semver": "^7.7.1",
+    "c8": "^11.0.0",
+    "chai": "^6.2.2",
+    "esbuild": "^0.25.5",
     "eslint": "^9.39.1",
-    "mocha": "^11.7.5",
-    "mongodb-memory-server": "^10.1.2",
-    "nyc": "^15.1.0",
-    "sinon": "^21.0.0",
+    "mongodb-memory-server": "^11.1.0",
+    "sinon": "^22.0.0",
     "tsd": "^0.33.0",
     "typescript": "^5.9.3"
   },
-  "nyc": {
-    "include": [
-      "lib/**/*.js"
-    ],
-    "exclude": [
-      "test/**",
-      "examples/**",
-      "scripts/**",
-      "reports/**"
-    ],
-    "reporter": [
-      "text",
-      "lcov",
-      "html"
-    ],
-    "check-coverage": true,
-    "lines": 70,
-    "statements": 70,
-    "functions": 70,
-    "branches": 65
-  },
   "dependencies": {
-    "mongodb": "^6.17.0",
-    "ssh2": "^1.17.0"
+    "async-lock": "^1.4.1",
+    "cache-hub": "^1.0.0",
+    "mongodb": "^6.21.0",
+    "schema-dsl": "^2.0.3"
   }
 }