jsql-neo 6.5.17 → 6.5.22

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.17** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.22** — 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/bin/jsql

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 const path = require('path');
 const fs = require('fs');
-const yaggs = require('@vexify-org/yaggs');
+// @vexify-org/yaggs 是可选依赖：缺失时（离线安装/私有源不可达/lockfile 漂移）
+// 用内置 shim 兜底，保证 --help/--version 及核心命令仍能启动（#24）。
+let yaggs;
+try { yaggs = require('@vexify-org/yaggs'); }
+catch (e) { yaggs = null; }
 const { ModuleManager } = require('../lib/mod');
 const Database = require('../lib/database');
 const migrate = require('../lib/migrate');
@@ -29,7 +33,10 @@ const manager = new ModuleManager();
 
 const RAW_ARGV = process.argv.slice(2);
 
-const cli = yaggs({ pkg: require('../package.json') })
+const _pkg = require('../package.json');
+const cli = (yaggs || require('./yaggs-fallback').buildYaggsFallback(_pkg))({
+  pkg: _pkg,
+})
   .usage('jsql <command> [options]')
   .option('help', { alias: ['h'], type: 'boolean', description: 'Show help' })
   .command('mod', 'Module management', (sub) => {

package/bin/yaggs-fallback.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * Minimal @vexify-org/yaggs-compatible CLI shim.
+ *
+ * Used when the optional dependency @vexify-org/yaggs is not installed
+ * (offline install, private registry unreachable, lockfile drift, …).
+ * Without this shim, bin/jsql crashed on every invocation — even --help /
+ * --version — because the top-level `require('@vexify-org/yaggs')` threw.
+ *
+ * The shim mirrors the fluent API surface bin/jsql relies on:
+ *   .usage(str).option(name, cfg).command(name, desc, builder, handler)
+ *   .middleware(fn).run(argv)
+ *
+ * It captures every command handler registered via the fluent chain and
+ * dispatches to it with a minimal `--key value` / `--flag` argument parse.
+ * This keeps --help/--version and the core commands (serve, export, import,
+ * mod, plugin, …) working even when the optional dependency is absent.
+ */
+
+function buildYaggsFallback(pkg) {
+  // 与 @vexify-org/yaggs 的调用形态一致：buildYaggsFallback(pkg)({ pkg }) 返回 CLI 对象。
+  return function makeCli(opts) {
+    const realPkg = (opts && opts.pkg) || pkg;
+    const commands = new Map();
+    let usageStr = '';
+    const self = {
+    usage(u) { usageStr = u; return self; },
+    option() { return self; },
+    positional() { return self; },
+    middleware() { return self; },
+    command(name, description, builder, handler) {
+      // 兼容两种签名：command(name, descObj) 或 command(name, desc, builder, handler)
+      let h = handler;
+      let desc = description;
+      if (description && typeof description === 'object') {
+        desc = description.description;
+        if (description.handler) h = description.handler;
+      }
+      commands.set(name, { desc: desc || '', handler: h, builder: builder || (() => {}) });
+      return self;
+    },
+    async run(argv) {
+      const args = (argv || []).slice();
+      const first = args[0];
+
+      if (!first || first === '--help' || first === '-h' || first === 'help') {
+        console.log(usageStr || `jsql ${realPkg.version} — embedded SQL CLI`);
+        console.log('Usage: jsql <command> [options]');
+        if (commands.size) {
+          console.log('');
+          console.log('Commands:');
+          for (const [name, c] of commands) {
+            console.log(`  ${name.padEnd(12)} ${c.desc}`);
+          }
+        }
+        console.log('');
+        console.log('Note: optional dependency @vexify-org/yaggs is not installed; full argument parsing is unavailable.');
+        console.log('      Install it with `npm install @vexify-org/yaggs` to restore rich argument parsing.');
+        return;
+      }
+
+      if (first === '--version' || first === '-v' || first === 'version') {
+        console.log(realPkg.version);
+        return;
+      }
+
+      const cmd = commands.get(first);
+      if (!cmd) {
+        console.error(`Unknown command: ${first}`);
+        console.error('Run `jsql --help` for the list of commands.');
+        process.exitCode = 1;
+        return;
+      }
+
+      // 极简参数解析：--key value / --key=value / --flag，以及位置参数。
+      const parsed = { _: [] };
+      for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+          const eq = a.indexOf('=');
+          if (eq !== -1) {
+            parsed[a.slice(2, eq)] = a.slice(eq + 1);
+          } else {
+            const nxt = args[i + 1];
+            if (nxt !== undefined && !nxt.startsWith('-')) { parsed[a.slice(2)] = nxt; i++; }
+            else parsed[a.slice(2)] = true;
+          }
+        } else if (a.startsWith('-') && a.length > 1) {
+          const key = a.slice(1);
+          const nxt = args[i + 1];
+          if (nxt !== undefined && !nxt.startsWith('-')) { parsed[key] = nxt; i++; }
+          else parsed[key] = true;
+        } else {
+          parsed._.push(a);
+        }
+      }
+
+      if (cmd.handler) return cmd.handler(parsed);
+      console.error(`Command '${first}' has no handler.`);
+      process.exitCode = 1;
+    },
+    };
+    return self;
+  };
+}
+
+module.exports = { buildYaggsFallback };

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.5.17 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.22 — 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
+};