monsqlize 2.0.2 → 2.0.4

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.4.md](./changelogs/v2.0.4.md); historical details live in the repository changelog archive.
+> **Last updated**: 2026-06-12
 
 ---
 
@@ -9,6 +9,8 @@
 
 | Version | Date | Summary | Details |
 |---------|------|---------|---------|
+| [v2.0.4](./changelogs/v2.0.4.md) | 2026-06-12 | Patch: production-safe Model index rollout controls, `schema-dsl@2.0.9`, capability-index wording cleanup, and documentation home refinements | [View](./changelogs/v2.0.4.md) |
+| [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 +447,10 @@ const result = await msq.collection('orders').insertOne(dataFromMongoose);
 changelogs/
 ├── README.md          # 变更文档说明
 ├── TEMPLATE.md        # 变更文档模板
-├── v2.0.1.md         # 当前发布详细变更
+├── v2.0.4.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 TypeScript 重写发布详细变更
 └── v1.x.y.md         # 历史版本详细变更（仓库归档）
 ```
@@ -497,11 +502,14 @@ changelogs/
 
 ## 相关文档
 
-- [changelogs/v2.0.1.md](./changelogs/v2.0.1.md) - 当前发布详细变更文档
+- [changelogs/v2.0.4.md](./changelogs/v2.0.4.md) - 当前发布详细变更文档
+- [changelogs/v2.0.3.md](./changelogs/v2.0.3.md) - v2.0.3 详细变更文档
+- [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-12
 

package/README.md

@@ -7,6 +7,8 @@ TypeScript-native MongoDB ODM and enhancement layer with v1-compatible APIs, mul
 [![MongoDB](https://img.shields.io/badge/MongoDB-6.x%20%2F%207.x-green.svg)](https://www.mongodb.com/)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen)](https://nodejs.org/)
 
+Documentation: [English](https://vextjs.github.io/monSQLize/) · [简体中文](https://vextjs.github.io/monSQLize/zh/)
+
 ```bash
 npm install monsqlize
 ```
@@ -37,7 +39,7 @@ monSQLize keeps the MongoDB driver mental model while adding the production feat
 
 - Drop-in collection helpers that preserve MongoDB-style CRUD, aggregation, indexes, transactions, and Change Streams.
 - Smart caching through `cache-hub`, including local memory caching, optional Redis-backed L2 caching, automatic invalidation, and function-level caching.
-- A lightweight Model layer with `schema-dsl` validation, hooks, relations, populate, custom methods, timestamps, soft delete, and optimistic locking.
+- A lightweight Model layer with `schema-dsl` validation, hooks, relations, populate, custom methods, timestamps, soft delete, optimistic locking, and production-safe index preflight.
 - Multi-connection-pool support, pool health checks, pool-scoped collections/models, and fallback strategies.
 - Business locks and distributed locks for multi-instance deployments.
 - Saga orchestration for multi-step business workflows.
@@ -72,15 +74,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
 
@@ -258,6 +253,27 @@ module.exports = {
 
 Relative model paths are resolved from `process.cwd()`. In production services, prefer absolute paths such as `path.join(__dirname, 'models')`.
 
+### Production Model Index Rollout
+
+Model-declared indexes are still created automatically by default for backward compatibility. Production services can turn off automatic indexing and run an explicit preflight before creating missing indexes:
+
+```js
+const db = new MonSQLize({
+  type: 'mongodb',
+  databaseName: 'mydb',
+  config: { uri: 'mongodb://localhost:27017' },
+  autoIndex: false
+});
+
+const plan = await db.ensureModelIndexes({ models: ['users'], dryRun: true });
+
+if (plan.totals.conflicts === 0) {
+  await db.ensureModelIndexes({ models: ['users'], throwOnError: true });
+}
+```
+
+`ensureModelIndexes()` creates only missing indexes. It does not drop, rename, or rebuild conflicting indexes.
+
 ### Populate
 
 ```js
@@ -423,14 +439,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 +454,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 +466,10 @@ See the current support and verification documents:
 
 Current TypeScript documentation and examples are the source of truth for the v2 package:
 
-- `docs/**` - current documentation.
+- Complete docs: [English](https://vextjs.github.io/monSQLize/) · [简体中文](https://vextjs.github.io/monSQLize/zh/)
+- `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 +491,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.4`.
 
 Key release-readiness points:
 
@@ -498,11 +526,29 @@ 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.9`; 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.4
+
+- Production-safe Model index rollout controls with `autoIndex`, dry-run preflight, conflict reporting, and explicit `ensureIndexes()` / `ensureModelIndexes()` APIs.
+- `schema-dsl` updated to `2.0.9`, with transitive `cache-hub` aligned to `2.2.4`.
+- User-facing capability and verification documentation wording cleaned up, plus documentation home experience refinements.
+
+### 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.

package/changelogs/v2.0.4.md

@@ -0,0 +1,61 @@
+# v2.0.4 — 2026-06-12
+
+## Overview
+
+v2.0.4 is a production-safety and documentation-quality patch. It keeps the public API backward compatible while adding explicit Model index rollout controls, updating the schema validation dependency, and refining user-facing documentation language.
+
+---
+
+## Runtime Fixes
+
+- Added production-safe Model index controls:
+  - runtime-level and model-level `autoIndex` options.
+  - explicit `ModelInstance.ensureIndexes()` and `MonSQLize.ensureModelIndexes()` APIs.
+  - dry-run index preflight with `existing`, `missing`, `conflicts`, and `failed` classification.
+  - missing-index creation without dropping, renaming, or rebuilding conflicting indexes.
+  - `model-index-error` events for observable automatic-index creation failures.
+- Kept automatic Model indexing enabled by default for backward compatibility.
+- Moved runtime Model index aggregation into the Model runtime helper layer so the strict source-size gate remains clean.
+
+## Dependencies
+
+- Updated `schema-dsl` from `2.0.8` to npm `latest` `2.0.9`.
+- Confirmed `schema-dsl@2.0.9` keeps the required `dsl()` and `validate()` runtime paths compatible with monSQLize.
+- Confirmed the `schema-dsl` transitive `cache-hub` dependency now resolves to `2.2.4`, matching the root direct dependency.
+
+## Documentation
+
+- Documented the recommended production index rollout flow:
+  - set `autoIndex: false` in production services.
+  - run `ensureIndexes({ dryRun: true })` / `ensureModelIndexes({ dryRun: true })`.
+  - create only missing indexes during a low-traffic maintenance window.
+  - monitor TTL and index-build behavior.
+- Corrected create-index documentation to distinguish local `INVALID_ARGUMENT` validation from raw MongoDB driver/server index conflicts.
+- Reworded capability-index and verification-entry documentation to use user-facing availability and verification language instead of internal migration status terms.
+- Refined the documentation home experience with the VextJS-style footer, aligned hero/feature layout, and updated hero data-flow visual.
+
+---
+
+## Compatibility
+
+- SemVer: patch release.
+- Breaking changes: none.
+- Existing v2 imports remain under `dist/cjs`, `dist/esm`, and `dist/types`.
+- Existing default automatic Model indexing behavior remains enabled unless users opt into the new production-safe controls.
+
+---
+
+## Validation
+
+- `npm run lint`
+- `npm run check:docs-examples`
+- `npm run type-check`
+- targeted Model/index unit and integration tests
+- `npm run test:examples`
+- `npm --prefix website run build`
+- `npm run verify:fast`
+- `npm run test:server-matrix`
+- `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.