monsqlize 1.3.1 → 2.0.0

package/changelogs/README.md

@@ -0,0 +1,160 @@
+# Changelogs 目录说明
+
+本目录存放 monSQLize 各版本的详细变更文档。
+
+---
+
+## 📁 目录结构
+
+```
+changelogs/
+├── README.md           # 本说明文档
+├── TEMPLATE.md         # 变更文档模板
+├── v2.0.0.md          # v2.0.0 详细变更
+└── v1.x.y.md          # 历史版本详细变更（仓库归档）
+```
+
+---
+
+## 📝 文档格式
+
+每个版本的详细变更文档包含以下章节：
+
+### 必需章节
+
+1. **版本信息** - 版本号、日期、类型、风险级别、兼容性
+2. **变更摘要** - 一句话总结变更核心内容
+3. **背景说明** - 为什么需要这次变更
+4. **变更内容** - 改了什么
+5. **影响范围** - 影响哪些文件和功能
+6. **详细变更清单** - Added/Changed/Fixed 等分类列表
+7. **验证方法** - 如何验证变更
+
+### 可选章节
+
+- **迁移指南** - 如何升级/降级（如有破坏性变更）
+- **相关资源** - 文档/示例/测试链接
+- **设计决策** - 为什么这样设计
+- **未来改进** - 计划的后续改进
+
+---
+
+## 🔍 快速查找
+
+### 按版本类型
+
+- **正式发布**: v2.0.0, v1.0.0
+- **功能版本**: v1.x
+- **修复版本**: v1.x.y
+
+### 按功能领域
+
+- **TypeScript 重构与 v1 平滑升级**: v2.0.0
+- **实时监听 / 管理功能 / 核心功能**: v1.x 历史版本
+
+### 按风险级别
+
+- **P0 (Critical)**: v2.0.0
+- **P1 (High)**: v1.x 破坏性或高风险历史版本
+- **P2 (Low)**: v1.x 修复版本
+
+---
+
+## ✍️ 如何创建新的变更文档
+
+### 步骤1: 复制模板
+
+```bash
+cp TEMPLATE.md v{版本号}.md
+```
+
+### 步骤2: 填写内容
+
+根据模板章节填写变更信息：
+- 版本信息
+- 变更摘要
+- 背景说明
+- 变更内容
+- 影响范围
+- 详细变更清单
+- 验证方法
+
+### 步骤3: 更新主 CHANGELOG
+
+在项目根目录的 `CHANGELOG.md` 中：
+- 在"版本概览"表格最上方添加新行
+- 格式：版本列和详情列指向当前发布版本的 `changelogs/v{版本号}.md`
+
+### 步骤4: 提交变更
+
+```bash
+git add CHANGELOG.md changelogs/v{版本号}.md
+git commit -m "docs: 发布 v{版本号}"
+git tag v{版本号}
+git push origin main --tags
+```
+
+---
+
+## 📚 模板说明
+
+### TEMPLATE.md
+
+`TEMPLATE.md` 是创建新版本文档的标准模板，包含：
+
+- 完整的章节结构
+- 占位符和示例
+- 注释说明
+- Markdown 格式规范
+
+使用时请：
+1. 复制模板文件
+2. 重命名为对应版本号
+3. 替换所有占位符
+4. 删除不需要的可选章节
+5. 补充完整的变更信息
+
+---
+
+## 📊 版本命名规范
+
+遵循[语义化版本](https://semver.org/lang/zh-CN/)：
+
+### 格式: vMAJOR.MINOR.PATCH
+
+- **MAJOR** - 不兼容的 API 变更
+- **MINOR** - 向后兼容的新增功能
+- **PATCH** - 向后兼容的问题修复
+
+### 示例
+
+- `v1.0.0` - 正式发布
+- `v1.1.0` - 新增功能
+- `v1.1.1` - Bug 修复
+- `v2.0.0` - 破坏性变更
+
+---
+
+## 🔗 相关资源
+
+- **主 CHANGELOG**: [../CHANGELOG.md](../CHANGELOG.md)
+- **项目文档**: [GitHub docs](https://github.com/vextjs/monSQLize/tree/main/docs)
+- **使用示例**: [GitHub examples](https://github.com/vextjs/monSQLize/tree/main/examples)
+- **测试用例**: [GitHub test](https://github.com/vextjs/monSQLize/tree/main/test)
+- **语义化版本**: https://semver.org/lang/zh-CN/
+
+---
+
+## 📋 变更文档清单
+
+| 版本 | 文件 | 状态 | 发布日期 |
+|------|------|------|---------|
+| v2.0.0 | v2.0.0.md | ✅ 待发布候选 | 2026-06-01 |
+| v1.x | 仓库历史归档 | ✅ 已发布 | 2025-12-03 起 |
+
+---
+
+**目录版本**: 2.0
+**最后更新**: 2026-06-01
+**维护者**: monSQLize Team
+

package/changelogs/v2.0.0.md

@@ -0,0 +1,222 @@
+# 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`](https://github.com/vextjs/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:
+
+```ts
+{
+  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>`
+
+```ts
+// 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`
+
+```ts
+// 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
+
+```ts
+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:
+
+```ts
+const msq = new MonSQLize({
+  type: 'mongodb',
+  config: {
+    uri: 'mongodb://mongo.internal:27017/mydb',
+    ssh: {
+      host: 'bastion.example.com',
+      username: 'deploy',
+      privateKeyPath: '~/.ssh/id_rsa',
+    },
+  },
+});
+```
+
+Requires the optional `ssh2` package: `npm install ssh2`.
+
+### Custom `CacheLike` pass-through (v1 compat)
+
+Passing a custom `CacheLike` instance (e.g. a Redis adapter) directly as `cache` is now supported:
+
+```ts
+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.