monSQLize v3.1.0

monSQLize v3.1.0

Release date: 2026-07-15

Highlights

• Pins the production dependency to registry schema-dsl@3.0.0 and continues to compile Model schemas only through the isolated schema-dsl/runtime integration.
• Consumes the canonical schema-dsl validation result (valid, normalized data, and errors[].path/message/keyword) without relying on deprecated upstream field/type/expected aliases.
• Keeps Model.validate() compatible for monSQLize callers as { valid, errors: [{ field, message }], data }, deriving field from the canonical upstream path.
• Persists successful normalized data across the six complete-document write paths: insertOne, insertMany, insertBatch, replaceOne, findOneAndReplace, and hydrated document save().
• Applies bulk defaults before before-hooks, normalizes before timestamps/version fields, and validates replacement documents before optimistic-lock reads.
• Rejects null, primitive, or array normalized results before any driver operation; failed validation snapshots are never written.
• Preserves timestamps on hydrated save() when versioning is disabled, including documents normalized by schema-dsl.
• Includes the maintained Node 24 GitHub Actions runtime, release metadata checks, TypeScript lint coverage, shared memory-server policy, coverage/package/license budgets, derived-artifact dry-run cleanup, and the lightweight data-task CLI bundle introduced after v3.0.0.

Compatibility boundaries

• Update operators and pipelines are partial mutations, so they are intentionally outside normalized complete-document persistence.
• isRequired() and isOptional() are not required by monSQLize; schema definitions already expose the required/optional state needed by this integration.
• The public monSQLize validation error shape remains stable even though its upstream adapter now consumes schema-dsl's canonical error fields.

Verification

• The release candidate must pass npm run release:preflight, the Node 18/20/22 remote matrix, packed CJS/ESM/TypeScript/CLI consumers, the MongoDB 7/8 server matrix, production dependency audit, and the documentation browser gates.

monSQLize v3.0.0

monSQLize v3.0.0

Release date: 2026-07-14
Release status: Released
Type: Major
Stable predecessor: v2.0.6

Summary

v3.0.0 consolidates the unpublished v2.0.7 work into a major release. It adds bounded production data tasks, Model-only write-path enforcement, runtime-scoped schema-dsl integration, stricter synchronization and optimistic-locking behavior, and production release controls. The major version is intentional because several defaults and failure contracts are stricter than v2.0.6.

Public capability inventory

Bounded production data tasks

• Added the named dataTasks facade with preview(), apply(), previewRestore(), and restore() for two independent source/target instances. CommonJS exposes the same root facade through destructuring; it is not an instance API.
• Added collection-level indexes[], filtered data, explicit fields / source-id identity, deterministic pipeline/handler transforms, approval drift fingerprints, affected-scope BSON backup packages, verification, and reversible restore-safety packages.
• Consolidated data tasks on one DataTaskJob contract and the named dataTasks.preview/apply/previewRestore/restore service; the unpublished instance runner and step configuration were removed.
• Consolidated the CLI on preview, apply, preview-restore, and restore, with task files directly exporting the same Job configuration.
• Production apply requires explicit targetEnvironment, a durable backup.dir, and a non-expired preview approval bound to the job, source, target, and target indexes.
• Write-task environments are restricted to development, test, staging, production, prod, or live; unknown or misspelled names fail planning instead of silently bypassing production gates.
• Data task locks use a renewable lease in the target database, coordinate separate processes, and stop writes after ownership is lost.
• Data task planning uses a bounded stream independent of the public findLimit, exact write-time document CAS includes unexpected-field detection, and expired local leases fail closed before another write.

Write-path policy

• Added writePathPolicy with permissive allow-both default behavior and optional model-only enforcement by namespace.
• Guards cover collection, database, legacy, raw client, management, batch, and aggregate $out / $merge write paths.
• Model writes and Model management methods remain available for namespaces assigned to model-only.

Runtime-scoped schema DSL

