docs: productize user-facing documentation

Author: rockyshi1993

README.md

@@ -15,32 +15,12 @@ npm install monsqlize
 
 MongoDB is the first complete adapter. MySQL and PostgreSQL adapters are planned as database-native runtime adapters, not as a transparent promise that every database already accepts the same query syntax.
 
-## Table of Contents
-
-- [Why monSQLize](#why-monsqlize)
-- [Adapter Status](#adapter-status)
-- [Runtime Consistency Contract](#runtime-consistency-contract)
-- [When to Use It](#when-to-use-it)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Model Layer](#model-layer)
-- [Caching and Performance](#caching-and-performance)
-- [Advanced Capabilities](#advanced-capabilities)
-- [Migration from the MongoDB Driver](#migration-from-the-mongodb-driver)
-- [Compatibility](#compatibility)
-- [Documentation](#documentation)
-- [Development](#development)
-- [Release Status](#release-status)
-- [Roadmap](#roadmap)
-- [License](#license)
-- [Support](#support)
-
 ## Why monSQLize
 
 monSQLize is not an ORM and it is not just a CRUD wrapper. It is a production data runtime layer: the database driver remains visible, while the operational features teams usually build around the driver are provided in one runtime.
 
 - Database-native adapter APIs: the current stable adapter preserves 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.
+- Smart database caching through `cache-hub`, including local memory caching, optional Redis-backed L2 caching, and automatic invalidation.
 - 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.
 - Change Stream sync helpers with resume token storage.
@@ -103,13 +83,7 @@ monSQLize is usually not the best first choice for pure write-heavy workloads, e
 npm install monsqlize
 ```
 
-Runtime dependencies installed with the package:
-
-- `mongodb` - official MongoDB driver.
-- `schema-dsl` - model schema validation runtime dependency.
-- `cache-hub` - cache and function-cache foundation.
-- `ioredis` - Redis-backed L2 cache and distributed invalidation support.
-- `ssh2` - SSH tunnel support for restricted/private network deployment.
+Use Node.js 18 or newer and provide a MongoDB connection URI. Optional Redis, SSH tunnel, cache, Model, and sync features are configured only when your application enables them.
 
 ## Quick Start
 
@@ -143,7 +117,7 @@ await users.insertOne({
 });
 
 const user = await users.findOne({ email: 'john@example.com' });
-const userById = await users.findOneById('507f1f77bcf86cd799439011');
+const sameUser = await users.findOne({ _id: '507f1f77bcf86cd799439011' });
 
 await users.updateOne(
   { email: 'john@example.com' },
@@ -189,7 +163,7 @@ The package root exports only the public package contract. Deep imports into his
 
 The Model layer is optional. Use it when you want schema validation, hooks, relations, populate, custom methods, timestamps, soft delete, or optimistic locking.
 
-`schema-dsl` is installed automatically as a runtime dependency of monSQLize. monSQLize creates an isolated `schema-dsl/runtime` instance for each `MonSQLize` runtime, then compiles Model schema callbacks when a Model is bound to that runtime.
+Models use the current `schema-dsl/runtime` path through monSQLize. monSQLize creates an isolated schema runtime for each `MonSQLize` instance, then compiles Model schema callbacks when a Model is bound to that runtime.
 
 ### Manual Model Registration
 
@@ -198,7 +172,7 @@ const MonSQLize = require('monsqlize');
 const { Model } = MonSQLize;
 
 Model.define('users', {
-  schema: (dsl) => dsl({
+  schema: (s) => s({
     username: 'string:3-32!',
     email: 'email!',
     password: 'string:6-!',
@@ -263,7 +237,7 @@ const schemaRuntime = createRuntime({
 });
 
 Model.define('tenantUsers', {
-  schema: (dsl) => dsl({
+  schema: (s) => s({
     tenantId: 'tenantId!',
     email: 'email!'
   })
@@ -302,7 +276,7 @@ const User = msq.model('users');
 // models/user.model.js
 module.exports = {
   name: 'users',
-  schema: (dsl) => dsl({
+  schema: (s) => s({
     username: 'string:3-32!',
     email: 'email!'
   }),
@@ -372,7 +346,7 @@ await User.updateMany({ status: 'pending' }, { $set: { status: 'active' } }, {
 
 ```js
 Model.define('posts', {
-  schema: (dsl) => dsl({
+  schema: (s) => s({
     title: 'string:1-200!',
     content: 'string!',
     userId: 'objectId!'
@@ -400,7 +374,7 @@ For aggregation, monSQLize prepends a soft-delete `$match` stage before the user
 
 ## Caching and Performance
 
-monSQLize can cache collection queries and arbitrary async functions.
+monSQLize can cache collection queries and coordinate local/Redis-backed invalidation for database runtime usage.
 
 ```js
 const users = msq.collection('users');
@@ -411,31 +385,14 @@ const hotUser = await users.findOne(
 );
 ```
 
-```js
-const { withCache } = require('monsqlize');
-
-async function getUserProfile(userId) {
-  const user = await msq.collection('users').findOneById(userId);
-  const orders = await msq.collection('orders').find({ userId }).toArray();
-  return { user, orders };
-}
-
-const cachedGetUserProfile = withCache(getUserProfile, {
-  ttl: 300_000,
-  cache: msq.getCache()
-});
-
-await cachedGetUserProfile('user-1');
-```
-
 Cache capabilities include:
 
 - In-memory L1 cache.
 - Optional Redis-backed L2 cache.
 - Automatic invalidation after writes.
-- Function-level caching through `withCache()`.
-- In-flight request deduplication.
-- Namespaces, TTLs, statistics, and conditional caching.
+- Cache namespace, TTL, and distributed invalidation controls.
+
+`withCache()` and `FunctionCache` remain exported for legacy compatibility, but non-database function caching is no longer promoted as a current monSQLize feature area.
 
 ## Advanced Capabilities
 
@@ -532,7 +489,7 @@ See the current support and verification documents:
 
 - [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)
+- [English common scenarios](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)
@@ -543,12 +500,11 @@ See the current support and verification documents:
 Current TypeScript documentation and examples are the source of truth for the v2 package:
 
 - 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.
+- Common scenarios: [English](https://vextjs.github.io/monSQLize/recipes) · [简体中文](https://vextjs.github.io/monSQLize/zh/recipes)
+- Example source: [examples index](https://github.com/vextjs/monSQLize/blob/main/examples/README.md)
+- Documentation source: [docs/en](https://github.com/vextjs/monSQLize/tree/main/docs/en) · [docs/zh](https://github.com/vextjs/monSQLize/tree/main/docs/zh)
+- Compatibility checks: [test/compatibility](https://github.com/vextjs/monSQLize/tree/main/test/compatibility)
+- Verification mapping: [test/validation](https://github.com/vextjs/monSQLize/tree/main/test/validation)
 
 Historical v1 assets are useful for tracing old behavior, but they are not the current publishing surface for v2.
 
@@ -586,98 +542,24 @@ npm run test:server-matrix
 npm run test:real-env:private
 ```
 
-`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.
+`check:docs-examples` verifies the 98/98 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 release train targets `v2.0.7`.
-
-Key release-readiness points:
-
-- TypeScript rewrite completed for the current runtime and test entry 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 `schema-dsl@2.1.1`; 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
 
-### Adapter roadmap
-
 - MongoDB remains the stable adapter and the current production runtime.
 - MySQL and PostgreSQL adapters will be introduced as database-native adapters under the same production runtime contract.
 - Adapter status will move from planned to alpha/stable only after runtime support, public types, examples, and verification coverage are present.
 - The project does not currently promise production-ready "one query syntax automatically adapts to every database" behavior.
-
-### v2.0.7
-
-- Package metadata and public release indexes now match the current data-runtime positioning without promoting business lock or Saga orchestration as primary package capabilities.
-- Hidden business lock and Saga compatibility pages now make their v2 runtime boundaries explicit for existing callers.
-- `npm run test:unit` uses the maintained unified runner unit group.
-- Validation ledgers now match the current 56 runnable TypeScript documentation examples.
-- Model v1 methods factory warnings now route through the runtime logger instead of direct console output.
-
-### v2.0.8
-
-- Model schema validation now uses an isolated `schema-dsl/runtime` instance per MonSQLize runtime, with `schemaDsl` configuration for runtime options, extension registration, runtime injection, explicit validation disablement, and fail-closed dependency resolution diagnostics.
-
-### v2.0.6
-
-- Dependency alignment carried the shared schema-dsl ESM/CJS custom type registry fix to downstream vext applications.
-- NodeNext declaration compatibility for ESM consumers through generated `*.d.mts` mirrors and import-side `types` conditions.
-- Restored v1-compatible root option type exports.
-
-### 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 invalidation 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.
-- Documentation and public types aligned with the current runtime behavior.
-
-### v2.0.0
-
-- TypeScript-native runtime and declarations.
-- v1 smooth-upgrade compatibility bridge.
-- Multi-level cache and function-cache support through `cache-hub`.
-- Transactions, connection pools, Change Stream sync, and slow-query logging.
-- Model layer with `schema-dsl` validation, relations, populate, hooks, and custom methods.
-
-### v2.x
-
 - Query analyzer improvements.
 - Automatic index suggestions.
 - Migration tooling.
 - GraphQL integration experiments.
 - More real-environment validation coverage.
 
-### v3.0+
-
-- MySQL runtime adapter experiments.
-- PostgreSQL runtime adapter experiments.
-- Shared production runtime capabilities across database-native adapters.
-- Cross-database sync middleware experiments.
-
 ## License
 
 monSQLize is released under the [Apache License 2.0](./LICENSE).

changelogs/unreleased.md

@@ -18,6 +18,7 @@
 - Upgraded `schema-dsl` to `2.1.1` and moved Model schema compilation/validation onto a MonSQLize runtime-scoped `schema-dsl/runtime` engine. `schemaDsl` now supports runtime options, extension registration, external runtime injection, explicit validation disablement, and fail-closed dependency resolution diagnostics.
 - Fixed `schemaDsl: { runtime, extensions }` lifecycle handling so injected runtimes register extensions once during `connect()` instead of registering the same factory during construction and reconnect setup.
 - Made injected `schema-dsl/runtime` extension registration idempotent across failed connect retries, close/reconnect cycles, shared external runtime instances, incremental/reordered extension sets, partial extension-registration failures, external runtime resets, and source-stable function-valued definitions. Function fingerprinting now distinguishes closure-sensitive definitions from stable local scopes, including destructuring, nested helpers, templates, class/object methods, private/member access, regex literals, reserved syntax tokens, semicolonless local declarations with and without initializers, and break/continue labels; conflicting closure definitions still surface through schema-dsl.
+- Hardened `schema-dsl/runtime` loading across CJS, ESM, and TypeScript-generated CJS test entry points; extended function fingerprinting for numeric literals and Unicode identifiers; and aligned full-document Model validation, docs, examples, and public type examples with the recommended `schema: (s) => s(...)` DSL callback style.
 - Cleaned Model schema validation documentation so the primary path consistently describes runtime-scoped `schema-dsl/runtime`, and added schema-dsl runtime resolution to the `INVALID_CONFIG` troubleshooting surface.
 - Raised the default `mongodb-memory-server` launch timeout to 30 seconds for test, validation, examples, and `useMemoryServer` paths while keeping `MONSQLIZE_MEMORY_MONGO_LAUNCH_TIMEOUT_MS` as the override.
 - Added a short-lived read-cache dirty barrier around writes and transaction commits. Cached reads now bypass and avoid refilling query cache while a namespace is being invalidated, reducing stale-cache windows when a process exits between a database write and post-write invalidation.
@@ -48,3 +49,7 @@
 - Clarified the `db()` / `collection()` / `use()` documentation path: quick-start and import examples now name the runtime `msq`, cross-database business examples prefer `use(name).collection(name)`, and `db(null)` validation docs now match the current runtime behavior.
 - Repositioned README, package metadata, and bilingual documentation as a database-native production data runtime layer, with MongoDB stable today and MySQL/PostgreSQL adapters clearly marked as planned.
 - Enhanced the documentation home hero illustration with CSS-driven SVG line flow, moving data packets, staggered node pulses, subtle scene breathing, and reduced-motion-safe visible cues.
+- Fixed documentation-site footer localization so the English and Chinese home pages no longer show both language footer navigation blocks at the same time.
+- Hid hand-written Markdown table-of-contents blocks in the Rspress documentation site so they no longer duplicate the generated right-side page outline.
+- Corrected the multi-pool documentation path: the page now presents `new MonSQLize({ pools: [...] })` as the recommended setup, removes stale pinned install versions, and aligns adjacent connection, pool-chain, API index, capability index, function-cache, and Saga installation docs with the current package.
+- Repositioned `withCache()` / `FunctionCache` as hidden legacy compatibility surfaces, removed them from current cache/navigation/API recommendation paths, aligned cache examples with database query caching, and corrected stable docs drift for pool health status, Node.js runtime version, and the 98/98 docs-example matrix.