jsql-neo 5.4.2 → 6.0.0-beta2

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.**
 
-> **v5.4.0** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo)
+> **v5.6.0** — 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)
@@ -232,7 +232,7 @@ npm install && npm run build                 # option 3: from source
 Verify:
 
 ```bash
-node -e "console.log(require('jsql-neo/package.json').version)"   # 5.4.0
+node -e "console.log(require('jsql-neo/package.json').version)"   # 5.6.0
 ```
 
 ### 30-second demo
@@ -835,6 +835,7 @@ CREATE TABLE IF NOT EXISTS orders (
 **SELECT grammar**
 
 ```sql
+WITH [RECURSIVE] cte_name [(col, ...)] AS (SELECT ...)[, ...]   -- CTE，见下节
 SELECT [DISTINCT] select_list
 FROM table_reference
 [JOIN table_reference ON condition]
@@ -843,9 +844,69 @@ FROM table_reference
 [HAVING condition]
 [ORDER BY column [ASC|DESC] [, ...]]
 [LIMIT { count | offset, count | count OFFSET offset }]
+[UNION [ALL|DISTINCT] SELECT ...]
+[INTERSECT [ALL|DISTINCT] SELECT ...]
+[EXCEPT [ALL|DISTINCT] SELECT ...]
 [RETURNING ...]
 ```
 
+**表达式与函数** — `CAST(expr AS type)`（INTEGER / FLOAT / DECIMAL / BOOLEAN / TEXT 等，
+支持 `VARCHAR(10)` 带长度写法）；`LIKE` / `ILIKE`（大小写不敏感）/ `REGEXP` / `RLIKE`；
+`= ANY (SELECT ...)` / `> ALL (SELECT ...)`（含 `SOME`）；
+`ORDER BY <表达式>`（如 `ORDER BY sal * 12 DESC`、`ORDER BY UPPER(name)`）。
+
+```sql
+SELECT CAST(sal AS TEXT) AS s, CAST(ratio AS FLOAT) AS r FROM emp;
+SELECT name FROM users WHERE name ILIKE 'a%';            -- 大小写不敏感
+SELECT name FROM emp WHERE sal > ALL (SELECT sal FROM emp WHERE dept = 'ops');
+SELECT name FROM emp ORDER BY sal * 12 DESC;
+SELECT name FROM emp FETCH FIRST 10 ROWS ONLY;            -- 等价于 LIMIT 10
+```
+
+**分组汇总** — `GROUP BY ... WITH ROLLUP` 会在结果末尾追加一行汇总
+（分组列置 `NULL`，聚合列覆盖全部行）：
+
+```sql
+SELECT dept, SUM(sal) AS total FROM emp GROUP BY dept WITH ROLLUP;
+-- [['eng', 300], ['ops', 300], [null, 600]]
+```
+
+**写入冲突处理** — 四种写法统一处理主键/唯一键冲突：
+
+| 写法 | 冲突时行为 | 返回字段 |
+|---|---|---|
+| 默认 | 抛 `ER_DUP_ENTRY` | — |
+| `INSERT IGNORE` | 跳过冲突行 | `duplicateSkipped` |
+| `ON CONFLICT (col) DO NOTHING` | 跳过冲突行 | `duplicateSkipped` |
+| `ON DUPLICATE KEY UPDATE ...` / `ON CONFLICT (col) DO UPDATE SET ...` | 更新已有行 | `duplicateUpdated` |
+| `REPLACE INTO` | 删除旧行后插入新行 | — |
+
+**`RETURNING`** — `INSERT` / `UPDATE` / `DELETE` 均可带 `RETURNING *` 或 `RETURNING col, ...`，
+结果在返回对象的 `returning: { columns, rows }` 上（同时填充 `columns` / `rows`）：
+
+```sql
+INSERT INTO emp (name, sal) VALUES ('z', 100) RETURNING id, name;
+UPDATE emp SET sal = 555 WHERE id = 1 RETURNING id, sal;
+DELETE FROM emp WHERE id = 1 RETURNING *;
+```
+
+**视图** — `CREATE [OR REPLACE] VIEW name [(cols)] AS SELECT ...` / `DROP VIEW [IF EXISTS] name`。
+视图定义保存在 `engine._views`，查询时内联为 FROM 子查询（支持视图引用视图，嵌套上限 16 层）：
+
+```sql
+CREATE VIEW v_eng AS SELECT * FROM emp WHERE dept = 'eng';
+SELECT name FROM v_eng;
+CREATE OR REPLACE VIEW v_eng AS SELECT * FROM emp;
+DROP VIEW v_eng;
+```
+
+**`EXPLAIN`** — `EXPLAIN [ANALYZE] <statement>` 输出 `step` / `detail` 两列的计划结构
+（扫描 / 连接 / 过滤 / 聚合 / 排序 / 限制）。**没有代价模型**，只展示计划形态，不预测行数或耗时。
+
+```sql
+EXPLAIN SELECT name FROM emp WHERE sal > 50;
+```
+
 **JOINs** — `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL OUTER JOIN`, `CROSS JOIN`,
 implicit `FROM a, b WHERE`, self-joins, multi-table chains.
 
@@ -866,21 +927,94 @@ FROM (SELECT dept FROM emp WHERE salary > 5000) t
 GROUP BY t.dept;
 ```
 
-**Transactions** — `BEGIN` / `START TRANSACTION`, `COMMIT`, `ROLLBACK`,
-`SAVEPOINT sp` / `ROLLBACK TO SAVEPOINT` / `RELEASE SAVEPOINT`. Read-committed-equivalent
-isolation; per-statement atomicity without explicit transactions; cross-table transactions;
-rolled-back changes are invisible to other connections until commit.
+**CTE（公用表表达式）** — `WITH [RECURSIVE] name [(cols)] AS (SELECT ...)`，
+可声明多个，后面的 CTE 可以引用前面的。执行层把 CTE 内联为 `FROM` 子查询，
+不需要引擎侧临时表。
+
+```sql
+WITH engineers AS (
+  SELECT * FROM emp WHERE dept = 'eng'
+)
+SELECT name, salary FROM engineers WHERE salary > 8000;
+
+-- 多个 CTE，后者引用前者
+WITH all_emp AS (SELECT * FROM emp),
+     high    AS (SELECT * FROM all_emp WHERE salary > 8000)
+SELECT dept, COUNT(*) AS n FROM high GROUP BY dept;
+
+-- 显式列名清单
+WITH t (who, howmuch) AS (SELECT name, salary FROM emp)
+SELECT who FROM t;
+
+-- CTE 也可接 INSERT / UPDATE / DELETE
+WITH src AS (SELECT * FROM emp WHERE dept = 'eng')
+INSERT INTO eng_backup SELECT * FROM src;
+```
+
+**窗口函数** — `function() OVER ( [PARTITION BY ...] [ORDER BY ...] [frame] )`。
+在 `WHERE` / `GROUP BY` / `HAVING` 之后、`DISTINCT` / `ORDER BY` / `LIMIT` 之前求值，
+符合 SQL 标准求值顺序。窗口聚合**不会**把结果塌缩成一行。
+
+| 函数 | 说明 |
+|---|---|
+| `ROW_NUMBER()` | 分区内连续行号 |
+| `RANK()` / `DENSE_RANK()` | 排名（并列时 `RANK` 跳号、`DENSE_RANK` 不跳号） |
+| `NTILE(n)` | 把分区切成 n 个桶 |
+| `LAG(expr[, n[, default]])` / `LEAD(...)` | 取分区内前/后第 n 行的值 |
+| `FIRST_VALUE(expr)` / `LAST_VALUE(expr)` | 帧内首/末行的值 |
+| `SUM/AVG/MIN/MAX/COUNT(...) OVER (...)` | 窗口聚合 |
+
+```sql
+SELECT name, dept, salary,
+       ROW_NUMBER() OVER (PARTITION BY dept ORDER BY salary DESC) AS rn,
+       RANK()       OVER (ORDER BY salary DESC)                   AS rk,
+       SUM(salary)  OVER (PARTITION BY dept)                      AS dept_total,
+       LAG(salary)  OVER (PARTITION BY dept ORDER BY salary)      AS prev
+FROM emp;
+
+-- 窗口帧
+SELECT name,
+       AVG(salary) OVER (ORDER BY salary
+                         ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS moving_avg
+FROM emp;
+```
+
+**集合运算符** — `UNION [ALL|DISTINCT]`、`INTERSECT [ALL|DISTINCT]`、`EXCEPT [ALL|DISTINCT]`。
+三者默认都是 `DISTINCT`；`UNION ALL` 保留重复行。
+
+```sql
+SELECT dept FROM emp WHERE salary > 5000
+INTERSECT
+SELECT dept FROM emp WHERE salary < 20000;
+
+SELECT dept FROM emp
+EXCEPT
+SELECT dept FROM emp WHERE salary < 5000;
+```
+
+**`EXISTS` / `NOT EXISTS`** — 支持**相关子查询**（逐行求值，外层行的列可在子查询中引用）：
+
+```sql
+SELECT name FROM emp e
+WHERE EXISTS (SELECT 1 FROM orders o WHERE o.emp_id = e.id AND o.amount > 1000);
+```
+
+**Transactions** — `BEGIN` / `START TRANSACTION`, `COMMIT`, `ROLLBACK`.
+Read-committed-equivalent isolation; per-statement atomicity without explicit transactions;
+cross-table transactions; rolled-back changes are invisible to other connections until commit.
 
 ```sql
 BEGIN;
 UPDATE accounts SET balance = balance - 100 WHERE id = 1;
 UPDATE accounts SET balance = balance + 100 WHERE id = 2;
-SAVEPOINT sp1;
-UPDATE accounts SET balance = balance - 100 WHERE id = 3;
-ROLLBACK TO SAVEPOINT sp1;
 COMMIT;
 ```
 
+> **SAVEPOINT — 部分支持。** `SAVEPOINT name` 与 `RELEASE SAVEPOINT name` 可以解析并登记，
+> 但 **`ROLLBACK TO SAVEPOINT` 会抛出明确错误**：引擎没有保存点/快照能力，
+> 无法只回退到某个保存点。用 `ROLLBACK` 回滚整个事务。
+> 这里刻意选择"报错"而不是"静默成功"——假装回滚成功会让调用方误以为数据已还原。
+
 **Other** — `SHOW DATABASES/TABLES/COLUMNS/CREATE TABLE`, `DESCRIBE t`, `USE db`,
 `EXPLAIN SELECT`, `SET SESSION x = y`, no-table queries (`SELECT VERSION()`), SQLite-style `PRAGMA`.
 
@@ -1141,6 +1275,56 @@ Result matrix: SELECT → `rows`; INSERT → `affectedRows` + `insertId`; UPDATE
 `affectedRows`; DDL/txn → `message`. Params: positional `?`, named `:name`, or object maps.
 Multi-statement supported; `SQLExecutor` class runs batched SQL from a string/stream.
 
+#### 参数绑定：两种方式
+
+```js
+// 1) 数组入参 —— 执行前用 applyParams 内联替换（转义安全，默认路径）
+await executeSQL(db, 'SELECT * FROM emp WHERE salary > ?', [5000]);
+
+// 2) 原生 ? 占位符 —— 解析成 AST 节点，在执行期绑定（5.6.0+）
+await executeSQL(db, 'SELECT * FROM emp WHERE salary > ?', { params: [5000] });
+
+// 支持顺序 ? 、编号 ?1 与标识符占位 ??
+await executeSQL(db, 'SELECT * FROM emp WHERE dept = ?1 OR salary > ?2', { params: ['eng', 5000] });
+```
+
+### AST access & rewrite
+
+`parseSQL()` 返回普通对象树。5.6.0 起提供 `lib/ast.js`（同时从 `lib/sql.js` 导出 `AST`、`walk`、
+`transform`、`visit`）用于遍历、查找与改写这棵树，无需了解每种节点类型。
+
+```js
+const { parseSQL, AST } = require('jsql-neo');
+
+const ast = parseSQL('SELECT name, salary FROM emp WHERE salary > 100 ORDER BY salary DESC');
+
+AST.tables(ast);    // ['emp']
+AST.columns(ast);   // ['name', 'salary']
+
+// 遍历（返回 false 可跳过子树）
+AST.walk(ast, (node, parent, key) => { console.log(node.type); });
+
+// 查找 / 收集
+AST.find(ast, n => n.type === 'compare');
+AST.collect(ast, n => n.type === 'column');
+
+// 不可变改写（返回新树，原 AST 不变）
+const renamed = AST.transform(ast, (node) => {
+  if (node && node.type === 'column' && node.name === 'name') return { ...node, name: 'NAME' };
+});
+
+// 原地改写
+AST.rewrite(ast, (node) => {
+  if (node && node.type === 'value' && node.value === 100) return { ...node, value: 200 };
+});
+
+// 按节点类型分派的访问器（visitSelect / visitColumn / visitCompare …）
+class Upper extends AST.StatementVisitor {
+  visitColumn(node) { node.name = String(node.name).toUpperCase(); }
+}
+new Upper().run(ast);
+```
+
 ### Events & hooks
 
 ```js
@@ -1273,7 +1457,7 @@ jsql mod --engine wasm        # switch engine (restart required)
 
 ```bash
 $ jsql version
-jsql-neo v5.4.0
+jsql-neo v5.6.0
 engine: native (napi) | wasm | js
 node: v22.0.0  platform: linux x64
 ```
@@ -1294,7 +1478,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=5.4.0`.
+The status bar shows: `db=<name> dialect=<d> mode=<tui|batch> ver=5.6.0`.
 
 ### Keyboard shortcuts
 
@@ -3858,7 +4042,7 @@ Data dir: /root/.jsql-neo/data
 
 ```bash
 $ jsql version
-jsql-neo v5.4.0
+jsql-neo v5.6.0
 engine: native (napi) | wasm | js
 node: v22.0.0
 platform: linux x64
@@ -4935,7 +5119,7 @@ Apache License
 
 *JSQL-NEO — One engine to rule them all. MySQL. PostgreSQL. MongoDB. Redis. SQL. TypeScript. The browser.*
 
-*文档版本：v5.4.0 · 最后更新：2026-08-12*
+*文档版本：v5.6.0 · 最后更新：2026-08-12*
 
 ---
 
@@ -6705,7 +6889,7 @@ Usage: jsql version
 
 输出版本与环境信息：
 
-  jsql-neo v5.4.0
+  jsql-neo v5.6.0
   engine: native (napi) | wasm | js
   node: v22.0.0
   platform: linux x64

package/index.d.ts

@@ -92,6 +92,7 @@ declare namespace JSQLNeo {
     stop(): Promise<void>;
     flush(): Promise<void>;
     createTable(name: string, schema: Schema): Promise<unknown>;
+    addColumn(table: string, name: string, def: string | FieldDef): Promise<unknown>;
     dropTable(name: string): Promise<unknown>;
     insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<unknown>;
     insertMany(table: string, data: Record<string, unknown>[]): Promise<unknown>;
@@ -260,6 +261,32 @@ declare namespace JSQLNeo {
     safety?: boolean;
     maxStatements?: number;
     session?: Record<string, unknown>;
+    /** 5.5.0+：原生 `?` 占位符绑定值（与 applyParams 的数组入参二选一） */
+    params?: unknown[];
+  }
+
+  /** AST 节点：带字符串 type 的普通对象树 */
+  export interface ASTNode {
+    type: string;
+    [key: string]: unknown;
+  }
+
+  /** 5.5.0+：AST 访问与改写 */
+  export namespace AST {
+    function walk(ast: unknown, visitor: (node: ASTNode, parent?: unknown, key?: string) => void | false, opts?: { post?: (node: ASTNode) => void }): unknown;
+    function collect(ast: unknown, predicate: (node: ASTNode) => boolean): ASTNode[];
+    function find(ast: unknown, predicate: (node: ASTNode) => boolean): ASTNode | null;
+    function transform(ast: unknown, fn: (node: unknown) => unknown): unknown;
+    function rewrite(ast: unknown, fn: (node: unknown) => unknown): unknown;
+    function tables(ast: unknown): string[];
+    function columns(ast: unknown): string[];
+    function isNode(value: unknown): boolean;
+    function cloneNode(node: unknown): unknown;
+    class StatementVisitor {
+      run(ast: unknown): unknown;
+      visitDefault?(node: ASTNode): void;
+      [key: string]: unknown;
+    }
   }
 
   export function executeSQL(engine: unknown, sql: string, paramsOrOpts?: unknown[] | SQLOptions, opts?: SQLOptions): Promise<SQLResult>;
@@ -268,6 +295,8 @@ declare namespace JSQLNeo {
   export function applyParams(sql: string, values: unknown[]): string;
   export function escapeValue(value: unknown): string;
   export function escapeId(value: string): string;
+  export function walk(ast: unknown, visitor: (node: ASTNode) => void | false): unknown;
+  export function transform(ast: unknown, fn: (node: unknown) => unknown): unknown;
 
   export interface DatabaseOptions {
     dataDir?: string;

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v5.1.2 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.0.0-beta1 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');
@@ -13,7 +13,8 @@
 
 const WasmClient = require('./lib/wasm_client');
 const NativeClient = require('./lib/native_client');
-const { Plugin } = require('./lib/plugin');
+const { Plugin, definePlugin, HOOKS } = require('./lib/plugin');
+const plugins = require('./lib/plugins');
 const { ModuleManager } = require('./lib/mod');
 const sql = require('./lib/sql');
 const { Datastore } = require('./lib/nedb_compat');
@@ -71,6 +72,9 @@ module.exports = {
     BTree: require('./lib/btree'),
     Cache: require('./lib/cache'),
     Plugin,
+    definePlugin,
+    HOOKS,
+    plugins,
     ModuleManager,
     JSQL_Error: require('./lib/errors').JSQL_Error,
     ErrorCodes: require('./lib/errors').ErrorCodes,
@@ -80,6 +84,12 @@ module.exports = {
     SQL: sql,
     executeSQL: sql.executeSQL,
     parseSQL: sql.parseSQL,
+    // AST 访问与改写（5.5.0+）
+    AST: sql.AST,
+    walk: sql.walk,
+    transform: sql.transform,
+    tokenize: sql.tokenize,
+    splitStatements: sql.splitStatements,
     Datastore,
     createConnection: mysqlCompat.createConnection,
     createPool: mysqlCompat.createPool,

package/lib/ast.js

@@ -0,0 +1,214 @@
+/**
+ * lib/ast.js — JSQL-NEO AST 访问与改写
+ *
+ * parseSQL() 返回的是普通 JS 对象树。本模块提供在不了解每种节点类型的
+ * 前提下遍历 / 查找 / 改写这棵树的能力：
+ *
+ *   walk(ast, visitor[, opts])   深度优先遍历（前序 + 可选后序）
+ *   collect(ast, predicate)      收集所有满足条件的节点
+ *   find(ast, predicate)         返回第一个满足条件的节点
+ *   transform(ast, fn)           不可变改写，返回新树
+ *   rewrite(ast, fn)             原地改写
+ *   tables(ast)                  列出语句引用的所有表名
+ *   columns(ast)                 列出语句引用的所有列名
+ *   StatementVisitor             基类，按节点类型分派 visitXxx 方法
+ *
+ * 设计约定：
+ *  - 「节点」指带字符串 type 字段的对象；但遍历会穿透所有普通对象与数组，
+ *    因为 SELECT 列描述符（{ expr, scalar, alias }）这类中间结构没有 type。
+ *  - seen 集合防止共享子树被重复访问或死循环。
+ *  - transform 返回新树、不改入参；rewrite 原地修改。
+ */
+
+const SKIP_KEYS = new Set(['pos']);
+
+function isNode(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) && typeof v.type === 'string';
+}
+
+function childKeys(obj) {
+  const out = [];
+  for (const k of Object.keys(obj)) if (!SKIP_KEYS.has(k)) out.push(k);
+  return out;
+}
+
+/** 深度优先遍历。visitor(node, parent, key) 返回 false 可跳过该子树。 */
+function walk(ast, visitor, opts = {}) {
+  const seen = new Set();
+  const post = opts.post || null;
+  const fn = typeof visitor === 'function' ? visitor : null;
+
+  const visit = (value, parent, key) => {
+    if (value === null || typeof value !== 'object') return;
+    if (seen.has(value)) return;
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, parent, key);
+      return;
+    }
+
+    const node = isNode(value);
+    let descend = true;
+    if (node && fn) {
+      const r = fn(value, parent, key);
+      if (r === false) descend = false;
+    }
+    if (descend) {
+      for (const k of childKeys(value)) visit(value[k], value, k);
+    }
+    if (node && post) post(value, parent, key);
+  };
+
+  if (Array.isArray(ast)) { for (const n of ast) visit(n, null, null); }
+  else visit(ast, null, null);
+  return ast;
+}
+
+/** 收集所有满足 predicate 的节点。 */
+function collect(ast, predicate) {
+  const out = [];
+  walk(ast, (node) => { if (predicate(node)) out.push(node); });
+  return out;
+}
+
+/** 返回第一个满足 predicate 的节点，找不到返回 null。 */
+function find(ast, predicate) {
+  let hit = null;
+  walk(ast, (node) => {
+    if (hit) return false;
+    if (predicate(node)) { hit = node; return false; }
+  });
+  return hit;
+}
+
+function cloneValue(v, seen) {
+  if (v === null || typeof v !== 'object') return v;
+  if (seen.has(v)) return v;
+  seen.add(v);
+  if (Array.isArray(v)) return v.map(x => cloneValue(x, seen));
+  const out = {};
+  for (const k of Object.keys(v)) out[k] = cloneValue(v[k], seen);
+  return out;
+}
+
+function cloneNode(node) { return cloneValue(node, new Set()); }
+
+/**
+ * 不可变改写：对每个节点调用 fn(node)，返回值非 undefined 时替换该节点。
+ * 返回新树，入参保持不变。
+ */
+function transform(ast, fn) {
+  const seen = new Set();
+
+  const visit = (value) => {
+    if (value === null || typeof value !== 'object') {
+      const r = fn(value);
+      return r === undefined ? value : r;
+    }
+    if (seen.has(value)) return value;
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+      const arr = value.map(visit);
+      const rep = fn(arr);
+      return rep === undefined ? arr : rep;
+    }
+
+    const out = {};
+    for (const k of Object.keys(value)) out[k] = visit(value[k]);
+
+    if (isNode(value)) {
+      const rep = fn(out);
+      return rep === undefined ? out : rep;
+    }
+    return out;
+  };
+
+  return visit(ast);
+}
+
+/** 原地改写：fn(node) 返回值非 undefined 时替换原节点。 */
+function rewrite(ast, fn) {
+  const seen = new Set();
+
+  const visit = (value, parent, key, index) => {
+    if (value === null || typeof value !== 'object') {
+      if (parent && key) {
+        const r = fn(value);
+        if (r !== undefined) {
+          if (index === undefined) parent[key] = r; else parent[key][index] = r;
+        }
+      }
+      return;
+    }
+    if (seen.has(value)) return;
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) visit(value[i], parent, key, i);
+      return;
+    }
+
+    for (const k of childKeys(value)) visit(value[k], value, k);
+
+    if (isNode(value) && parent && key) {
+      const r = fn(value);
+      if (r !== undefined) {
+        if (index === undefined) parent[key] = r; else parent[key][index] = r;
+      }
+    }
+  };
+
+  visit(ast, null, null);
+  return ast;
+}
+
+/** 语句引用的所有表名（含 JOIN / 子查询）。 */
+function tables(ast) {
+  const out = new Set();
+  walk(ast, (node) => {
+    if (node.type === 'select' && node.from) {
+      for (const t of (node.from.tables || [])) if (t && t.table) out.add(t.table);
+      for (const j of (node.from.joins || [])) if (j.item && j.item.table) out.add(j.item.table);
+    }
+    if (node.type === 'insert' || node.type === 'update' || node.type === 'delete' ||
+        node.type === 'createTable' || node.type === 'dropTable' || node.type === 'truncate') {
+      if (node.name) out.add(node.name);
+      if (node.table) out.add(node.table);
+    }
+  });
+  return [...out];
+}
+
+/** 语句引用的所有列名（去重）。 */
+function columns(ast) {
+  const out = new Set();
+  walk(ast, (node) => {
+    if (node.type === 'column' && node.name) out.add(node.name);
+  });
+  return [...out];
+}
+
+/**
+ * 按节点类型分派的访问器基类。
+ * 子类定义 visitSelect(node) / visitCompare(node) … 即可；未定义类型走 visitDefault。
+ *
+ *   class MyVisitor extends StatementVisitor {
+ *     visitColumn(node) { node.name = String(node.name).toLowerCase(); }
+ *   }
+ *   new MyVisitor().run(ast);
+ */
+class StatementVisitor {
+  run(ast) {
+    walk(ast, (node) => {
+      const camel = String(node.type).replace(/(^|[-_])([a-z])/g, (_, __, ch) => ch.toUpperCase());
+      const method = this['visit' + camel];
+      if (typeof method === 'function') method.call(this, node);
+      else if (typeof this.visitDefault === 'function') this.visitDefault(node);
+    });
+    return ast;
+  }
+}
+
+module.exports = { walk, collect, find, transform, rewrite, tables, columns, StatementVisitor, isNode, cloneNode };