• Upgraded schema-dsl to 2.1.6 and moved Model schema compilation to an isolated schema-dsl/runtime owned by each connected monSQLize runtime.
• Added schemaDsl options for runtime options, extension registration, external runtime injection, and explicit validation disablement.
• External runtimes remain application-owned and are not disposed by MonSQLize.close().

Model consistency and query bounds

• Versioned single-document writes now use optimistic concurrency control. Stale writes throw WRITE_CONFLICT.
• Added updateMany() / updateBatch() version modes: counter, strict, and off where supported.
• find() now defaults to findLimit: 500; positive limit and skip values are bounded by findMaxLimit and findMaxSkip. limit(0) keeps MongoDB's unlimited cursor semantics.
• Soft-delete filtering now covers the standard Model read surface, including findPage, ID reads, distinct, aggregate, stream, and explain.
• Populate has-many skip / limit is applied per parent and nested populate is capped by maxDepth (default 5).

Synchronization, cache, and operational safety

• Change Stream targets are processed in order; resume-token persistence is atomic and strict by default.
• Added optional per-target sync idempotency gates and explicit failure/restart state handling.
• Transaction cache invalidations are replayed after successful commit; query caches skip session-scoped reads and avoid refill during write-side invalidation barriers.
• autoIndex: true preflights with listIndexes(), skips matching indexes, creates only missing indexes, and reports conflicts without dropping or rebuilding indexes.
• dropDatabase() treats production, prod, and live as production-like environments requiring allowProduction: true.
• Data-task apply and restore use before/current-image compare-and-set filters, bounded source and backup sizes, ordered manifest checkpoint batches, and fsync-backed atomic backup files.
• Saga step timeouts use OPERATION_TIMEOUT, abort the cooperative context signal, and never trigger retries; failed runtime connection attempts await partial resource cleanup before returning.
• Runtime dependencies are pinned to schema-dsl@2.1.6 and ioredis@5.11.1; Node 18-compatible test tooling uses mongodb-memory-server@10.4.3.
• The release server matrix now strictly requires MongoDB 7.0.37 and 8.0.26 across standalone, replica-set, Driver 6/7, and DataTask integration paths; unavailable combinations fail release preflight instead of being recorded as a successful skip.
• Release candidates must be clean, have a valid installed dependency graph, and already exist on origin; the same preflight also verifies the docs site and packaged MIGRATION.md / SECURITY.md consumer guidance.
• A manual pre-tag authentication workflow verifies the repository's current npm publish credential with npm whoami without creating a tag or publishing.
• Build and test artifact cleanup retries transient Windows filesystem contention, so repeated release-gate compilation does not fail on short-lived ENOTEMPTY, EPERM, or EBUSY races.
• GitHub workflows use actions/setup-node@v6, avoiding the retired Node 20 action runtime while preserving the explicit Node 18/20/22 package test matrix.
• Stable Pages deployment separates immutable release-tag content from current release tooling, so historical stable tags can rebuild their tagged docs with the current audited website toolchain and link gate without deploying unpublished branch content; current releases still require the complete website verification chain.

Compatibility-impacting changes

Review these changes before upgrading from v2.0.6:

1. Versioned Model single-document writes can now throw WRITE_CONFLICT or INVALID_ARGUMENT where v2 behavior could write without a usable expected version.
2. Versioned updateMany() defaults to counter; choose strict for per-document conditional writes or off for compatibility behavior.
3. find() applies a default limit of 500 and validates positive limits/skips against configured caps.
4. Resume-token load/save failures stop Change Stream synchronization unless legacy best-effort options are selected explicitly.
5. updateBatch({ upsert: true }) is rejected. Use upsertOne() or native updateMany(..., { upsert: true }) according to the required insert semantics.
6. dropDatabase() has a broader production-like environment guard.
7. Soft-delete reads, has-many populate paging, nested populate depth, pool validation, and wildcard Change Stream collection filters now follow the documented stricter behavior.
8. Production Jobs require preview -> approval -> apply, a durable affected-scope backup directory, and a new preview after any source/target/index drift.

