v2.0.0.md

v2.0.0 — 2026-06-01

Overview

v2.0.0 is a full TypeScript rewrite of monSQLize. The public API is preserved — existing v1 code requires only minor configuration adjustments to run on v2.

---

Architecture

Layer	Change
Source language	JavaScript → TypeScript (strict mode)
Cache engine	Internal implementation → cache-hub
Internal structure	Flat modules → capability layers + adapter bridge
Type declarations	Hand-maintained .d.ts → generated from source (single source of truth)

---

Compatibility Notes and Breaking Changes

B1 — SagaResult shape documents v1/v2 aliases

SagaResult now exposes the runtime fields and the restored v1/v2 alias fields:

{
  executionId: string;          // primary v1 field
  sagaId?: string;              // v2 alias, optional for v1 fixtures
  sagaName?: string;
  success: boolean;
  result?: unknown;
  error?: Error;
  errorMessage?: string;
  completedSteps: string[];
  completedStepCount?: number;
  completedStepNames?: string[];
  compensatedSteps: string[];
  duration: number;
  compensation?: { success: boolean; results: [...] };
}

B2 — TransactionInfo.status keeps the v1 'started' value

The internal transaction state still uses 'active', but Transaction#getInfo().status maps it back to 'started' for v1 callers. Public values are 'pending' | 'started' | 'committed' | 'aborted'.

B3 — getPoolStats() / getPoolHealth() return Record<string, T>

// v1 — array
getPoolStats(): PoolStats[]
getPoolHealth(): PoolHealthStatus[]

// v2 — keyed by pool name
getPoolStats(): Record<string, PoolStats>
getPoolHealth(): Record<string, PoolHealthStatus>

B4 — PoolStats shape extended

PoolStats now includes connections, available, waiting, and status fields that were absent in v1 type declarations (but present in the runtime).

B5 — getCache() returns CacheLike

// v1
getCache(): MemoryCache

// v2
getCache(): CacheLike  // MemoryCache | MultiLevelCache | custom adapter

This is a widening: MemoryCache is still the default; the return type is broader to accommodate the two new cache modes.

---

New Features

MultiLevel cache via cache option

const msq = new MonSQLize({
  type: 'mongodb',
  cache: {
    multiLevel: true,
    local: { maxEntries: 5000 },
    remote: MonSQLize.createRedisCacheAdapter('redis://localhost:6379'),
    policy: { writePolicy: 'local-first-async-remote', backfillLocalOnRemoteHit: true },
  },
});

SSH tunnel support

Connect to MongoDB through a bastion host with no code changes required:

const msq = new MonSQLize({
  type: 'mongodb',
  config: {
    uri: 'mongodb://mongo.internal:27017/mydb',
    ssh: {
      host: 'bastion.example.com',
      username: 'deploy',
      privateKeyPath: '~/.ssh/id_rsa',
    },
  },
});

Historical v2.0.0 note: SSH tunneling originally expected ssh2 to be present separately. In current v2.0.2+ packages, ssh2 is installed with monsqlize.

Custom CacheLike pass-through (v1 compat)

Passing a custom CacheLike instance (e.g. a Redis adapter) directly as cache is now supported:

const msq = new MonSQLize({
  type: 'mongodb',
  cache: MonSQLize.createRedisCacheAdapter('redis://localhost:6379'),
});

In v1 this silently fell back to a default MemoryCache. In v2 it is used directly.

HealthView.driver field

health() now returns driver: { connected: boolean } alongside the existing fields.

ModelInstance soft-delete and batch methods

findOneOnlyDeleted, countWithDeleted, countOnlyDeleted, insertBatch, updateBatch are now declared in the public type surface (they existed at runtime in v1 but were not typed).

---

v1 Compatibility Map

v1 option	v2 equivalent	Status
cache.maxSize	cache.maxEntries	✅ auto-mapped
cache.ttl	cache.defaultTtl	✅ auto-mapped
cache.autoInvalidate	cacheAutoInvalidate (top-level)	✅ both accepted
cache: CacheLike	cache: CacheLike	✅ pass-through
cache: MultiLevelCacheOptions	cache: { multiLevel: true, ... }	✅ fully supported
options.database	options.databaseName	✅ alias preserved
SagaResult.sagaId	SagaResult.sagaId + executionId alias	✅
ctx.sagaId in Saga steps	ctx.executionId + ctx.sagaId alias	✅ alias preserved

---

JSDoc Coverage

All public API surface now carries complete English JSDoc:

• types/collection.d.ts — 49 Collection / DbAccessor / AdminAccessor methods
• types/model.d.ts — 44 ModelInstance methods
• types/monsqlize.d.ts — 43 MonSQLize interface methods
• types/lock.d.ts — Lock / LockManager
• types/saga.d.ts — SagaOrchestrator / SagaContext / SagaStep
• types/transaction.d.ts — Transaction / TransactionManager / CacheLockManager
• types/runtime.d.ts — MemoryCache / MultiLevelCache / FunctionCache

---

v1 Compatibility Fixes (included in this release)

API / Runtime

