monsqlize 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # CHANGELOG
 
-> Summary index — current release details are packaged in [changelogs/v2.0.2.md](./changelogs/v2.0.2.md); historical details live in the repository changelog archive.
-> **Last updated**: 2026-06-09
+> Summary index — current release details are packaged in [changelogs/v2.0.3.md](./changelogs/v2.0.3.md); historical details live in the repository changelog archive.
+> **Last updated**: 2026-06-11
 
 ---
 
@@ -9,6 +9,7 @@
 
 | Version | Date | Summary | Details |
 |---------|------|---------|---------|
+| [v2.0.3](./changelogs/v2.0.3.md) | 2026-06-11 | Patch: v1 compatibility fixes, public stats APIs, standalone docs-site link safety, bilingual docs consistency, and release preflight alignment | [View](./changelogs/v2.0.3.md) |
 | [v2.0.2](./changelogs/v2.0.2.md) | 2026-06-09 | Patch: direct runtime, optional and development dependencies pinned to exact versions for deterministic consumer installs | [View](./changelogs/v2.0.2.md) |
 | [v2.0.1](./changelogs/v2.0.1.md) | 2026-06-03 | Patch: model collection/pool compatibility, automatic-index task dedupe, runtime cache/pool v1 smooth-upgrade fixes, and current docs/types alignment | [View](./changelogs/v2.0.1.md) |
 | [v2.0.0](./changelogs/v2.0.0.md) | 2026-06-01 | 🎉 **v2.0.0 — TypeScript rewrite**: full TypeScript source, cache-hub integration, schema-dsl `^2.0.3` TS dependency, Apache-2.0 licensing, English README, MultiLevel cache support, v1 API compat preserved, optimized npm artifact boundary without default sourcemaps, JSDoc coverage complete, `getPoolStats/getPoolHealth` keyed by pool name, v1 compat fixes included, workspace smooth-upgrade bridge validated for downstream consumers | [View](./changelogs/v2.0.0.md) |
@@ -445,7 +446,9 @@ const result = await msq.collection('orders').insertOne(dataFromMongoose);
 changelogs/
 ├── README.md          # 变更文档说明
 ├── TEMPLATE.md        # 变更文档模板
-├── v2.0.1.md         # 当前发布详细变更
+├── v2.0.3.md         # 当前发布详细变更
+├── v2.0.2.md         # v2.0.2 详细变更
+├── v2.0.1.md         # v2.0.1 详细变更
 ├── v2.0.0.md         # v2 TypeScript 重写发布详细变更
 └── v1.x.y.md         # 历史版本详细变更（仓库归档）
 ```
@@ -497,11 +500,13 @@ changelogs/
 
 ## 相关文档
 
-- [changelogs/v2.0.1.md](./changelogs/v2.0.1.md) - 当前发布详细变更文档
+- [changelogs/v2.0.3.md](./changelogs/v2.0.3.md) - 当前发布详细变更文档
+- [changelogs/v2.0.2.md](./changelogs/v2.0.2.md) - v2.0.2 详细变更文档
+- [changelogs/v2.0.1.md](./changelogs/v2.0.1.md) - v2.0.1 详细变更文档
 - [README.md](./README.md) - 项目说明
 - [docs/](https://github.com/vextjs/monSQLize/blob/main/docs/index.md) - API 文档
 
 ---
 
-**最后更新**: 2026-06-03
+**最后更新**: 2026-06-11
 

package/README.md

@@ -72,15 +72,8 @@ Runtime dependencies installed with the package:
 - `schema-dsl` - model schema validation runtime dependency.
 - `cache-hub` - cache and function-cache foundation.
 - `async-lock` - local concurrency lock support.
-
-Optional dependencies:
-
-- `ioredis` - required only when you enable Redis / L2 cache features.
-- `ssh2` - required only when you connect through an SSH tunnel.
-
-```bash
-npm install ioredis ssh2
-```
+- `ioredis` - Redis-backed L2 cache, distributed invalidation, and distributed lock support.
+- `ssh2` - SSH tunnel support for restricted/private network deployment.
 
 ## Quick Start
 
@@ -423,14 +416,14 @@ const user = await users.findOne({ email });
 const list = await users.find({ status: 'active' }).toArray();
 ```
 