Upgrade checklist

1. Run the complete release preflight on the exact commit to be tagged.
2. Audit versioned Model writes and select an explicit batch version mode where the default is not desired.
3. Review services that depend on unlimited find() results and configure bounded limits deliberately.
4. Decide whether Change Stream resume-token persistence should remain strict; document any best-effort override.
5. Inventory direct write paths before enabling writePathPolicy: { default: 'model-only' }.
6. Keep autoIndex: false in production rollout paths unless startup-time asynchronous creation is deliberately accepted; use data-task index plans for reviewed production changes.
7. For historical data changes, follow preview -> review -> apply; use previewRestore -> restore only when rollback is required, and retain the full database restore point until acceptance completes.

Release acceptance

The release is publishable only when all of the following pass on the release commit:

• lint, docs-example coverage, TypeScript/tsd checks, strict file-size checks
• complete unit/integration suites and source coverage thresholds
• examples and MongoDB server matrix
• real dataTasks and CLI integration probes
• package dry-run plus temporary-install CJS, ESM, dataTasks, schema-dsl, types, MIGRATION/SECURITY, bin, help, and version smoke tests
• clean-install docs-site type, build, internal-link, and dependency-audit verification
• npm registry, dist-tag, Git tag, GitHub Release, and Pages post-publish acceptance

See the bilingual release preflight guides and production rollout guides for commands and recovery procedures.

monSQLize v1.0.0 - Official Release 🎉

🎉 monSQLize v1.0.0 - Official Release

高性能 MongoDB 增强库 - 正式发布！

---

📦 安装

npm install monsqlize

🌟 为什么选择 monSQLize？

monSQLize 是一个专为 MongoDB 设计的高性能增强库，在保持 100% MongoDB API 兼容的同时，提供：

• ⚡ 10-100x 性能提升 - 智能缓存系统
• 🔄 事务管理优化 - 自动管理 + 优化，减少 30% DB 访问
• 🌐 分布式部署支持 - Redis Pub/Sub 实现多实例缓存一致性
• 📦 便利方法 - 减少 60-80% 代码量
• 🛠️ 运维监控 - 开箱即用的健康检查、性能监控

---

✨ 核心功能

🔵 完整的 CRUD 操作（100%）

• Create: insertOne, insertMany, insertBatch（高性能批处理，10-50x 提升）
• Read: find, findOne, findPage（游标分页，支持千万级数据）, aggregate, count, distinct
• Update: updateOne, updateMany, replaceOne, findOneAndUpdate, findOneAndReplace
• Delete: deleteOne, deleteMany, findOneAndDelete

⚡ 便利方法（减少 60-80% 代码）

• findOneById - 通过 ID 查询，减少 80% 代码
• findByIds - 批量查询，1次 DB 调用
• upsertOne - 简化 upsert 操作
• incrementOne - 原子递增/递减
• findAndCount - 同时返回数据和总数

🚀 智能缓存系统

• TTL/LRU 多种策略
• 自动缓存失效（写操作后）
• 多层缓存（内存 + Redis）
• 并发去重

🔐 完整的事务支持

• 自动管理: withTransaction()
• 手动管理: startTransaction()
• 缓存锁机制（防止脏读）
• 只读优化（-30% DB访问）
• 文档级别锁（16倍并发提升）

📊 深度分页

• 游标分页（性能稳定，不受页数影响）
• 支持千万级数据
• 前后翻页、跳页
• 异步总数统计

🌐 分布式部署

• 多实例缓存一致性（Redis Pub/Sub）
• 分布式事务锁
• 1-5ms 实时广播延迟

🛠️ Admin/Management 功能

• 运维监控: ping, buildInfo, serverStatus, stats
• 数据库管理: listDatabases, dropDatabase, listCollections, runCommand
• Schema 验证: setValidator, setValidationLevel, setValidationAction, getValidator
• 集合管理: stats, renameCollection, collMod, convertToCapped

📈 索引管理