• findAndCount: return value includes documents as a backward-compat alias for data ({ data, total, documents })
• findOneById / findByIds: options.cache now restores v1-style read-through TTL caching.
• Runtime query defaults: built-in defaults now match v1 (maxTimeMS=2000, findLimit=10, slowQueryMs=500, findPageMaxLimit=500).
• LockManager TTL: explicit lock TTL values are no longer silently capped by maxDuration.
• withCache(fn): default behavior now matches v1 (ttl=60000, namespace='fn', enableStats=true).
• adaptLegacyCacheLike: exported as both a named import and MonSQLize.adaptLegacyCacheLike
• MultiLevelCache: exported as both a named import and MonSQLize.MultiLevelCache
• Error messages: createValidationError default message 参数校验失败; createCursorError default 游标无效
• FunctionCache.defaultTTL: v1 option defaultTTL now accepted as an alias for ttl; v1 code using new FunctionCache(db, { defaultTTL: 60000 }) works without changes
• Read query meta wrapper: find / findOne / count / aggregate / distinct now restore the v1 { data, meta } result shape when options.meta is enabled.
• FunctionCache defaults and stats: new FunctionCache() is supported, the default namespace is restored to action, and stats include totalTime / avgTime.
• Batch writes: insertBatch / deleteBatch retry defaults are restored to 3 attempts and 1000ms; updateBatch now supports onError='retry', retryAttempts, retryDelay, and onRetry.
• Model hooks: flat hooks support beforeInsert / afterInsert aliases and now cover bulk/upsert/findOneAnd* write paths.

Type Declarations

• FindAndCountResult: includes documents?: TSchema[] optional backward-compat alias
• SagaResult: includes completedStepNames?: string[] (ordered step names, v1 compat) and errorCause?: unknown
• CachedFunction: exposes getCacheStats() as a v1 shim over stats()
• Query meta overloads: public collection types now expose ResultWithMeta<T> overloads for meta-enabled read APIs.
• Collection management methods: public collection types now declare stats, renameCollection, collMod, convertToCapped, validator setters, and getValidator.
• ModelInstance helpers: public model types now declare getRelations() and getEnums().
• Model hooks: beforeInsert / afterInsert are declared as flat hook aliases.
• Batch options: public batch option types now expose retry and progress options consistently.
• Workspace smooth-upgrade bridge: legacy-wide Model / Collection public contracts accept v1 consumer fixture shapes without source changes, including object schema definitions, validate:true operation overrides, validate() response data, array-form populate(), document-level populate(), Transaction stats, Saga metadata/return contracts, FunctionCache registration, Mongo connection aliases, package metadata exports, sync transform overloads, top-level FindPageOptions.comment, and optional v2-only counter aliases.
• Root and static export parity: ESM named exports and default MonSQLize statics are aligned with the CJS surface, including advanced capabilities and package metadata.
• Remaining v1 operation contracts: MonSQLize#scopedCollection() pool scoping, ConnectionPoolManager#selectPool() string operations, chainable ModelDocument#populate(), synchronous listSagas(), and required SagaResult.compensatedSteps are restored for v1-compatible consumers.
• Collection find() overload: the v1 three-argument find(query, projection, options) form is restored at runtime and in public types.
• Redis adapter errors: legacy invalid-argument and missing-ioredis messages are preserved while keeping structured monSQLize error codes.

Workspace Upgrade Validation

• Verified zero-business-code upgrade paths for workspace consumers chat, payment, user, admin, search, vext, and permission-core by overlaying only the local monSQLize package candidate and running each service's TypeScript/test gate.
• Additional workspace declarations were classified in requirements/平滑升级支持/06-工作区依赖覆盖矩阵.md; historical/spec assets and credential-bearing scripts are static-only exclusions from the default release gate until they are sanitized.

Internal

• src/entry/runtime-core.ts reduced from 852 to 769 lines; cache normalizer extracted to runtime-cache-normalizer.ts
• node --test --test-concurrency=1 applied to all integration test scripts to prevent parallel mongod startup hangs on Windows
• withCache() performance validation ledgers now align with the current benchmark source and document that v1 transaction benchmarks are not directly comparable to the v2 function-cache hot-path baseline.
• The transaction/cache-lock unit test was stabilized, and release preflight now runs the default npm test gate before pack dry-run.
• Runtime dependency schema-dsl now follows npm latest TypeScript line ^2.0.3; deprecated mistake releases in the 2.3.x range are explicitly excluded from the upgrade target.
• Project licensing is now Apache-2.0, and the package README is published in English for npm and GitHub users.
• npm package artifacts are limited to runtime CJS / ESM bundles, public .d.ts declarations, and release documentation. Source maps are disabled by default and excluded from the package boundary even when generated locally.
• GitHub Actions publish flow now runs release:preflight once before npm publish --ignore-scripts, avoiding duplicate prepublishOnly lifecycle execution inside the final publish step while preserving raw npm publish safeguards.

---

Migration Notes

Most v1 applications will run without modification. The steps below apply only if you hit one of the breaking changes.

1. getPoolStats() / getPoolHealth() — if you iterate the result as an array, switch to Object.values(msq.getPoolStats()).
2. Saga context — replace ctx.sagaId with ctx.executionId inside step handlers.
3. getCache() narrowing — if you assigned the result to a MemoryCache typed variable, widen the type to CacheLike.
4. cache.maxSize — still works transparently; rename to maxEntries at your convenience.
5. slow-query-log queryHash — v2 now normalizes the hash from stable identity fields (database|db、collection|coll、operation|op、queryShape|query) and stores a 16-character digest. Historical slow-query-log records remain readable, but new and old aggregation keys are not guaranteed to stay continuous. This release does not include an automatic migration script; if your downstream analytics depend on historical key continuity, migrate those records explicitly before or during rollout.