-The current v2.0.1 release has been validated against the workspace consumers `chat`, `payment`, `user`, `admin`, `search`, `vext`, and `permission-core` without requiring business-source changes in those projects.
+The v2 line has been validated against the workspace consumers `chat`, `payment`, `user`, `admin`, `search`, `vext`, and `permission-core` without requiring business-source changes in those projects.
 
 ## Compatibility
 
 | Surface | Current Support |
 |---|---|
 | Node.js | `>=18.0.0`; CI covers Node 18 / 20 / 22. |
-| MongoDB driver | `mongodb@^6.21.0` baseline; driver 7 has additional compatibility coverage. |
+| MongoDB driver | `mongodb@6.21.0` runtime baseline; driver 7.2.0 has additional compatibility coverage. |
 | MongoDB server | Memory-server based 6.x / 7.x validation is covered by the project test matrix. |
 | Module systems | CommonJS and ESM are both validated. |
 | TypeScript | Public declarations are published from `dist/types/index.d.ts`. |
@@ -438,9 +431,11 @@ The current v2.0.1 release has been validated against the workspace consumers `c
 
 See the current support and verification documents:
 
-- [docs/README.md](https://github.com/vextjs/monSQLize/blob/main/docs/README.md)
-- [docs/support-matrix.md](https://github.com/vextjs/monSQLize/blob/main/docs/support-matrix.md)
-- [docs/verification-entrypoints.md](https://github.com/vextjs/monSQLize/blob/main/docs/verification-entrypoints.md)
+- [English documentation](https://github.com/vextjs/monSQLize/blob/main/docs/en/README.md)
+- [Chinese documentation](https://github.com/vextjs/monSQLize/blob/main/docs/zh/README.md)
+- [English recipes](https://github.com/vextjs/monSQLize/blob/main/docs/en/recipes.md)
+- [Support matrix](https://github.com/vextjs/monSQLize/blob/main/docs/en/support-matrix.md)
+- [Verification entry points](https://github.com/vextjs/monSQLize/blob/main/docs/en/verification-entrypoints.md)
 - [test/compatibility/README.md](https://github.com/vextjs/monSQLize/blob/main/test/compatibility/README.md)
 - [test/validation/VERIFICATION-PROGRESS.md](https://github.com/vextjs/monSQLize/blob/main/test/validation/VERIFICATION-PROGRESS.md)
 
@@ -448,7 +443,9 @@ See the current support and verification documents:
 
 Current TypeScript documentation and examples are the source of truth for the v2 package:
 
-- `docs/**` - current documentation.
+- `docs/en/**` - default English documentation.
+- `docs/zh/**` - Simplified Chinese documentation.
+- `docs/en/recipes.md` / `docs/zh/recipes.md` - shortest copy-ready paths for common setup scenarios.
 - `examples/**` - TypeScript examples.
 - `test/compatibility/**` - package exports and compatibility guards.
 - `test/validation/**` - verification ledgers and mapping notes.
@@ -470,27 +467,34 @@ npm run build
 npm run type-check
 npm test
 npm run verify:fast
+npm run verify:full
 npm run release:preflight
 ```
 
-Release preflight runs linting, type checks, size guards, runtime checks, compatibility checks, refactor guards, the default test suite, and `npm pack --dry-run`.
+Release preflight runs linting, type checks, size guards, runtime checks, compatibility checks, refactor guards, production dependency audit, the default test suite, and `npm pack --dry-run`.
 
 `npm run release:publish` runs the preflight gate once and then calls `npm publish --ignore-scripts` so the final publish step does not repeat the full lifecycle gate. Raw `npm publish` is still guarded by `prepublishOnly`.
 
 Optional commands:
 
 ```bash
+npm run check:docs-examples
 npm run test:examples
 npm run test:coverage
+npm run test:audit
 npm run test:server-matrix
 npm run test:real-env:private
 ```
 
-`test:real-env:private` is intentionally opt-in and expects private environment variables. It is not part of the default CI or release gate.
+`check:docs-examples` verifies the 97/97 bilingual documentation matrix, runnable-example runner parity, shared-example targets, doc-check targets, and user-facing path text.
+
+`test:examples`, `test:server-matrix`, and `config.useMemoryServer` use a fixed `mongodb-memory-server` policy: MongoDB `7.0.14` by default, binaries cached under `.cache/mongodb-memory-server/binaries`, and temporary data paths created under `.cache/mongodb-memory-server/db` with forced cleanup for project-managed paths. Stale managed data paths whose owner PID is no longer alive are pruned before new memory-server launches. Override with `MONSQLIZE_MEMORY_MONGO_BINARY_VERSION`, `MONSQLIZE_REPLSET_BINARY_VERSION`, `MONGOMS_DOWNLOAD_DIR`, or `MONSQLIZE_MEMORY_SERVER_DB_DIR` when needed.
+
+`test:coverage` is the independent 90% coverage governance gate for the published CJS runtime artifact. `test:audit` checks production dependencies against the npm registry. `test:real-env:private` is intentionally opt-in and expects private environment variables. Coverage and private real-environment checks are not part of the default CI or release gate.
 
 ## Release Status
 
-The current published release is `v2.0.1`.
+The current published release is `v2.0.3`.
 
 Key release-readiness points:
 
@@ -498,11 +502,23 @@ Key release-readiness points:
 - Package exports are consolidated under `dist/cjs`, `dist/esm`, and `dist/types`.
 - npm packages include the runtime bundles and declaration files only; source maps are disabled by default and can be generated locally with `MONSQLIZE_BUILD_SOURCEMAPS=1 npm run build`.
 - v1 smooth-upgrade compatibility has been validated against the target workspace consumers.
-- `schema-dsl` follows the npm `latest` TypeScript line `^2.0.3`; deprecated `2.3.x` mistake releases are intentionally excluded.
+- `schema-dsl` follows the npm `latest` TypeScript line `schema-dsl@2.0.8`; deprecated `2.3.x` mistake releases are intentionally excluded.
 - GitHub Actions publishes to npm from `v*` tags after running `npm run release:preflight`; the publish step skips duplicate lifecycle scripts because the gate already ran in the same job.
 
 ## Roadmap
 
+### v2.0.3
+
+- v1 compatibility patch for documented `findPage({ cache })` behavior.
+- Public transaction and distributed cache invalidator statistics APIs.
+- Standalone documentation-site link safety and bilingual docs consistency fixes.
+- Release preflight alignment for bilingual docs paths and production dependency audit.
+
+### v2.0.2
+
+- Deterministic dependency metadata patch.
+- `ioredis` and `ssh2` are installed with monSQLize by default, so Redis-backed cache/locks and SSH tunnels no longer require a separate dependency install step.
+
 ### v2.0.1
 
 - v1 smooth-upgrade compatibility patch for Model actual collection names, scoped pools/databases, automatic-index dedupe, and cache/pool option aliases.

package/changelogs/README.md

@@ -10,6 +10,8 @@
 changelogs/
 ├── README.md           # 本说明文档
 ├── TEMPLATE.md         # 变更文档模板
+├── v2.0.3.md          # v2.0.3 详细变更
+├── v2.0.2.md          # v2.0.2 详细变更
 ├── v2.0.1.md          # v2.0.1 详细变更
 ├── v2.0.0.md          # v2.0.0 详细变更
 └── v1.x.y.md          # 历史版本详细变更（仓库归档）
@@ -44,19 +46,19 @@ changelogs/
 
 ### 按版本类型
 
-- **正式发布**: v2.0.1, v2.0.0, v1.0.0
+- **正式发布**: v2.0.3, v2.0.2, v2.0.1, v2.0.0, v1.0.0
 - **功能版本**: v1.x
 - **修复版本**: v1.x.y
 
 ### 按功能领域
 
-- **TypeScript 重构与 v1 平滑升级**: v2.0.1, v2.0.0
+- **TypeScript 重构与 v1 平滑升级**: v2.0.3, v2.0.2, v2.0.1, v2.0.0
 - **实时监听 / 管理功能 / 核心功能**: v1.x 历史版本
 
 ### 按风险级别
 
 - **P0 (Critical)**: v2.0.0
-- **Patch**: v2.0.1
+- **Patch**: v2.0.3, v2.0.2, v2.0.1
 - **P1 (High)**: v1.x 破坏性或高风险历史版本
 - **P2 (Low)**: v1.x 修复版本
 
@@ -151,6 +153,8 @@ git push origin main --tags
 
 | 版本 | 文件 | 状态 | 发布日期 |
 |------|------|------|---------|
+| v2.0.3 | v2.0.3.md | ✅ 已发布 | 2026-06-11 |
+| v2.0.2 | v2.0.2.md | ✅ 已发布 | 2026-06-09 |
 | v2.0.1 | v2.0.1.md | ✅ 已发布 | 2026-06-03 |
 | v2.0.0 | v2.0.0.md | ✅ 已发布 | 2026-06-01 |
 | v1.x | 仓库历史归档 | ✅ 已发布 | 2025-12-03 起 |
@@ -158,6 +162,6 @@ git push origin main --tags
 ---
 
 **目录版本**: 2.0
-**最后更新**: 2026-06-03
+**最后更新**: 2026-06-11
 **维护者**: monSQLize Team
 

package/changelogs/v2.0.0.md

@@ -109,7 +109,7 @@ const msq = new MonSQLize({
 });
 ```
 
-Requires the optional `ssh2` package: `npm install ssh2`.
+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)
 

package/changelogs/v2.0.3.md

@@ -0,0 +1,58 @@
+# v2.0.3 — 2026-06-11
+
+## Overview
+
+v2.0.3 is a compatibility and documentation-quality patch. It keeps the public API backward compatible while restoring documented v1 behaviors, tightening release checks, and making the bilingual documentation site safer to consume as a standalone site.
+
+---
+
+## Runtime Fixes
+
+- Restored documented `findPage({ cache })` page-result caching, cache invalidation, after/before totals, and v1-style totals TTL / hint / collation behavior.
+- Restored public transaction statistics parity through `getTransactionStats()`, including p95/p99 duration, success rate, read-only ratio, and bounded sample tracking.
+- Wired documented transaction defaults and lock settings into runtime transaction creation.
+- Added `getDistributedCacheInvalidatorStats()` so distributed cache invalidation statistics are available through a public API instead of private runtime fields.
+- Aligned pool selection with public health status updates and forwarded direct pool `tags` preferences into automatic pool selection.
+- Restored `SSHConfig.port` in public declarations and added a type guard against accidental `SSHConfig` shape drift.
+
+## Documentation and Examples
+
+- Replaced documentation-private runtime fields with public APIs across admin, database operations, explain, model relations, transaction, distributed deployment, sync backup, and pool health docs.
+- Converted source/example file links in the standalone documentation site to GitHub URLs.
+- Strengthened the 97/97 bilingual document example matrix and kept the final 56 runnable examples, 19 shared-example docs, and 22 doc-check docs in sync.
+- Refreshed docs-site navigation, ObjectId/ID query grouping, localized top navigation, home hero, logo presentation, theme parity, and mobile wrapping.
+- Added focused runnable examples for index management, aggregation-pipeline updates, upsert, function cache, model hooks, relations, nested populate, runtime events, CountQueue, pool chain routing, pool health checks, transaction optimization stats, and advanced Saga flows.
+- Normalized source, type, test, example, script, config, and package output text to English-only wording.
+
+## Dependencies and Release Gate
+
+- Fixed the root `cache-hub` direct dependency at `2.2.4`.
+- Updated `schema-dsl` to the current supported TypeScript line `2.0.8` while continuing to exclude deprecated `2.3.x` mistake releases.
+- Kept `verify:full` as the reproducible full functional gate and left the 90% coverage threshold on the independent `test:coverage` governance command.
+- Updated server-matrix runners to execute compiled integration tests from `.generated/test-dist`.
+- Updated release preflight to validate the current bilingual documentation paths and include the production dependency audit gate.
+
+---
+
+## Compatibility
+
+- SemVer: patch release.
+- Breaking changes: none.
+- Existing v2 public imports remain under `dist/cjs`, `dist/esm`, and `dist/types`.
+- Redis, SSH, Model, multi-pool, Saga, Change Stream, and cache features remain opt-in by configuration where applicable.
+
+---
+
+## Validation
+
+- `npm run check:docs-examples`
+- `npm run type-check`
+- targeted runtime / transaction / findPage regression tests
+- `npm run test:unit`
+- `npm run test:integration`
+- `npm run test:examples`
+- `npm run lint`
+- `npm run test:audit`
+- `git diff --check`
+
+Full release validation is handled by `npm run release:preflight`, `npm pack --dry-run`, `npm publish --dry-run`, and pack install smoke before publishing.