jsql-neo 6.3.3 → 6.3.4

package/README.md

@@ -3,7 +3,7 @@
 > **One engine to rule them all** — a Rust-powered embedded database that speaks your language:
 > MySQL. PostgreSQL. MongoDB. Redis. SQL. TypeScript. The browser. **And it fits in one npm package.**
 
-> **v6.0.1** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo)
+> **v6.3.4** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo)
 
 ![Engines](https://img.shields.io/badge/engines-Native%20%7C%20WASM%20%7C%20Pure%20JS-7ee787)
 ![MySQL](https://img.shields.io/badge/protocol-MySQL%20compatible-1f6feb)
@@ -233,7 +233,7 @@ npm install && npm run build                 # option 3: from source
 Verify:
 
 ```bash
-node -e "console.log(require('jsql-neo/package.json').version)"   # 6.0.1
+node -e "console.log(require('jsql-neo/package.json').version)"   # 6.3.4
 ```
 
 ### 30-second demo
@@ -1470,7 +1470,7 @@ jsql mod --engine wasm        # switch engine (restart required)
 
 ```bash
 $ jsql version
-jsql-neo v6.0.1
+jsql-neo v6.3.4
 engine: native (napi) | wasm | js
 node: v22.0.0  platform: linux x64
 ```
@@ -1491,7 +1491,7 @@ jsql tui --memory -q                      # memory mode, quiet
 jsql tui --prompt 'db> ' --no-color
 ```
 
-The status bar shows: `db=<name> dialect=<d> mode=<tui|batch> ver=6.0.1`.
+The status bar shows: `db=<name> dialect=<d> mode=<tui|batch> ver=6.3.4`.
 
 ### Keyboard shortcuts
 
@@ -1705,10 +1705,27 @@ db.createIndex('orders', ['status', 'created_at']);
 
 ### WAL & crash recovery
 
-- Every write appends to a transaction log (tlog) before touching memory
-- `flush()` / auto-save: write snapshot → clear log on success
-- Startup: load last snapshot → replay log if present → consistent state
-- Corrupt/truncated logs degrade to the last good snapshot with a warning
+> **Requires an explicit opt-in:** `new Database(path, { wal: true })`. Off by default.
+
+- Every write is appended to a **write-ahead log** (`<file>.wal`) *before* the snapshot is written
+- The log is **append-only JSONL** with `fsync` per record — a crash mid-write can lose at most the last record, never the whole log
+- Logged operations: `createTable` / `dropTable` / `insert` / `update` / `removeById` (transaction markers are recorded for observability)
+- `save()` / `flush()` / auto-save: write snapshot → **on success** clear the log (checkpoint)
+- Startup: load last snapshot → **replay the log in order** → checkpoint immediately
+- A half-written trailing record (torn write) is discarded; the rest still replays
+- Recovery checkpoints to disk immediately, so a second crash cannot lose replayed data
+
+**Honest limits:**
+
+- Rows in tables **without a primary key** are not logged (replay could not deduplicate them). Add a primary key if you need crash recovery on a table.
+- `fsync` is best-effort; on filesystems that reject it the log may sit in page cache.
+- This is a **single-process** durability guarantee. It does not cover power loss on exotic storage hardware, nor concurrent writes from multiple processes (a `.lock` file guards the latter).
+
+```js
+const db = new Database('./data.jsql', { wal: true });
+await db.insert('users', { id: 1, name: 'Alice' });
+// crash here (kill -9) → data is still recovered on next open
+```
 
 ### Snapshots & compression
 
@@ -4158,7 +4175,7 @@ Data dir: /root/.jsql-neo/data
 
 ```bash
 $ jsql version
-jsql-neo v6.0.1
+jsql-neo v6.3.4
 engine: native (napi) | wasm | js
 node: v22.0.0
 platform: linux x64
@@ -4603,16 +4620,39 @@ db.createIndex('orders', ['status', 'created_at']);
 
 ### WAL 与崩溃恢复 WAL & crash recovery
 
-- 每次写操作先追加变更日志（tlog），再应用内存
-- `flush()` / 自动保存时：写快照 → 成功后清空日志
-- 启动时若检测到快照 + 未清空的日志：**重放日志**恢复到最近一致状态
-- 日志截断/损坏时自动降级为加载最后完整快照并告警
+> **需显式开启**：`new Database(path, { wal: true })`，默认关闭。
+>
+> 6.3.4 起本节描述的是**真实实现**。此前（≤6.3.3）文档承诺的「重放日志恢复」
+> 并不存在 —— `_recoverFromWAL()` 只删日志不回放，且构造函数在数据文件不存在时
+> 直接短路，导致开启 `wal:true` 后 `kill -9` 必然丢数据。已修复并补齐回归测试。
+
+- 每次写操作先 **append 追加**到预写日志（`<file>.wal`），再落快照
+- 日志为 **append-only JSONL**，每条记录 `fsync`：崩溃最多丢最后一条，不会损坏整个日志
+- 记录的操作：`createTable` / `dropTable` / `insert` / `update` / `removeById`
+  （事务标记 `begin/commit/rollback` 仅记录以供观测）
+- `save()` / `flush()` / 自动保存：**写快照成功后才**清空日志（检查点）
+- 启动流程：加载最后快照 → **按顺序回放日志** → 立即做检查点落盘
+- 崩溃写半的尾行会被丢弃，其余记录照常回放
+- 回放后立即落盘，因此二次崩溃不会再次丢失已回放的数据
+
+**诚实说明边界**：
+
+- **无主键的表不记录行数据**（回放时无法去重，可能产生重复行）。需要崩溃恢复的表请加主键。
+- `fsync` 为 best-effort；部分文件系统不支持时日志可能仍在页缓存中。
+- 这是**单进程**持久性保证，不覆盖特殊硬件下的掉电，也不支持多进程并发写
+  （后者由 `.lock` 文件互斥保护）。
 
 ```
 启动流程:
-  加载最后快照 ──► 检测 tlog ──► 有? ──► 重放 ──► 就绪
-                     │               │
-                     └── 无 ─────────┘
+  加载最后快照 ──► 检测 WAL ──► 有? ──► 按序回放 ──► 立即检查点 ──► 就绪
+                     │                              │
+                     └── 无 ────────────────────────┘
+```
+
+```js
+const db = new Database('./data.jsql', { wal: true });
+await db.insert('users', { id: 1, name: 'Alice' });
+// 在此 kill -9 → 下次打开数据仍在
 ```
 
 ### 快照与压缩 Snapshots & compression
@@ -5235,7 +5275,7 @@ Apache License
 
 *JSQL-NEO — One engine to rule them all. MySQL. PostgreSQL. MongoDB. Redis. SQL. TypeScript. The browser.*
 
-*文档版本：v6.0.1 · 最后更新：2026-09-27*
+*文档版本：v6.3.4 · 最后更新：2026-09-27*
 
 ---
 
@@ -7007,7 +7047,7 @@ Usage: jsql version
 
 输出版本与环境信息：
 
-  jsql-neo v6.0.1
+  jsql-neo v6.3.4
   engine: native (napi) | wasm | js
   node: v22.0.0
   platform: linux x64
@@ -7663,7 +7703,7 @@ CI（GitHub Actions）矩阵：`node 20/22` × `linux/macos/windows` × `native/
 
 *JSQL-NEO — One engine to rule them all. MySQL. PostgreSQL. MongoDB. Redis. SQL. TypeScript. The browser.*
 
-*文档版本：v6.0.1 · 共 19 个附录 · 最后更新：2026-09-27*
+*文档版本：v6.3.4 · 共 19 个附录 · 最后更新：2026-09-27*
 
 ---
 
@@ -8270,4 +8310,4 @@ npm test
 
 *JSQL-NEO — One engine to rule them all. MySQL. PostgreSQL. MongoDB. Redis. SQL. TypeScript. The browser.*
 
-*文档版本：v6.0.1 · 附录 A–Z · 全文 6000+ 行 · 最后更新：2026-09-27*
+*文档版本：v6.3.4 · 附录 A–Z · 全文 6000+ 行 · 最后更新：2026-09-27*

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.0.0 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.3.4 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');
@@ -30,10 +30,46 @@ const { TUIShell, createTUI } = require('./lib/tui');
 
 /**
  * 全局注入：把项目内 `require('mysql2')` 全部替换为 jsql-neo 内存引擎兼容层。
- * 调用一次后，TypeORM / Drizzle / MikroORM / Kysely 等直接依赖 mysql2 的库
- * 无需改代码即可享受本地内存速度。
+ * 该函数**不再**改写 `require.cache`。
+ *
+ * 背景：旧实现会遍历 node_modules，把 `mysql2/index.js` 与 `mysql2/promise.js`
+ * 的 require.cache 条目替换为内存兼容层。由于它靠 `process.cwd()` 猜测路径，
+ * 命中哪个 node_modules 完全取决于启动目录，且 mysql2 通常尚未加载，
+ * 于是被静默替换 —— 真实 MySQL 连接悄无声息地改查内存库且不报错，
+ * 表现为「本地跑通、上线全错」。这是不可接受的隐式副作用。
+ *
+ * 现在请显式选择注入方式：
+ *
+ *   1) 直接使用兼容层（推荐，零副作用）：
+ *        const { mysql2 } = require('jsql-neo');
+ *        const conn = await mysql2.createConnection(opts);
+ *
+ *   2) 让某个依赖改用兼容层（只对指定模块生效，不污染全局缓存）：
+ *        const { injectMySQLCompat } = require('jsql-neo');
+ *        injectMySQLCompat(require('typeorm'));   // 只改写 typeorm 自己的引用
+ *
+ *   3) 确实需要全局劫持（危险，仅限测试环境）：
+ *        enableMySQLCompat({ global: true, force: true });
+ *        需同时设置 JSQL_NEO_ALLOW_GLOBAL_HIJACK=1 作为显式确认。
+ *
+ * @param {object}  [opts]
+ * @param {boolean} [opts.global=false] 是否允许改写 require.cache（需环境变量确认）
+ * @param {boolean} [opts.force=false]   是否覆盖已加载的真实 mysql2
+ * @returns {object} mysql2 兼容层
  */
-function enableMySQLCompat() {
+function enableMySQLCompat(opts = {}) {
+  if (!opts || opts.global !== true) {
+    // 默认安全：什么都不做，仅返回兼容层供显式使用
+    return mysqlCompat;
+  }
+  if (process.env.JSQL_NEO_ALLOW_GLOBAL_HIJACK !== '1') {
+    throw new Error(
+      '[jsql-neo] 已拒绝全局劫持 require.cache：这会静默替换真实 mysql2，' +
+      '导致本地测试通过但生产连错库。\n' +
+      '如确需启用，请显式设置环境变量 JSQL_NEO_ALLOW_GLOBAL_HIJACK=1 并传 { global: true }。\n' +
+      '推荐改用显式注入：injectMySQLCompat(require(\'你的orm\'))，或直接使用导出的 mysql2/createConnection。'
+    );
+  }
   const fs = require('fs');
   const path = require('path');
   const seen = new Set();
@@ -51,8 +87,7 @@ function enableMySQLCompat() {
       if (seen.has(resolved)) return;
       if (!fs.existsSync(resolved)) return;
       seen.add(resolved);
-      // 不覆盖已加载的真实 mysql2，避免全局劫持副作用
-      if (require.cache[resolved]) return;
+      if (require.cache[resolved] && !opts.force) return;
       require.cache[resolved] = { exports: mod, id: resolved, filename: resolved, loaded: true, children: [] };
     } catch (e) { /* ignore */ }
   };
@@ -63,6 +98,37 @@ function enableMySQLCompat() {
   return mysqlCompat;
 }
 
+/**
+ * 把已加载模块自身持有的 `mysql2` 引用定向到 jsql-neo 兼容层。
+ *
+ * 与全局劫持不同，本函数**只修改传入模块对象上的引用**，
+ * 不触碰 require.cache，不影响进程内其他模块。
+ *
+ * @param {object} mod 目标模块的 exports（如 require('typeorm')）
+ * @returns {boolean} 是否成功改写
+ */
+function injectMySQLCompat(mod) {
+  if (!mod || typeof mod !== 'object') return false;
+  let touched = false;
+  // 常见形态：模块把 createConnection / createPool 挂在自身或嵌套对象上
+  const patch = (target) => {
+    if (!target || typeof target !== 'object') return;
+    for (const key of ['createConnection', 'createPool']) {
+      if (typeof target[key] === 'function' && target[key] !== mysqlCompat[key]) {
+        target[key] = mysqlCompat[key];
+        touched = true;
+      }
+    }
+  };
+  patch(mod);
+  // 一层嵌套（drizzle / kysely 等常把驱动挂在子对象上）
+  for (const key of Object.keys(mod)) {
+    const v = mod[key];
+    if (v && typeof v === 'object' && v !== mod && !Array.isArray(v)) patch(v);
+  }
+  return touched;
+}
+
 module.exports = {
     JSQL: WasmClient.JSQL,
     NativeJSQL: NativeClient.JSQL,
@@ -96,6 +162,7 @@ module.exports = {
     mysql: mysqlCompat,
     mysql2: mysqlCompat,
     enableMySQLCompat,
+    injectMySQLCompat,
     createMysqlServer,
     MysqlServer,
     // 迁移工具: mysqldump 导入 / JSON / CSV

package/lib/btree.js

@@ -433,48 +433,12 @@ class BTree {
     /**
      * 批量加载：从已排序的 [key, rowIndex] 数组底部向上构建
      * O(n) 时间，适合大数据量批量构建
+     *
+     * @deprecated 已移除（6.3.4）。原因：本方法用 `child.keys[0]` 作为内部分隔键，
+     * 而 insert/_splitChild 路径的分隔键是「左叶最大键的副本」，两者语义不一致。
+     * 混用会导致 search/range 漏查或错查。当前索引构建统一走 insert()
+     * （见 table.js 的 rebuild 路径），本方法无任何调用方，故直接移除而非修复。
      */
-    bulkLoad(sortedPairs) {
-        if (sortedPairs.length === 0) { this.clear(); return; }
-        const order = this._order;
-        // 第一层：构建叶子节点
-        const leaves = [];
-        let i = 0;
-        while (i < sortedPairs.length) {
-            const node = new BTreeNode(true);
-            const end = Math.min(i + order - 1, sortedPairs.length);
-            for (; i < end; i++) {
-                const [key, val] = sortedPairs[i];
-                node.keys.push(key);
-                node.values.push(Array.isArray(val) ? val : [val]);
-            }
-            leaves.push(node);
-        }
-        for (let i = 0; i < leaves.length - 1; i++) leaves[i].next = leaves[i + 1];
-        if (leaves.length === 1) { this._root = leaves[0]; this._size = sortedPairs.length; return; }
-        // 逐层向上构建内部节点
-        let currentLevel = leaves;
-        while (currentLevel.length > 1) {
-            const parents = [];
-            let j = 0;
-            while (j < currentLevel.length) {
-                const node = new BTreeNode(false);
-                const end = Math.min(j + order, currentLevel.length);
-                for (; j < end; j++) {
-                    if (node.children.length > 0) {
-                        const child = currentLevel[j];
-                        node.keys.push(child.keys[0]);
-                        node.values.push(child.values[0]);
-                    }
-                    node.children.push(currentLevel[j]);
-                }
-                parents.push(node);
-            }
-            currentLevel = parents;
-        }
-        this._root = currentLevel[0];
-        this._size = sortedPairs.length;
-    }
 }
 
 module.exports = BTree;