jsql-neo 6.5.16 → 6.5.20

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.5.16** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.20** — stable release · [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)
@@ -47,10 +47,10 @@ irm jsql.vexify.top/setup | iex
 npm install jsql-neo
 ```
 
-**JSQL-NEO** is a Rust-powered embedded database with **zero runtime dependencies**. It runs in Node.js, CLI, Web UI, and the browser (WASM).
+**JSQL-NEO** is a Rust-powered embedded database with a **single runtime dependency** (`@vexify-org/yaggs`, used only by the `jsql` CLI argument parser) — no native libs to compile, no system deps to install. It runs in Node.js, CLI, Web UI, and the browser (WASM).
 
 - **Four wire protocols on one port** — `jsql serve` accepts MySQL, PostgreSQL, MongoDB and Redis clients; `mysql2`, `pg`, `mongodb` and `ioredis` connect directly
-- **Zero dependencies** — no native libs to compile, no system deps to install
+- **Nearly dependency-free** — only `@vexify-org/yaggs` (CLI arg parsing); no native libs to compile, no system deps to install
 - **Three engines, same API** — `native` (Rust N-API), `wasm` (same Rust core), `js` (pure JS)
 - **O(1) primary-key lookups and updates** — hash index, no full-table scan; unindexed filters run in Rust
 
@@ -80,7 +80,7 @@ JSQL-NEO: MySQL + PostgreSQL + MongoDB + Redis + SQL
 | **Redis** | `ioredis`, `redis-cli` — all data types + TTL |
 | **One Port** | Protocol sniffing routes all four clients to the same data |
 | **Zero-Dep TUI** | `jsql tui` — line editing, history, Tab, CJK tables |
-| **Web UI** | Zero-dependency management console + HTTP API |
+| **Web UI** | Management console + HTTP API with no frontend framework |
 | **WASM** | Full engine in browser, no server needed |
 
 ---

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.5.16 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.20 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');
@@ -131,6 +131,9 @@ function injectMySQLCompat(mod) {
 
 module.exports = {
     JSQL: WasmClient.JSQL,
+    // jsql 1.0.0 怀旧兼容层（同步 createTable/dropTable + db.<表名> 属性）
+    // 用法：const { Database } = require('jsql-neo/compat/v1');
+    compatV1: require('./lib/compat/v1'),
     NativeJSQL: NativeClient.JSQL,
     Database: require('./lib/database'),
     Table: require('./lib/table'),

package/lib/btree.js

@@ -20,10 +20,28 @@ class BTree {
      * @param {boolean} unique - 是否唯一索引
      */
     constructor(order = 64, unique = false) {
-        this._order = order;
+        if (typeof order !== 'number' || !Number.isFinite(order)) {
+            throw new Error(`BTree order must be a finite number (got ${order})`);
+        }
+        // order=3 属于 2-3 树，删除时的 merge 需要「三个 1-key 子节点 + 分隔键 = 3 keys」
+        // 塞进一个最多 2 keys 的节点，B-tree 的标准 borrow/merge 在数学上做不到，
+        // 必须换一整套 2-3 树删除算法（或者用 2-3-4 树即 order=4 等价替身）。
+        // 这里把 order<4 归一化成 4：多路树的所有查询语义（search/range/entries/prefix）
+        // 与 order 无关，唯一区别是节点最多存 3 个 key 而不是 2 个 —— 只会更平衡。
+        //
+        // 以前不归一化时 _minKeys = floor(order/2)-1 = 0，允许空节点；_splitChild 在
+        // 只剩 2 个 key 的节点上算出的分隔键下标又超出了右半边界，于是右子节点为空、
+        // 父节点出现重复分隔键 —— 插入 19,7,12 后根节点 keys 变成 [19,19]，
+        // 之后混合增删会静默丢索引条目。
+        this._requestedOrder = order;
+        this._order = Math.max(4, Math.trunc(order));
         this._unique = unique;
         this._root = new BTreeNode();
         this._size = 0;
+        // 必须用归一化后的 this._order 计算下界，否则 order=3 会算出 _minKeys=0
+        // （允许空节点），删除时 merge/borrow 判定全错，最后留下 64 条幽灵条目。
+        this._minKeys = Math.floor(this._order / 2) - 1;
+        this._minDegree = Math.ceil(this._order / 2);
     }
 
     get size() { return this._size; }
@@ -91,22 +109,28 @@ class BTree {
         const newChild = new BTreeNode(child.leaf);
         const mid = Math.floor((this._order - 1) / 2);
 
-        const midKey = child.keys[mid];
-        const midVal = child.values[mid];
+        // 分隔键下标：必须保证左、右两侧都至少留 1 个 key。
+        // 节点满时 keys.length === order-1，右半从 sepIdx+1 开始，
+        // 所以 sepIdx <= order-3。取 min(mid, order-3)：order>=4 时 mid <= order-3 恒成立
+        // （order=4 → 1, order=5 → 2, order=6 → 2, order=64 → 31），行为与标准 B-tree 一致。
+        const sepIdx = Math.max(0, Math.min(mid, this._order - 3));
+
+        const midKey = child.keys[sepIdx];
+        const midVal = child.values[sepIdx];
 
         if (child.leaf) {
             // 叶子：右半移到新节点；分隔键保留在左叶（它是真实数据键），父节点只存副本
-            newChild.keys = child.keys.splice(mid + 1);
-            newChild.values = child.values.splice(mid + 1);
+            newChild.keys = child.keys.splice(sepIdx + 1);
+            newChild.values = child.values.splice(sepIdx + 1);
             newChild.next = child.next;
             child.next = newChild;
         } else {
             // 内部：分隔键提升到父节点并从子节点移除，保持 children = keys + 1
-            newChild.keys = child.keys.splice(mid + 1);
-            newChild.values = child.values.splice(mid + 1);
-            child.keys.splice(mid, 1);
-            child.values.splice(mid, 1);
-            newChild.children = child.children.splice(mid + 1);
+            newChild.keys = child.keys.splice(sepIdx + 1);
+            newChild.values = child.values.splice(sepIdx + 1);
+            child.keys.splice(sepIdx, 1);
+            child.values.splice(sepIdx, 1);
+            newChild.children = child.children.splice(sepIdx + 1);
         }
 
         parent.keys.splice(index, 0, midKey);
@@ -271,81 +295,122 @@ class BTree {
 
     remove(key, rowIndex) {
         if (!this._root) return false;
-        const res = this._removeFromNode(this._root, key, rowIndex);
-        if (!res.found) return false;
-        if (!res.remaining) this._size--;
-        // 只做惰性删除 + 分隔键归一：不再在下降途中借用/合并。
-        // 旧实现先对路由到的子节点做 borrow/merge 再检查键是否存在，
-        // 删除一个不存在的键（或 rowIndex 不匹配）也会重构整棵树，
-        // 合并时丢掉的分隔键副本可能正好是仍然存活的数据键 —— 条目静默丢失。
-        this._normalize();
-        return !res.remaining;
+        const removed = this._removeFromNode(this._root, key, rowIndex);
+        // 删掉整个键（而非仅删某个 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];
+        }
+        return removed;
     }
 
     _removeFromNode(node, key, rowIndex) {
         if (node.leaf) {
             const i = this._lowerBound(node.keys, key);
-            if (i >= node.keys.length || node.keys[i] !== key) return { found: false };
-            const pos = node.values[i].indexOf(rowIndex);
-            if (pos === -1) return { found: false };
+            if (i >= node.keys.length || node.keys[i] !== key) return false;
+            if (!node.values[i].includes(rowIndex)) return false;
             const vals = node.values[i].filter(v => v !== rowIndex);
             if (vals.length === 0) {
                 node.keys.splice(i, 1);
                 node.values.splice(i, 1);
-                return { found: true, remaining: false };
+                return true;
             }
             node.values[i] = vals;
-            return { found: true, remaining: true };
+            return false;
         }
 
-        const i = this._route(node, key);
+        let i = this._route(node, key);
+
+        // 下降前确保子节点有足够键，避免欠满子节点
         const child = node.children[i];
-        if (!child) return { found: false };
-        return this._removeFromNode(child, key, rowIndex);
+        if (child.keys.length <= this._minKeys) {
+            i = this._rebalanceChild(node, i);
+        }
+        return this._removeFromNode(node.children[i], key, rowIndex);
     }
 
-    /**
-     * 惰性回收：删掉节点里空的叶子/空子树，折叠只剩一个孩子的内部节点，
-     * 并按「分隔键 = 左子树最大键」的约定重算所有内部键，最后重建叶子链表。
-     * 节点欠满不影响正确性（插入时仍然按满则分裂），因此无需借用/合并。
-     */
-    _normalize() {
-        const root = this._cleanNode(this._root);
-        this._root = root || new BTreeNode();
-        this._relinkLeaves();
+    _rebalanceChild(parent, i) {
+        if (i > 0 && parent.children[i - 1].keys.length > this._minKeys) {
+            this._borrowFromLeft(parent, i);
+            return i;
+        }
+        if (i + 1 < parent.children.length && parent.children[i + 1].keys.length > this._minKeys) {
+            this._borrowFromRight(parent, i);
+            return i;
+        }
+        if (i > 0) {
+            this._mergeChildren(parent, i - 1);
+            return i - 1;
+        }
+        this._mergeChildren(parent, i);
+        return i;
     }
 
-    _cleanNode(node) {
-        if (node.leaf) return node.keys.length === 0 ? null : node;
-        const kids = [];
-        for (const c of node.children) {
-            const kept = this._cleanNode(c);
-            if (kept) kids.push(kept);
+    _borrowFromLeft(parent, i) {
+        const left = parent.children[i - 1];
+        const right = parent.children[i];
+        if (right.leaf) {
+            // 叶子节点：移动左叶最大键到右叶最小位置
+            const k = left.keys.pop();
+            const v = left.values.pop();
+            right.keys.unshift(k);
+            right.values.unshift(v);
+            // 父节点分隔键应为左叶新的最大值（pop 后的最后一个键）
+            parent.keys[i - 1] = left.keys[left.keys.length - 1];
+            parent.values[i - 1] = left.values[left.values.length - 1];
+        } else {
+            right.keys.unshift(parent.keys[i - 1]);
+            right.values.unshift(parent.values[i - 1]);
+            parent.keys[i - 1] = left.keys.pop();
+            parent.values[i - 1] = left.values.pop();
+            right.children.unshift(left.children.pop());
         }
-        node.children = kids;
-        if (kids.length === 0) return null;
-        if (kids.length === 1) return kids[0];
-        node.keys = [];
-        node.values = [];
-        for (let i = 0; i < kids.length - 1; i++) {
-            const m = this._getMax(kids[i]);
-            node.keys.push(m.key);
-            node.values.push(m.value);
+    }
+
+    _borrowFromRight(parent, i) {
+        const left = parent.children[i];
+        const right = parent.children[i + 1];
+        if (left.leaf) {
+            // 叶子节点：用被移动的键而非旧分隔键，避免重复
+            const k = right.keys.shift();
+            const v = right.values.shift();
+            left.keys.push(k);
+            left.values.push(v);
+            parent.keys[i] = k;
+            parent.values[i] = v;
+        } else {
+            left.keys.push(parent.keys[i]);
+            left.values.push(parent.values[i]);
+            parent.keys[i] = right.keys.shift();
+            parent.values[i] = right.values.shift();
+            left.children.push(right.children.shift());
         }
-        return node;
     }
 
-    _relinkLeaves() {
-        let head = this._root;
-        while (head && !head.leaf) head = head.children[0];
-        let prev = null;
-        let node = head;
-        while (node) {
-            if (prev) prev.next = node;
-            prev = node;
-            node = node.next;
+    /**
+     * 修复内部节点的分隔键：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;
         }
-        if (prev) prev.next = null;
+        for (const c of node.children) this._fixSeparators(c);
     }
 
     _getMax(node) {
@@ -354,6 +419,27 @@ class BTree {
         return { key: node.keys[i], value: node.values[i] };
     }
 
+    _mergeChildren(parent, index) {
+        const left = parent.children[index];
+        const right = parent.children[index + 1];
+        const midKey = parent.keys[index];
+        const midVal = parent.values[index];
+
+        // 叶子节点：分隔键是叶子的副本（已在 left 或 right 中），不能重复压入
+        if (!left.leaf) {
+            left.keys.push(midKey);
+            left.values.push(midVal);
+        }
+        for (const __e of right.keys) left.keys.push(__e);
+        for (const __e of right.values) left.values.push(__e);
+        if (!left.leaf) for (const __e of right.children) left.children.push(__e);
+        if (left.leaf) left.next = right.next;
+
+        parent.keys.splice(index, 1);
+        parent.values.splice(index, 1);
+        parent.children.splice(index + 1, 1);
+    }
+
     // ============================================================
     // 遍历
     // ============================================================

package/lib/compat/v1.js

@@ -0,0 +1,208 @@
+// © Vexify 2026 All Rights Reserved.
+/**
+ * jsql 1.0.0 兼容层（怀旧 API）
+ *
+ * 1.0.0 的公开 API 是**全同步**的：
+ *
+ *   const jsql = require('jsql-neo');
+ *   const db = new jsql.Database('mydb.json');
+ *   db.createTable('users', {
+ *     id:   { type: 'integer', primaryKey: true, autoIncrement: true },
+ *     name: { type: 'string', required: true },
+ *     age:  { type: 'integer' }
+ *   });
+ *   db.users.insert({ name: 'Alice', age: 25 });
+ *   db.users.where({ age: { $gte: 18 } }).orderBy('age', 'desc').limit(10).get();
+ *
+ * v6 引擎本身已经把 Table / Query 的全部方法做成同步的，只有
+ * `Database.createTable()` / `Database.dropTable()` 变成了 async。
+ * 这层只做两件事：
+ *
+ *   1. 同步版 createTable/dropTable（内部走 _createTableSync/_dropTableSync）；
+ *   2. 把 `db.<表名>` 的取值属性镜像到包装对象上，保证老代码直接可用。
+ *
+ * 除了这两个方法，其余行为完全等同 v6：拿到的 Table 就是 lib/table.js 的
+ * Table，查询链就是 lib/query.js 的 Query，不存在第二套实现。
+ *
+ * 注意：这是兼容层，不是"降级"。它不会关闭 v6 的任何能力，
+ * 需要 async API 时通过 `db.raw` 拿到底层 Database 即可。
+ */
+
+const Database = require('../database');
+const Table = require('../table');
+
+/**
+ * 把 1.0.0 的简写 schema（'string' / 'integer' 等）解析成对象。
+ * 与 Database#createTable 里的解析逻辑保持一致，避免两处语义漂移。
+ */
+function parseShorthand(schema) {
+    if (typeof schema !== 'string') return schema || {};
+    const parsed = {};
+    for (const seg of schema.split(',')) {
+        const trimmed = seg.trim();
+        if (!trimmed) continue;
+        const parts = trimmed.split(/\s+/);
+        const field = parts.shift();
+        parsed[field] = parts.join(' ').toLowerCase().trim() || 'string';
+    }
+    return parsed;
+}
+
+/** 深拷贝（优先 structuredClone，退化到 JSON） */
+function deepClone(value) {
+    try {
+        if (typeof structuredClone === 'function') return structuredClone(value);
+    } catch (e) { /* 含函数/类实例时退化 */ }
+    return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * 从行数据推断 schema（仅用于 import 时表还不存在的场景）。
+ * 1.0.0 的 export() 只吐出 rows，不带 schema，所以必须能反推。
+ */
+function inferSchema(rows) {
+    const schema = {};
+    if (!Array.isArray(rows) || rows.length === 0) return schema;
+    const sample = rows[0];
+    for (const [field, value] of Object.entries(sample)) {
+        let type = 'string';
+        if (typeof value === 'number') type = Number.isInteger(value) ? 'integer' : 'float';
+        else if (typeof value === 'boolean') type = 'boolean';
+        else if (Array.isArray(value)) type = 'array';
+        else if (value !== null && typeof value === 'object') type = 'object';
+        schema[field] = { type };
+    }
+    // 1.0.0 的 export() 不带 schema，自增主键信息会丢。
+    // 常见约定：`id` 且整型唯一 —— 还原成 primaryKey + autoIncrement，
+    // 否则 import 后继续 insert 会得到 id=undefined（老代码会当场炸）。
+    if (schema.id && schema.id.type === 'integer') {
+        const ids = rows.map(r => r.id);
+        const unique = new Set(ids).size === ids.length && ids.every(v => typeof v === 'number');
+        if (unique) {
+            schema.id.primaryKey = true;
+            schema.id.autoIncrement = true;
+        }
+    }
+    return schema;
+}
+
+class V1Database {
+    /**
+     * @param {string|null} [filePath] 文件路径；null / ':memory:' 为内存模式
+     * @param {object} [options] 透传给 v6 Database
+     */
+    constructor(filePath, options = {}) {
+        this._db = new Database(filePath, options);
+        // 文件模式导入或目录模式加载时，表已经存在 —— 同样要把
+        // db.<表名> 属性镜像到包装对象上，否则老代码 `db.users` 会 undefined。
+        for (const name of this._db.getTables()) this._bindTable(name);
+    }
+
+    /** 底层 v6 Database（需要 async / 高级能力时用） */
+    get raw() {
+        return this._db;
+    }
+
+    _bindTable(name) {
+        if (typeof name !== 'string' || !name) return;
+        // 内部字段绝不覆盖（表名叫 _db 时不能把引擎句柄删掉）
+        if (name === '_db') return;
+        // 表名撞上类方法（如叫 "save"）时不覆盖方法，保持 1.0.0 的边界行为。
+        if (Object.prototype.hasOwnProperty.call(V1Database.prototype, name)) return;
+        if (Object.prototype.hasOwnProperty.call(this, name)) {
+            delete this[name];
+        }
+        Object.defineProperty(this, name, {
+            get: () => this._db[name],
+            enumerable: true,
+            configurable: true
+        });
+    }
+
+    // ============================================================
+    // 表管理（1.0.0 语义：同步）
+    // ============================================================
+
+    /**
+     * 同步建表。
+     * @param {string} name
+     * @param {object|string} schema
+     * @returns {Table}
+     */
+    createTable(name, schema) {
+        const table = this._db._createTableSync(name, parseShorthand(schema));
+        this._bindTable(name);
+        return table;
+    }
+
+    /**
+     * 同步删表（表不存在时静默返回，符合 1.0.0 的宽松行为）。
+     * @param {string} name
+     */
+    dropTable(name) {
+        if (this._db.hasTable(name)) this._db._dropTableSync(name);
+        if (name !== '_db' && Object.prototype.hasOwnProperty.call(this, name)) delete this[name];
+    }
+
+    hasTable(name) {
+        return this._db.hasTable(name);
+    }
+
+    getTable(name) {
+        return this._db[name];
+    }
+
+    getTables() {
+        return this._db.getTables();
+    }
+
+    // ============================================================
+    // 持久化（与 v6 一致，均为同步）
+    // ============================================================
+
+    save() {
+        return this._db.save();
+    }
+
+    close() {
+        return this._db.close();
+    }
+
+    export() {
+        const data = this._db.export();
+        // 1.0.0 的 export() 是快照：调用方会存起来 / 发出去 / 过一会儿再 import。
+        // v6 的 Table#toJSON() 直接返回 this._rows，原样透传的话后续 insert/update
+        // 会同步改写刚导出的"快照"（import 到新库后两个库还共享同一个数组）。
+        // 这里做一次深拷贝，保持导出结果的不可变语义。
+        const snapshot = {};
+        for (const [name, rows] of Object.entries(data)) {
+            snapshot[name] = Array.isArray(rows) ? deepClone(rows) : rows;
+        }
+        return snapshot;
+    }
+
+    /**
+     * 导入数据。1.0.0 的 export() 只保留 rows，表不存在时按首行推断 schema 建表，
+     * 保证 export → import 往返可用。
+     */
+    import(data) {
+        if (!data || typeof data !== 'object') return this;
+        for (const [name, rows] of Object.entries(data)) {
+            if (!this._db.hasTable(name)) {
+                this.createTable(name, inferSchema(rows));
+            }
+            // 再拷贝一次：避免导入方后续修改自己的数据时串改库内行
+            this._db[name]._loadRows(Array.isArray(rows) ? deepClone(rows) : []);
+        }
+        this._db._markDirtyLegacy && this._db._markDirtyLegacy();
+        return this;
+    }
+}
+
+module.exports = {
+    Database: V1Database,
+    Table,
+    // 便于测试 / 高级用法
+    V1Database,
+    _inferSchema: inferSchema
+};

package/lib/database.js

@@ -1344,11 +1344,15 @@ class Database {
             startedAt: Date.now()
         };
 
-        // 无论隔离级别都要保存完整快照：ROLLBACK 必须撤销本事务写入的行。
-        // 此前 READ_COMMITTED 只记 autoIncrement，回滚后行原样残留（静默不撤销）。
-        // 隔离级别只影响「读取时能否看到其他事务的已提交数据」（这里是单连接内嵌库，
-        // 不涉及并发可见性），不应影响回滚能力。
-        this._transaction.snapshot = this._captureTxSnapshot();
+        if (level === 'REPEATABLE_READ') {
+            // 快照：保存当前所有数据（深拷贝，保证嵌套对象可回滚）
+            this._transaction.snapshot = this._captureTxSnapshot();
+        } else {
+            // READ_COMMITTED：只保存 autoIncrement
+            for (const [name, table] of Object.entries(this._tables)) {
+                this._transaction.autoIncrements[name] = table._autoIncrement;
+            }
+        }
 
         this._savepointStack = [];
         this._walWrite({ op: 'begin', level });
@@ -1370,6 +1374,12 @@ class Database {
 
         if (this._transaction.snapshot) {
             this._restoreTxSnapshot(this._transaction.snapshot);
+        } else {
+            // READ_COMMITTED：没有行快照，只能退回自增值
+            for (const [name, table] of Object.entries(this._tables)) {
+                const v = this._transaction.autoIncrements[name];
+                if (v !== undefined) table._autoIncrement = v;
+            }
         }
 
         this._walWrite({ op: 'rollback', at: this._transaction.startedAt });
@@ -1847,8 +1857,8 @@ class Database {
         let rows = table._applyFilterOptimized(table._getVisibleRows(), filter || {});
         if (limit > 0) rows = rows.slice(offset, offset + limit);
         else if (offset > 0) rows = rows.slice(offset);
-        // P1-11: 返回深拷贝，防止调用方修改（含嵌套对象/数组）影响内部数据
-        rows = rows.map(r => Table.cloneRow(r));
+        // P1-11: 返回浅拷贝，防止调用方修改影响内部数据
+        rows = rows.map(r => ({ ...r }));
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { filter, opts }, rows]);
         return rows;
@@ -1880,8 +1890,8 @@ class Database {
         const row = this._resolveId(table, id);
         // P1-4: 软删除行对普通读取不可见
         if (row && row._deleted) return null;
-        // P1-11: 返回深拷贝，防止调用方修改（含嵌套对象/数组）影响内部数据
-        const result = row ? Table.cloneRow(row) : null;
+        // P1-11: 返回浅拷贝，防止调用方修改影响内部数据
+        const result = row ? { ...row } : null;
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { id }, result]);
         return result;
@@ -1892,7 +1902,7 @@ class Database {
         if (!table) throw createError('ER_NO_SUCH_TABLE', tableName);
         if (!(await this._runHooks('beforeFind', [tableName, { ids }]))) return null;
         // P1-4: 过滤掉软删除行；P1-11: 返回浅拷贝
-        const rows = ids.map(id => this._resolveId(table, id)).filter(r => r !== null && !r._deleted).map(r => Table.cloneRow(r));
+        const rows = ids.map(id => this._resolveId(table, id)).filter(r => r !== null && !r._deleted).map(r => ({ ...r }));
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { ids }, rows]);
         return rows;
@@ -1938,9 +1948,6 @@ class Database {
             const clash = table._rows.find(r => r !== row && r[field] === nv);
             if (clash) throw createError('ER_DUP_ENTRY', `Duplicate entry '${nv}' for key '${field}'`);
         }
-        // 主键/必填列的 NULL 校验：updateById 此前只做类型校验与重复检查，
-        // `UPDATE t SET id = NULL` 会被静默写入（主键行变成 NULL 主键）。
-        table._validateConstraints({ ...row, ...validated }, table._rows.indexOf(row));
         Object.assign(row, validated);
         if (pk) this._walWrite({ op: 'update', table: tableName, pk, id, row: { ...validated } });
         this._emit('update', { table: tableName, id, data: validated });
@@ -1959,9 +1966,7 @@ class Database {
         for (const [id, data] of pairs) {
             const row = this._resolveId(table, id);
             if (row) {
-                const validated = table._validateDataTypes({ ...data }, true);
-                table._validateConstraints({ ...row, ...validated }, table._rows.indexOf(row));
-                Object.assign(row, validated);
+                Object.assign(row, data);
                 count++;
                 if (pk) this._walWrite({ op: 'update', table: tableName, pk, id, row: { ...data } });
             }

package/lib/errors.js

@@ -81,10 +81,22 @@ function createError(codeKey, ...args) {
         return new JSQL_Error('UNKNOWN', `Unknown error: ${codeKey}`, { codeKey, args });
     }
 
-    // 单趟替换所有 %s：既避免参数值里本身含有 %s 时被后续替换再次消费造成串位，
-    // 也避免实参不足时消息里残留裸 %s。
-    let idx = 0;
-    const msg = template.msg.replace(/%s/g, () => (idx < args.length ? String(args[idx++]) : ''));
+    // 单次扫描替换：占位符按模板顺序消费，参数内容原样写入。
+    //
+    // 旧实现是 `for (args) msg = msg.replace('%s', () => String(arg))`，
+    // 每一轮都在**上一轮的结果**上再找第一个 '%s' —— 参数里自带的 '%s'
+    // 会被当成下一个占位符吃掉，且顺序错位：
+    //   createError('ER_BAD_FIELD_ERROR', 'X%sY', 'Z')
+    //     → "Unknown column 'XZY' in '%s'"（X%sY 被改写成 XZY）
+    // 正确结果是 "Unknown column 'X%sY' in 'Z'"。
+    let i = 0;
+    let msg = template.msg.replace(/%s/g, () => (i < args.length ? String(args[i++]) : '%s'));
+    if (args.length > 0 && !/%s/.test(template.msg)) {
+        // 模板里没有占位符（如 ER_NO_TRANSACTION）时，参数不能被静默丢弃：
+        // 追加在后面，至少保留调用方给出的上下文。
+        const rest = args.map(a => String(a)).join(' ');
+        msg = rest ? `${msg} (${rest})` : msg;
+    }
 
     return new JSQL_Error(template.code, msg, { args });
 }

package/lib/migrate.js

@@ -30,12 +30,8 @@ function normalizeSchema(schema) {
     if (d.type === 'varchar' || d.type === 'text' || d.type === 'char') d.type = 'string';
     if (d.type === 'double' || d.type === 'real' || d.type === 'decimal' || d.type === 'numeric') d.type = 'float';
     if (d.type === 'bool') d.type = 'boolean';
-    // 保留用户显式配置的 length；maxLength 只是别名，仅在 length 未给出时回填。
-    // 此前无条件 delete d.length 再仅从 maxLength 恢复，导致显式 length 丢失。
-    if (d.maxLength !== undefined) {
-      if (d.length === undefined) d.length = d.maxLength;
-      delete d.maxLength;
-    }
+    delete d.length;
+    if (d.maxLength) { d.length = d.maxLength; delete d.maxLength; }
     out[name] = d;
   }
   return out;