• createIndex, createIndexes, listIndexes, dropIndex, dropIndexes
• 支持所有索引类型（单字段、复合、唯一、TTL、文本、地理空间等）

---

🚀 性能优势

批量插入性能

文档数	MongoDB 原生	monSQLize	提升倍数
1,000	850ms	45ms	18.9x
5,000	4,200ms	180ms	23.3x
10,000	8,500ms	350ms	24.3x
50,000	43,000ms	1,700ms	25.3x

缓存性能

场景	无缓存	有缓存	提升倍数
简单查询	15ms	0.1ms	150x
复杂聚合	500ms	0.5ms	1000x
深度分页	2000ms	1ms	2000x

---

📚 文档与示例

完整文档

• 📖 API 文档
• 📖 快速开始指南
• 📖 事务使用指南
• 📖 分布式部署指南

示例代码

• 📁 完整示例代码目录
• 50+ 可运行示例，涵盖所有功能场景

---

🎯 快速开始

const MonSQLize = require('monsqlize');

// 1. 连接数据库
const db = new MonSQLize({
    type: 'mongodb',
    config: { uri: 'mongodb://localhost:27017/mydb' }
});

const { collection } = await db.connect();

// 2. 基础 CRUD
const users = collection('users');

// 插入
await users.insertOne({ name: 'Alice', age: 30 });

// 查询（启用缓存 5 秒）
const alice = await users.findOne({ name: 'Alice' }, { cache: 5000 });

// 更新（自动失效缓存）
await users.updateOne({ name: 'Alice' }, { $set: { age: 31 } });

// 3. 便利方法
const user = await users.findOneById('507f1f77bcf86cd799439011');
await users.upsertOne({ email: 'alice@example.com' }, { name: 'Alice' });

// 4. 事务支持
await db.withTransaction(async (session) => {
    await users.updateOne({ _id: userId }, { $inc: { balance: -100 } }, { session });
    await orders.insertOne({ userId, amount: 100 }, { session });
});

// 5. 深度分页
const result = await users.findPage({
    query: { status: 'active' },
    page: 1,
    limit: 20
});

---

✅ 质量保证

• ✅ 测试覆盖率: 77%+
• ✅ 测试用例: 1000+ 个测试用例，100% 通过
• ✅ 文档完整性: 100% API 文档覆盖
• ✅ 示例代码: 50+ 可运行示例
• ✅ Lint: 0 错误 0 警告
• ✅ 安全审计: 无高危漏洞

---

🔧 兼容性

Node.js 版本

版本	支持状态	测试状态
14.x	✅ 支持	✅ 已测试
16.x	✅ 支持	✅ 已测试
18.x	✅ 完全支持	✅ 已测试（推荐）
20.x	✅ 完全支持	✅ 已测试（推荐）
22.x	✅ 支持	✅ 已测试

MongoDB Driver 版本

版本	支持状态	测试状态
4.x	✅ 完全支持	✅ 已测试
5.x	✅ 完全支持	✅ 已测试
6.x	✅ 完全支持	✅ 已测试（推荐）
7.x	✅ 完全支持	✅ 已测试

MongoDB Server 版本

• ✅ MongoDB 4.4+
• ✅ MongoDB 5.0+
• ✅ MongoDB 6.0+

---

🎉 Breaking Changes

无破坏性变更

从 v0.3.0 可以平滑升级到 v1.0.0，无需修改任何代码。

---

🙏 贡献者

感谢所有为这个项目做出贡献的开发者！

---

📄 许可证

MIT License - Copyright (c) 2025 vextjs

---

🔗 链接

• npm: https://www.npmjs.com/package/monsqlize
• GitHub: https://github.com/vextjs/monSQLize
• 文档: https://github.com/vextjs/monSQLize/tree/main/docs
• 示例: https://github.com/vextjs/monSQLize/tree/main/examples
• Issues: https://github.com/vextjs/monSQLize/issues

---

🎉 立即开始使用 monSQLize，让你的 MongoDB 应用性能飞跃！