jsql-neo 6.0.0 → 6.0.2

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.0** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo)
+> **v6.0.1** — 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)
@@ -124,6 +124,7 @@ For the complete Chinese edition of every topic below, jump to the [中文版](#
 - [Migration Tools](#migration-tools)
 - [Storage & Performance](#storage--performance)
 - [Security](#security)
+- [Plugin System](#plugin-system)
 - [Errors](#errors)
 - [TypeScript](#typescript)
 - [Architecture](#architecture)
@@ -232,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.0
+node -e "console.log(require('jsql-neo/package.json').version)"   # 6.0.1
 ```
 
 ### 30-second demo
@@ -410,7 +411,7 @@ Auth failure returns the standard `Access denied for user 'x'@'...' (using passw
 
 The server answers the system probes ORMs and GUI tools run at connect time:
 
-- `SELECT VERSION()` → `8.0.0-jsql-neo`
+- `SELECT VERSION()` → `8.0.1-jsql-neo`
 - System variables: `@@version`, `@@version_comment`, …
 - `SHOW DATABASES / SHOW TABLES / SHOW COLUMNS / SHOW CREATE TABLE`
 - `information_schema.tables / columns / statistics`
@@ -1064,7 +1065,7 @@ SELECT AGE('2026-08-12', '2020-01-01');             -- '6 years 7 mons 11 days'
 **Conditional / null** — `IF(cond, a, b)`, `IIF`, `IFNULL(a, b)`, `COALESCE(...)`, `NULLIF`,
 `ISNULL`, `CASE WHEN ... THEN ... ELSE ... END` (search/simple form, works with aggregates).
 
-**System & misc** — `VERSION()` → `8.0.0-jsql-neo`, `DATABASE()`, `USER()`/`CURRENT_USER`,
+**System & misc** — `VERSION()` → `8.0.1-jsql-neo`, `DATABASE()`, `USER()`/`CURRENT_USER`,
 `LAST_INSERT_ID()`, `ROW_COUNT()`, `CAST`/`CONVERT`, `JSON_EXTRACT(doc, '$.path')`,
 `JSON_OBJECT`/`JSON_ARRAY`, `JSON_UNQUOTE`, `JSON_CONTAINS`, `JSON_SET/INSERT/REPLACE/REMOVE`,
 `UUID()`, `TYPEOF(x)`, `PRINT(x)`.
@@ -1091,15 +1092,21 @@ ORDER BY avg_sal DESC;
 
 ### Operators
 
-**Arithmetic** — `+ - * / % MOD DIV ^` (power, PG style).
+**Arithmetic** — `+ - * / %`，以及 `MOD` / `DIV` / `POWER()`。
 
 **Comparison** — `= <> != < <= > >=`, `IS NULL`, `IS TRUE/FALSE` (three-valued),
 `BETWEEN a AND b`, `IN (...)`, `LIKE`/`NOT LIKE`, `ILIKE` (case-insensitive),
-`RLIKE`/`REGEXP`, `~ ~* !~ !~*` (PG regex), `EXISTS`, `ANY`/`ALL`/`SOME`, `<=>` (NULL-safe).
+`RLIKE`/`REGEXP`, `EXISTS`, `= ANY` / `> ALL` / `SOME`.
 
-**Logic** — `AND OR NOT XOR` (short-circuit), MySQL aliases `&&` `||`.
+**Logic** — `AND OR NOT` (short-circuit).
 
-**Bitwise** — `& | ^ ~ << >>`.
+**Bitwise** — `& | ^ ~ << >>`（`^` 是按位异或，`~` 是按位取反）。
+
+> **运算符方言说明。** `^` 与 `~` 在 MySQL（位运算）和 PostgreSQL（`^` 为幂、
+> `~` 为正则匹配）中含义冲突，本实现统一采用 **MySQL 语义**：`^` = 按位异或、
+> `~` = 按位取反。需要幂运算请用 `POWER(x, n)`，需要正则请用 `REGEXP` / `~*`。
+> 因此 PG 风格的 `^`（幂）、`~ ~* !~ !~*`（正则）与 JSON 操作符
+> （`-> ->> #> #>> @> <@`）**暂不支持**。
 
 **JSON (PG style)** — `->` (JSON result), `->>` (text), `#>`, `#>>` (paths), `@>` `<@`
 (containment), `?` `?|` `?&` (key existence).
@@ -1457,7 +1464,7 @@ jsql mod --engine wasm        # switch engine (restart required)
 
 ```bash
 $ jsql version
-jsql-neo v6.0.0
+jsql-neo v6.0.1
 engine: native (napi) | wasm | js
 node: v22.0.0  platform: linux x64
 ```
@@ -1478,7 +1485,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.0`.
+The status bar shows: `db=<name> dialect=<d> mode=<tui|batch> ver=6.0.1`.
 
 ### Keyboard shortcuts
 
@@ -1753,6 +1760,105 @@ normalization on data dirs and import/export paths; Web UI db-name whitelist (no
 }
 ```
 
+## Plugin System
+
+JSQL-NEO ships with a unified plugin system that works across all three engine implementations:
+**Native** (`NativeJSQL`), **WASM** (`JSQL`), and **Pure JS** (`Database`). Full documentation
+is in [PLUGINS.md](./PLUGINS.md).
+
+### Quick start
+
+```js
+const { Database, Plugin } = require('jsql-neo');
+const db = new Database();
+
+db.use({
+  name: 'my-plugin',
+  install(db, ctx) {
+    db.myFlag = true;
+  },
+  hooks: {
+    beforeInsert(table, data) { /* modify data */ return data; },
+    afterInsert(table, data, ids) {},
+    beforeUpdate(table, id, data) { return true; },   // false = abort
+    afterUpdate(table, id, data, result) {},
+    beforeDelete(table, id) { return true; },
+    afterDelete(table, id, result) {},
+    beforeFind(table, query) { return true; },
+    afterFind(table, query, result) {},
+  },
+});
+```
+
+### Hooks reference (18 unified hooks)
+
+| Hook | Parameters | Return | Description |
+|---|---|---|---|
+| `beforeInsert` | `(table, data[])` | modified data / `false` to abort | pre-insert |
+| `afterInsert` | `(table, data[], ids)` | — | post-insert |
+| `beforeUpdate` | `(table, id, data)` | `true`/`false` | pre-update |
+| `afterUpdate` | `(table, id, data, result)` | — | post-update |
+| `beforeDelete` | `(table, id)` | `true`/`false` | pre-delete |
+| `afterDelete` | `(table, id, result)` | — | post-delete |
+| `beforeFind` | `(table, query)` | `true`/`false` | pre-query |
+| `afterFind` | `(table, query, result)` | — | post-query |
+| `beforeCreateTable` | `(name, schema)` | `true`/`false` | pre-DDL |
+| `afterCreateTable` | `(name, schema)` | — | post-DDL |
+| `beforeDropTable` | `(name)` | `true`/`false` | pre-drop |
+| `afterDropTable` | `(name)` | — | post-drop |
+| `beforeFlush` | `()` | `true`/`false` | pre-flush |
+| `afterFlush` | `()` | — | post-flush |
+| `beforeCount` | `(table)` | `true`/`false` | pre-count |
+| `afterCount` | `(table, count)` | — | post-count |
+| `onStart` | `()` | — | engine start |
+| `onStop` | `()` | — | engine stop |
+
+### Events
+
+| Event | Payload |
+|---|---|
+| `insert` | `{ table, count, ids }` |
+| `update` | `{ table, id, data }` |
+| `delete` | `{ table, ids }` |
+| `createTable` | `{ name, schema }` |
+| `dropTable` | `{ name }` |
+| `start` / `stop` | `{}` |
+
+### Plugin helper class
+
+```js
+const timestampPlugin = new Plugin('timestamp')
+  .on('beforeInsert', (table, data) => {
+    data.forEach(r => r.created_at = new Date().toISOString());
+    return data;
+  })
+  .onEvent((ev, payload) => console.log(ev))
+  .install((db, ctx) => {})
+  .build();
+
+db.use(timestampPlugin);
+```
+
+### Module system (CLI)
+
+```bash
+jsql mod add --address /path/mod.js     # register module
+jsql mod enable <name>                   # enable (auto-enables dependencies)
+jsql mod disable <name>                  # disable (cascades)
+jsql mod list | ls [--json]             # list
+```
+
+Modules persist to `~/.config/jsql/mod.config`. Circular dependencies are rejected;
+disabling cascades to dependents.
+
+> **插件没有沙箱，请只装可信来源的模块。** 两条装载路径都不做隔离：
+> - `db.use(plugin)` —— 直接把插件对象挂进核心，与核心同权；
+> - `jsql mod add <dir>` —— 模块文件走普通 `require()`，同样与核心同权，
+>   可访问 `fs` / `child_process` 等一切 Node API。
+>
+> 早期文档曾写"模块文件在 VM 沙箱中执行"，实际代码中不存在 vm 隔离，此处已更正。
+> 需要隔离时请在进程级解决（容器 / 子进程 / 单独的用户与权限）。
+
 ---
 
 ## TypeScript
@@ -2378,7 +2484,7 @@ createMysqlServer({
 
 支持常见系统查询，让 ORM 与 GUI 工具的初始化探测流程正常工作：
 
-- `SELECT VERSION()` → `8.0.0-jsql-neo`
+- `SELECT VERSION()` → `8.0.1-jsql-neo`
 - `SELECT @@version` / `@@version_comment` 等系统变量
 - `SHOW DATABASES` / `SHOW TABLES` / `SHOW COLUMNS FROM t` / `SHOW CREATE TABLE t`
 - `information_schema.tables` / `information_schema.columns` / `information_schema.statistics`
@@ -2410,7 +2516,7 @@ SELECT TABLE_NAME, TABLE_ROWS FROM information_schema.tables WHERE TABLE_SCHEMA
 
 | 函数 | 行为 |
 |---|---|
-| `VERSION()` | `8.0.0-jsql-neo` |
+| `VERSION()` | `8.0.1-jsql-neo` |
 | `NOW()` / `CURRENT_TIMESTAMP` | `YYYY-MM-DD HH:MM:SS`（UTC） |
 | `CONCAT(a, b, ...)` | 字符串拼接 |
 | `GROUP_CONCAT(x)` | 聚合拼接（逗号分隔） |
@@ -3104,26 +3210,28 @@ SELECT * FROM orders LIMIT 40 OFFSET 20;    -- 标准偏移语法
 | `BEGIN` / `START TRANSACTION` | 开启事务 |
 | `COMMIT` | 提交 |
 | `ROLLBACK` | 回滚 |
-| `SAVEPOINT sp` / `ROLLBACK TO SAVEPOINT sp` / `RELEASE SAVEPOINT sp` | 保存点 |
+| `SAVEPOINT sp` / `RELEASE SAVEPOINT sp` | 保存点（**仅登记**，无快照能力） |
+| `ROLLBACK TO SAVEPOINT sp` | **不支持**——会抛错，不会静默"假成功" |
 | 自动事务 | 无显式事务时单语句原子 |
 
 事务保证：
 
 - 读已提交（read committed）隔离级别的等价语义
 - 事务内修改对事务外不可见（提交前），提交后原子可见
-- 回滚撤销本事务全部修改（含保存点回滚）
+- 回滚撤销本事务全部修改
 - 支持跨表事务（引擎级提交日志）
 
 ```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;      -- 撤销 id=3 的修改
 COMMIT;
 ```
 
+> **`ROLLBACK TO SAVEPOINT` 目前不可用。** 引擎没有保存点/快照能力，无法只回退到某个
+> 保存点。这里刻意选择"抛错"而不是"静默成功"——假装回滚成功会让调用方误以为数据已还原。
+> 需要部分回滚时请用 `ROLLBACK` 放弃整个事务。
+
 #### 其他语句
 
 | 语句 | 说明 |
@@ -3245,7 +3353,7 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 
 | 函数 | 说明 | 示例 |
 |---|---|---|
-| `VERSION()` | 服务器版本 | `8.0.0-jsql-neo` |
+| `VERSION()` | 服务器版本 | `8.0.1-jsql-neo` |
 | `DATABASE()` | 当前库名 | `DATABASE()` |
 | `USER()` / `CURRENT_USER` | 当前用户 | `USER()` → `root` |
 | `LAST_INSERT_ID()` | 最近自增 ID | 配合 AUTO_INCREMENT 使用 |
@@ -4042,7 +4150,7 @@ Data dir: /root/.jsql-neo/data
 
 ```bash
 $ jsql version
-jsql-neo v6.0.0
+jsql-neo v6.0.1
 engine: native (napi) | wasm | js
 node: v22.0.0
 platform: linux x64
@@ -4711,7 +4819,7 @@ jsql-neo/
 ├── index.js                     # ★ 公共 API 出口
 ├── index.d.ts                   # TypeScript 声明
 ├── test/                        # 测试套件
-├── docs/                        # 文档（本文件即索引）
+├── PLUGINS.md                   # 插件与模块文档（与 README 同级，无 docs/ 目录）
 ├── src/rust/                    # Rust 引擎源码（native + wasm）
 ├── data/                        # 默认数据目录（运行时创建）
 └── package.json
@@ -4902,7 +5010,7 @@ npm run typecheck
 - `src/rust/`：Rust 引擎（native + wasm 同源）
 - `lib/`：Node 侧全部逻辑（协议/解析/TUI/兼容层）
 - `test/`：单元 + 集成测试
-- `docs/`：扩展文档
+- 扩展文档位于仓库根目录：`PLUGINS.md`（插件与模块）。本仓库**没有** `docs/` 目录。
 
 ---
 
@@ -5119,7 +5227,7 @@ Apache License
 
 *JSQL-NEO — One engine to rule them all. MySQL. PostgreSQL. MongoDB. Redis. SQL. TypeScript. The browser.*
 
-*文档版本：v6.0.0 · 最后更新：2026-09-26*
+*文档版本：v6.0.1 · 最后更新：2026-09-27*
 
 ---
 
@@ -6594,7 +6702,7 @@ FROM orders;
 #### 会话信息
 
 ```sql
-SELECT VERSION();                  -- '8.0.0-jsql-neo'
+SELECT VERSION();                  -- '8.0.1-jsql-neo'
 SELECT DATABASE();                 -- 'app'
 SELECT USER();                     -- 'root@localhost'
 SELECT CURRENT_USER;               -- 'root@localhost'
@@ -6889,7 +6997,7 @@ Usage: jsql version
 
 输出版本与环境信息：
 
-  jsql-neo v6.0.0
+  jsql-neo v6.0.1
   engine: native (napi) | wasm | js
   node: v22.0.0
   platform: linux x64
@@ -7545,7 +7653,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.*
 
-*文档版本：v5.4.0 · 共 19 个附录 · 最后更新：2026-08-12*
+*文档版本：v6.0.1 · 共 19 个附录 · 最后更新：2026-09-27*
 
 ---
 
@@ -8152,4 +8260,4 @@ npm test
 
 *JSQL-NEO — One engine to rule them all. MySQL. PostgreSQL. MongoDB. Redis. SQL. TypeScript. The browser.*
 
-*文档版本：v5.4.0 · 附录 A–Z · 全文 6000+ 行 · 最后更新：2026-08-12*
+*文档版本：v6.0.1 · 附录 A–Z · 全文 6000+ 行 · 最后更新：2026-09-27*

package/lib/pg_server.js

@@ -861,4 +861,10 @@ class PgServer {
   }
 }
 
-module.exports = { PgServer, PgConnection, buildRowDescription, buildDataRow, buildCommandComplete, buildErrorResponse, buildReadyForQuery, buildParameterStatus, buildBackendKeyData, buildParseComplete, buildBindComplete, buildCloseComplete, buildNoData, buildParameterDesc, TYPE_OIDS, pgTypeOid, pgFormatValue };
+// README 的 createXxxServer 工厂系列里，PG 这个之前漏了实现：
+// index.js 一直从本模块解构 createPgServer，实际拿到 undefined。
+function createPgServer(options) {
+  return new PgServer(options || {});
+}
+
+module.exports = { PgServer, createPgServer, PgConnection, buildRowDescription, buildDataRow, buildCommandComplete, buildErrorResponse, buildReadyForQuery, buildParameterStatus, buildBackendKeyData, buildParseComplete, buildBindComplete, buildCloseComplete, buildNoData, buildParameterDesc, TYPE_OIDS, pgTypeOid, pgFormatValue };

package/lib/redis_server.js

@@ -470,52 +470,81 @@ class RedisServer {
 
   /** 供多协议嗅探复用：把 socket 交给 Redis 处理，可携带已缓冲的首包 */
   _handleSocket(socket, existing = '') {
-    let buf = String(existing || '');
+    // 刻意不 setEncoding('utf8')：RESP 的 $N 是**字节**长度，
+    // 转成字符串再按字符切片会把多字节 UTF-8（中文等）截断。
+    let buf = Buffer.isBuffer(existing) ? existing : Buffer.from(String(existing || ''), 'utf8');
     this._authedSockets.set(socket, false);
-    socket.setEncoding('utf8');
-    socket.on('data', (chunk) => {
-      buf += chunk;
+
+    const drain = () => {
       for (;;) {
-        const msg = this._parse(buf);
+        let msg;
+        try {
+          msg = this._parse(buf);
+        } catch (e) {
+          // 协议错误：回复错误并丢弃缓冲，避免一直卡在同一段坏数据上
+          this._send(socket, (e instanceof Error) ? e : new Error('ERR Protocol error'));
+          buf = Buffer.alloc(0);
+          return;
+        }
         if (!msg) break;
         buf = buf.slice(msg.consumed);
+        if (msg.ignore) continue;
         this._handle(socket, msg.cmd, msg.args);
       }
+    };
+
+    socket.on('data', (chunk) => {
+      buf = Buffer.concat([buf, Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8')]);
+      drain();
     });
     socket.on('error', () => {});
-    for (;;) {
-      const msg = this._parse(buf);
-      if (!msg) break;
-      buf = buf.slice(msg.consumed);
-      this._handle(socket, msg.cmd, msg.args);
-    }
+    drain();
   }
 
+  /**
+   * 解析一条 RESP2 请求，返回 { consumed, cmd, args } 或 null（数据不完整）。
+   * buf 是 Buffer —— 所有长度计算都按**字节**进行。
+   */
   _parse(buf) {
-    if (buf[0] !== '*') {
-      const i = buf.indexOf('\r\n');
+    if (!buf || buf.length === 0) return null;
+    const crlf = (from) => buf.indexOf('\r\n', from, 'utf8');
+
+    // 非 '*' 开头：inline 命令（telnet / nc 手工输入）
+    if (buf[0] !== 0x2a) {
+      const i = crlf(0);
       if (i < 0) return null;
-      const cmd = buf.slice(0, i).trim().split(/\s+/);
-      if (!cmd.length) return null;
-      return { consumed: i + 2, cmd: cmd.map(c => c.toUpperCase()), args: cmd.slice(1) };
+      const line = buf.slice(0, i).toString('utf8').trim();
+      if (!line) return { consumed: i + 2, ignore: true };
+      const parts = line.split(/\s+/);
+      // 之前这里返回的是数组（cmd.map(...)），导致 switch(cmd) 永远匹配不上，
+      // inline 输入一律被当成 unknown command。必须是字符串。
+      const cmd = parts[0].toUpperCase();
+      return { consumed: i + 2, cmd, args: parts.slice(1) };
     }
-    const i = buf.indexOf('\r\n');
+
+    const i = crlf(0);
     if (i < 0) return null;
-    const n = parseInt(buf.slice(1, i), 10);
-    if (isNaN(n)) throw new Error('ERR Protocol error');
+    const n = parseInt(buf.slice(1, i).toString('utf8'), 10);
+    if (isNaN(n)) throw new Error('ERR Protocol error: invalid multibulk length');
+    // *0（空命令）与 *-1（null 数组）此前会走到 parts[0].toUpperCase() 崩溃
+    if (n <= 0) return { consumed: i + 2, ignore: true };
+
     let off = i + 2;
     const parts = [];
     for (let k = 0; k < n; k++) {
-      if (buf[off] !== '$') throw new Error('ERR Protocol error: expected bulk string');
-      const j = buf.indexOf('\r\n', off);
+      if (buf.length <= off) return null;
+      if (buf[off] !== 0x24) throw new Error('ERR Protocol error: expected bulk string');   // '$'
+      const j = crlf(off);
       if (j < 0) return null;
-      const len = parseInt(buf.slice(off + 1, j), 10);
-      if (isNaN(len)) throw new Error('ERR Protocol error');
-      if (buf.length < j + 2 + len + 2) return null;
-      parts.push(buf.slice(j + 2, j + 2 + len));
-      off = j + 2 + len + 2;
+      const len = parseInt(buf.slice(off + 1, j).toString('utf8'), 10);
+      if (isNaN(len)) throw new Error('ERR Protocol error: invalid bulk length');
+      const start = j + 2;
+      if (len === -1) { parts.push(null); off = start; continue; }   // $-1 null bulk
+      if (buf.length < start + len + 2) return null;                 // 按字节判断
+      parts.push(buf.slice(start, start + len).toString('utf8'));
+      off = start + len + 2;
     }
-    const cmd = parts[0].toUpperCase();
+    const cmd = String(parts[0] || '').toUpperCase();
     return { consumed: off, cmd, args: parts.slice(1) };
   }
 
@@ -550,7 +579,8 @@ class RedisServer {
     } else if (typeof val === 'number') {
       out = ':' + val + '\r\n';
     } else if (Array.isArray(val)) {
-      out = '*' + val.length + '\r\n' + val.map(v => '$' + String(v).length + '\r\n' + v + '\r\n').join('');
+      // 长度用字节数，不能用 String.length —— 否则中文等多字节值会让客户端解帧错位
+      out = '*' + val.length + '\r\n' + val.map(v => '$' + Buffer.byteLength(String(v), 'utf8') + '\r\n' + v + '\r\n').join('');
     } else if (typeof val === 'string') {
       if (val === 'OK' || val === 'PONG') {
         out = '+' + val + '\r\n';