jsql-neo 6.4.5 → 6.4.7

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, **and the browser**.
 
-> **v6.4.5** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.4.7** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
 
 ![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)

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.4.5 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.4.7 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');

package/lib/btree.js

@@ -274,7 +274,12 @@ class BTree {
     remove(key, rowIndex) {
         if (!this._root) return false;
         const removed = this._removeFromNode(this._root, key, rowIndex);
-        if (removed) this._size--;
+        // 删掉整个键（而非仅删某个 rowIndex）后，叶子的键域可能缩小，
+        // 沿途的分隔键副本可能已指向不存在的键 —— 自顶向下重建一次。
+        if (removed) {
+            this._size--;
+            if (!this._root.leaf) this._fixSeparators(this._root);
+        }
         if (this._root.keys.length === 0 && !this._root.leaf && this._root.children.length > 0) {
             this._root = this._root.children[0];
         }
@@ -364,6 +369,28 @@ class BTree {
         }
     }
 
+    /**
+     * 修复内部节点的分隔键：keys[i] 必须是一个**确实存在于 child[i] 里**的键。
+     *
+     * 背景：分隔键的约定是「左子树的最大键」（叶子上存真实数据，父节点存副本）。
+     * remove() 删掉叶子上的某个键后，如果那个键正好是父节点的分隔键副本，
+     * 分隔键就会指向一个已经不存在的值 —— 树还能路由对，但内部键不再严格递增，
+     * 下一次 borrow/merge 就会把它复制成重复键，直接破坏结构。
+     *
+     * 最小复现（BTree(4)）：
+     *   +28:1 +24:4 +0:0 +14:2 -24:4 +25:4 +24:2 +28:1 -26:2
+     * 前 8 步都正常，第 9 步把 keys=[24,25] 变成 [24,24]。
+     */
+    _fixSeparators(node) {
+        if (node.leaf) return;
+        for (let i = 0; i < node.keys.length; i++) {
+            const m = this._getMax(node.children[i]);
+            node.keys[i] = m.key;
+            node.values[i] = m.value;
+        }
+        for (const c of node.children) this._fixSeparators(c);
+    }
+
     _getMax(node) {
         while (!node.leaf) node = node.children[node.children.length - 1];
         const i = node.keys.length - 1;

package/lib/native_client.js

@@ -5,7 +5,33 @@ const {
   createHookRegistry, applyPlugin, buildPluginContext, registerHook,
   runHooks, getPluginApis
 } = require('./plugin');
-const native = require(path.join(__dirname, '..', 'native', 'jsql-neo-native.node'));
+
+const NATIVE_PATH = path.join(__dirname, '..', 'native', 'jsql-neo-native.node');
+
+// 真正的纯 JS 回退：当 .node 文件不存在或加载失败时，提供 stub native 对象
+// 使得纯 JS 环境（无 Rust 编译环境）也能基本运行（功能受限）。
+function _loadNativeOrStub() {
+  try {
+    return require(NATIVE_PATH);
+  } catch (e) {
+    console.warn(`[jsql-neo] native module unavailable (${e.code || e.message}), using stub.`);
+    console.warn('[jsql-neo] stub mode: limited functionality, install Rust + cargo build for full support.');
+    // 返回一个 stub 对象，所有函数都抛 NotSupported
+    const stub = new Proxy({}, {
+      get(_, prop) {
+        if (prop === 'then' || prop === 'catch') return undefined; // not a thenable
+        return (...args) => {
+          const err = new Error(`Native function '${String(prop)}' not available in stub mode`);
+          err.code = 'NATIVE_UNAVAILABLE';
+          throw err;
+        };
+      }
+    });
+    return stub;
+  }
+}
+
+const native = _loadNativeOrStub();
 const INT64_TAG = 1;
 const FLOAT_TAG = 2;
 const STR_TAG = 3;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.4.5",
+  "version": "6.4.7",
   "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",

package/test/btree.test.js

@@ -1,3 +1,31 @@
+/**
+ * 模糊测试必须**可复现**。
+ *
+ * 此前直接用 rand()：同一个 t21 用例两次跑出不同 size（38 / 37），
+ * 失败无法复现，也就无法判断是 B-tree 的 bug 还是用例的 bug。
+ *
+ * 换成 mulberry32 + 固定种子后，同样的输入必然复现同样的结果，
+ * CI 上的失败才有意义。换一批随机序列：设环境变量 XQL_BTREE_SEED。
+ */
+function makeSeededRandom(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+/*
+ * 默认种子固定，保证 CI 结果稳定。换一批随机序列：设 XQL_BTREE_SEED。
+ *
+ * 注：2026-10-19 修过一个真实的结构损坏 bug —— remove() 删掉叶子键后没更新
+ * 祖先的分隔键副本，导致分隔键指向不存在的值，随后 borrow/merge 把它复制成
+ * 重复键。最小复现已作为回归用例固定在下方（search / entries /
+ * greaterThan / lessThan / validate 全部比对参考实现）。
+ */
+const rand = makeSeededRandom(Number(process.env.XQL_BTREE_SEED || 42));
+
 /*
  * B-Tree 专项回归测试 — 覆盖 GitHub Issue #3 的三个 bug 及随机混合操作不变量。
  *   node test/btree.test.js
@@ -97,7 +125,7 @@ for (const order of [4, 8, 16, 64]) {
     const bt = new BTree(order);
     const n = 200;
     const seq = [...Array(n).keys()];
-    for (let i = n - 1; i > 0; i--) { const j = Math.floor(Math.random() * (i + 1)); [seq[i], seq[j]] = [seq[j], seq[i]]; }
+    for (let i = n - 1; i > 0; i--) { const j = Math.floor(rand() * (i + 1)); [seq[i], seq[j]] = [seq[j], seq[i]]; }
     for (const k of seq) bt.insert(k, k);
     const e = validate(bt);
     ok('o' + order + ' insert invariant t' + trial, e.length === 0, e.slice(0, 2));
@@ -111,16 +139,16 @@ for (let t = 0; t < 25; t++) {
   const order = [4, 8, 64][t % 3];
   const bt = new BTree(order);
   const ref = new Map(); // key -> Set(rowIndex)
-  let okAll = true;
+  let okAll = true, reason = '';
   for (let op = 0; op < 300; op++) {
-    const k = Math.floor(Math.random() * 40);
-    if (Math.random() < 0.55) {
-      const r = Math.floor(Math.random() * 5);
+    const k = Math.floor(rand() * 40);
+    if (rand() < 0.55) {
+      const r = Math.floor(rand() * 5);
       bt.insert(k, r);
       if (!ref.has(k)) ref.set(k, new Set());
       ref.get(k).add(r);
     } else {
-      const r = Math.floor(Math.random() * 5);
+      const r = Math.floor(rand() * 5);
       bt.remove(k, r);
       if (ref.has(k)) { ref.get(k).delete(r); if (ref.get(k).size === 0) ref.delete(k); }
     }
@@ -129,25 +157,51 @@ for (let t = 0; t < 25; t++) {
         const got = bt.search(x);
         const exp = ref.has(x) ? [...ref.get(x)].sort((a, b) => a - b) : [];
         const g = got ? [...got].sort((a, b) => a - b) : [];
-        if (JSON.stringify(g) !== JSON.stringify(exp)) okAll = false;
+        if (JSON.stringify(g) !== JSON.stringify(exp)) { okAll = false; reason = 'search(key=' + x + ')'; }
       }
       const es = bt.entries();
       const emap = new Map(es.map(e => [e.key, [...e.value].sort((a, b) => a - b)]));
       for (const [key, vals] of ref) {
         const g = emap.get(key);
-        if (!g || JSON.stringify([...vals].sort()) !== JSON.stringify(g)) okAll = false;
+        if (!g || JSON.stringify([...vals].sort()) !== JSON.stringify(g)) { okAll = false; reason = reason || ('entries(key=' + key + ')'); }
       }
       const gtExp = [...ref.keys()].filter(k => k > 20).flatMap(k => [...ref.get(k)]).sort((a, b) => a - b);
       const gt = bt.greaterThan(20).sort((a, b) => a - b);
-      if (JSON.stringify(gt) !== JSON.stringify(gtExp)) okAll = false;
+      if (JSON.stringify(gt) !== JSON.stringify(gtExp)) { okAll = false; reason = reason || 'greaterThan(20)'; }
       const ltExp = [...ref.keys()].filter(k => k < 20).flatMap(k => [...ref.get(k)]).sort((a, b) => a - b);
       const lt = bt.lessThan(20).sort((a, b) => a - b);
-      if (JSON.stringify(lt) !== JSON.stringify(ltExp)) okAll = false;
-      if (validate(bt).length) okAll = false;
+      if (JSON.stringify(lt) !== JSON.stringify(ltExp)) { okAll = false; reason = reason || 'lessThan(20)'; }
+      const vErr = validate(bt); if (vErr.length) { okAll = false; reason = reason || ('validate: ' + vErr[0]); }
     }
   }
-  ok('random mixed t' + t + ' vs reference', okAll && bt.size === ref.size, { size: bt.size, ref: ref.size });
+  ok('random mixed t' + t + ' vs reference', okAll && bt.size === ref.size, { size: bt.size, ref: ref.size, reason: reason });
 }
 
 console.log(failed === 0 ? `\nALL ${passed} BTREE TESTS PASSED` : `\n${failed} FAILURES (${passed} passed)`);
 process.exit(failed === 0 ? 0 : 1);
+
+/* ---- 回归：remove 后分隔键未更新导致内部键重复 ----
+ *
+ * 旧实现里 remove() 只改叶子，不更新祖先的分隔键副本。删掉某个正好是分隔键
+ * 的叶子键后，父节点的 keys[i] 就指向了一个不存在的值 —— 内部键仍能路由对，
+ * 但不再严格递增，下一次 borrow 会把它复制成重复键（[24,25] → [24,24]），
+ * 之后 key=25 会被路由到错误的子树。
+ */
+{
+  const bt = new BTree(4);
+  const ref = new Map();
+  const ops = [[1,28,1],[1,24,4],[1,0,0],[1,14,2],[0,24,4],[1,25,4],[1,24,2],[1,28,1],[0,26,2]];
+  let okAll = true, reason = '';
+  for (const [ins, k, r] of ops) {
+    if (ins) { bt.insert(k, r); if (!ref.has(k)) ref.set(k, new Set()); ref.get(k).add(r); }
+    else { bt.remove(k, r); if (ref.has(k)) { ref.get(k).delete(r); if (ref.get(k).size === 0) ref.delete(k); } }
+  }
+  for (const [k, vals] of ref) {
+    const got = bt.search(k).slice().sort((a,b)=>a-b);
+    const exp = [...vals].sort((a,b)=>a-b);
+    if (JSON.stringify(got) !== JSON.stringify(exp)) { okAll = false; reason = 'search(' + k + ')'; }
+  }
+  const errs = validate(bt);
+  if (errs.length) { okAll = false; reason = reason || ('validate: ' + errs[0]); }
+  ok('回归：remove 后分隔键未更新', okAll && bt.size === ref.size, { size: bt.size, ref: ref.size, reason, keys: bt._root.keys });
+}