jsql-neo 6.0.0 → 6.0.4

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`
@@ -834,7 +835,7 @@ CREATE TABLE IF NOT EXISTS orders (
 
 **SELECT grammar**
 
-```sql
+```text
 WITH [RECURSIVE] cte_name [(col, ...)] AS (SELECT ...)[, ...]   -- CTE，见下节
 SELECT [DISTINCT] select_list
 FROM table_reference
@@ -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,28 +1092,34 @@ 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** — `& | ^ ~ << >>`（`^` 是按位异或，`~` 是按位取反）。
 
-**JSON (PG style)** — `->` (JSON result), `->>` (text), `#>`, `#>>` (paths), `@>` `<@`
-(containment), `?` `?|` `?&` (key existence).
+> **运算符方言说明。** `^` 与 `~` 在 MySQL 与 PostgreSQL 中含义冲突，本实现按上下文区分：
+> - `^` 统一为**按位异或**（MySQL 语义）；幂运算请用 `POWER(x, n)`。
+> - `~` 在**单目**位置是按位取反（MySQL），在**双目**位置是正则匹配（PG），
+>   另有 `~*`（不敏感）、`!~`、`!~*`。
+> - 需要正则时也可用 `REGEXP` / `RLIKE`；PG 的 `^`（幂）**暂不支持**。
+
+**JSON (PG style)** — `->` / `->>`（取字段）、`#>` / `#>>`（路径取值）、`@>` / `<@`（包含）、
+`?` / `?|` / `?&`（键存在），可链式（`meta->'addr'->>'city'`）。
 
 ### LIKE / ILIKE / regex
 
-- `%` any length, `_` one char, `\` escape (`ESCAPE` clause)
-- `ILIKE` = LIKE, case-insensitive
-- `REGEXP`/`RLIKE`/`~` use the JS RegExp engine; flags `i/m/s`
+- `%` any length, `_` one char；`ESCAPE '!'` 可自定义转义符（默认 `\`）
+- `ILIKE` = LIKE，大小写不敏感
+- `REGEXP` / `RLIKE` 使用 JS RegExp 引擎；flags `i/m/s`
 
 ```sql
 SELECT * FROM users
-WHERE email ~* '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
+WHERE email REGEXP '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
 ```
 
 ### Indexes & constraints
@@ -1263,16 +1270,17 @@ const result = await executeSQL(db, sql, params);
 ```js
 {
   columns: ['id', 'name', 'age'],
-  columnTypes: ['INTEGER', 'VARCHAR', 'INTEGER'],
+  columnTypes: ['INT', 'VARCHAR(255)', 'INT'],
   rows: [[1, 'Alice', 30]],
-  rowCount: 2, affectedRows: 0, insertId: 1,
-  message: '2 rows selected', command: 'SELECT',
+  rowCount: 1, affectedRows: 0,
+  message: '1 row selected', command: 'SELECT',
   durationMs: 0.42, warnings: [],
 }
 ```
 
-Result matrix: SELECT → `rows`; INSERT → `affectedRows` + `insertId`; UPDATE/DELETE →
-`affectedRows`; DDL/txn → `message`. Params: positional `?`, named `:name`, or object maps.
+Result matrix: SELECT → `rows`（另有 `columnTypes`、`rowCount`、`command`、`message`、
+`durationMs`、`warnings`）；INSERT → `affectedRows` + `insertId`（另有 `ids`）；
+UPDATE/DELETE → `affectedRows`；DDL/txn → `message`。 Params: positional `?`, named `:name`, or object maps.
 Multi-statement supported; `SQLExecutor` class runs batched SQL from a string/stream.
 
 #### 参数绑定：两种方式
@@ -1457,7 +1465,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 +1486,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 +1761,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 +2485,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 +2517,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)` | 聚合拼接（逗号分隔） |
@@ -3031,7 +3138,7 @@ DELETE FROM orders WHERE status = 'cancelled' LIMIT 100;
 
 #### 查询语法 SELECT
 
-```sql
+```text
 SELECT [DISTINCT] select_list
 FROM table_reference
 [JOIN table_reference ON condition]
@@ -3104,26 +3211,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 +3354,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 使用 |
@@ -3295,7 +3404,6 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 | `+` `-` `*` `/` | 四则 | `(a + b) * 2` |
 | `%` / `MOD` | 取模 | `a % 3` |
 | `DIV` | 整数除法（MySQL） | `7 DIV 2` → 3 |
-| `^` | 幂（PG） | `2 ^ 10` → 1024 |
 
 #### 比较运算符
 
@@ -3337,10 +3445,15 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 |---|---|---|
 | `->` | 取 JSON 字段（返回 JSON） | `meta->'name'` |
 | `->>` | 取 JSON 字段（返回文本） | `meta->>'name'` |
-| `#>`, `#>>` | 路径访问 | `meta#>>'{a,b}'` |
+| `#>` | 路径取值（返回 JSON） | `meta#>'{addr,city}'` |
+| `#>>` | 路径取值（返回文本） | `meta#>>'{addr,city}'` |
 | `@>` | 包含 | `meta @> '{"plan":"pro"}'` |
-| `<@` | 被包含 | `'{"a":1}'::jsonb <@ meta` |
-| `?` / `?|` / `?&` | 键存在 | `meta ? 'plan'` |
+| `<@` | 被包含 | `'{"a":1}' <@ meta` |
+| `?` | 含指定键 | `meta ? 'plan'` |
+| `?\|` | 含任一键 | `meta ?\| '{a,b}'` |
+| `?&` | 含全部键 | `meta ?& '{a,b}'` |
+
+可链式取值：`meta->'addr'->>'city'`。
 
 ### LIKE / ILIKE / 正则
 
@@ -3358,14 +3471,12 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 
 - 基于 JS RegExp 引擎
 - 支持 flags：`i`（忽略大小写）、`m`（多行）、`s`（点匹配换行）
-- PG 风格的 `~` / `~*` / `!~` / `!~*` 运算符也支持：
-  - `name ~ '^A'`（大小写敏感匹配）
-  - `name ~* '^a'`（不敏感）
-  - `name !~ '^X'`（不匹配）
+- PG 风格的 `~`（大小写敏感）/ `~*`（不敏感）/ `!~` / `!~*` 双目运算符也支持；
+  单目位置的 `~` 仍是按位取反。
 
 ```sql
 SELECT * FROM users
-WHERE email ~* '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
+WHERE email REGEXP '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
 ```
 
 ### 事务 Transactions
@@ -4042,7 +4153,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 +4822,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 +5013,7 @@ npm run typecheck
 - `src/rust/`：Rust 引擎（native + wasm 同源）
 - `lib/`：Node 侧全部逻辑（协议/解析/TUI/兼容层）
 - `test/`：单元 + 集成测试
-- `docs/`：扩展文档
+- 扩展文档位于仓库根目录：`PLUGINS.md`（插件与模块）。本仓库**没有** `docs/` 目录。
 
 ---
 
@@ -5119,7 +5230,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*
 
 ---
 
@@ -5692,7 +5803,8 @@ expr := literal
       | expr [NOT] LIKE pattern [ESCAPE char]
       | expr [NOT] ILIKE pattern
       | expr [NOT] RLIKE pattern | expr [NOT] REGEXP pattern
-      | expr [NOT] ~ pattern | expr [NOT] ~* pattern | expr !~ pattern
+      | expr ~ pattern | expr ~* pattern | expr !~ pattern | expr !~* pattern
+      | expr ? key | expr ?| keys | expr ?& keys
       | expr IS [NOT] NULL | expr IS [NOT] TRUE | expr IS [NOT] FALSE
       | expr [NOT] IN ( ... )
       | expr [NOT] ANY '(' select_statement ')'
@@ -5738,16 +5850,17 @@ function_call := func_name '(' [DISTINCT] args ')'      -- 普通/聚合
 ### 运算符优先级（从高到低）
 
 ```
-1.  ()  .  []  ->  ->>  #>  #>>
-2.  ::  CAST 一元 + - ~
+1.  ()  .  []  ->  ->>  #>  #>>  ::
+2.  CAST 一元 + - ~
 3.  ^  *  /  %  DIV  MOD
 4.  +  -
 5.  <<  >>  &  |  ^（位）
-6.  =  <>  !=  <  <=  >  >=  <=>  BETWEEN  IN  LIKE  ILIKE  RLIKE  REGEXP  ~  ~*  @>  <@  ?
+6.  =  <>  !=  <  <=  >  >=  <=>  @>  <@  ?  ?|  ?&  BETWEEN  IN  LIKE  ILIKE  RLIKE  REGEXP  ~  ~*  !~  !~*
 7.  NOT
-8.  AND
-9.  OR  XOR
-10. 三元（IF / CASE 解析为函数）
+8.  AND  &&
+9.  XOR
+10. OR  ||
+11. 三元（IF / CASE 解析为函数）
 ```
 
 ### 关键词语法表
@@ -6594,7 +6707,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 +7002,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
@@ -7344,7 +7457,7 @@ jsql import ./data app.sql
 | 字符串字面量 | 单引号 | 单引号 | 单引号（双引号按标识符，PG 语义） |
 | 布尔 | `TRUE/FALSE`（1/0） | `t/f`（三值逻辑） | 兼容两者 |
 | 分页 | `LIMIT off, n` | `LIMIT n OFFSET off` | 两者 |
-| JSON 访问 | `JSON_EXTRACT` | `->` `->>` | 两者 + `#>>` |
+| JSON 访问 | `JSON_EXTRACT` | `->` `->>` `#>>` | 两者 |
 | 类型转换 | `CAST`/`CONVERT` | `::` | 三者 |
 | 条件分支 | `IF()` | `CASE` | `IF` + `CASE` + `IIF` |
 | 空值回退 | `IFNULL()` | `COALESCE` | 两者 |
@@ -7545,7 +7658,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 +8265,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/native_client.js

@@ -17,6 +17,33 @@ function safeParse(str, fallback) {
   try { return JSON.parse(str); } catch (e) { return fallback; }
 }
 
+/**
+ * 序列化对象/数组字段（JSON 列）并给出可读错误。直接 JSON.stringify 遇到循环引用会抛
+ * "Converting circular structure to JSON"，指向不到具体列，这里补上表/列信息。
+ * 与 lib/wasm_client.js 的 safeStringify 保持一致。
+ */
+function safeStringify(value, table, column) {
+  try {
+    return JSON.stringify(value);
+  } catch (e) {
+    const msg = (e && e.message) ? e.message : String(e);
+    throw new Error(`Cannot serialize column '${column}' of table '${table}': ${msg}`);
+  }
+}
+
+/** 插入行必须是普通对象；null/undefined/数组/基本类型在这里就被拦下（与 lib/wasm_client.js 一致） */
+function assertRowObject(row, index, isBatch) {
+  const ok = row !== null && row !== undefined && typeof row === 'object' &&
+    !Array.isArray(row) && !(row instanceof Date);
+  if (ok) return;
+  const got = row === null ? 'null'
+    : Array.isArray(row) ? 'array'
+      : row instanceof Date ? 'Date'
+        : typeof row;
+  const where = isBatch ? ` at index ${index}` : '';
+  throw new TypeError(`insert(): expected a row object${where}, got ${got}`);
+}
+
 const NATIVE_TYPE_MAP = {
   text: 'string',
   varchar: 'string',
@@ -399,8 +426,17 @@ class JSQL {
       rows = rows.map(row => {
         const out = {};
         for (const [k, v] of Object.entries(row)) {
-          if (v instanceof Date) out[k] = v.toISOString();
-          else out[k] = v;
+          const def = schema[k];
+          let t = null;
+          if (typeof def === 'string') t = def.toLowerCase();
+          else if (def && typeof def === 'object' && def.type) t = String(def.type).toLowerCase();
+          if (v !== null && v !== undefined && ['json', 'array', 'object'].includes(t) && typeof v !== 'string') {
+            out[k] = safeStringify(v, table, k);
+          } else if (v instanceof Date) {
+            out[k] = v.toISOString();
+          } else {
+            out[k] = v;
+          }
         }
         return out;
       });
@@ -450,18 +486,39 @@ class JSQL {
   async _flush() {
     this._flushOpsNow();
     if (!this._runHooks('beforeFlush', [])) return null;
-    const flushed = {};
-    for (const [table, rows] of Object.entries(this._buffer)) {
-      if (rows.length === 0) continue;
-      const r = await this._insertBatch(table, rows);
-      flushed[table] = r;
-    }
+    // 先把整个 buffer 原子取出再写入。
+    // 旧写法是遍历 this._buffer、await 之后才清空 —— 期间其他协程继续往同一个数组
+    // push，同一批行会被多个 flush 重复写入（并发 insert 行数暴涨/丢行）。
+    // 与 lib/wasm_client.js 的修法保持一致。
+    const pending = this._buffer;
     this._buffer = {};
     this._bufferSize = 0;
+    const flushed = {};
+    try {
+      for (const [table, rows] of Object.entries(pending)) {
+        if (rows.length === 0) continue;
+        flushed[table] = await this._insertBatch(table, rows);
+      }
+    } catch (e) {
+      // 坏行不回写 buffer：否则 stop() 二次 flush 会再抛同一个错导致进程 exit 1
+      if (!this._flushErrors) this._flushErrors = [];
+      this._flushErrors.push({
+        at: Date.now(),
+        message: (e && e.message) ? e.message : String(e),
+        tables: Object.keys(pending),
+        rowCounts: Object.fromEntries(Object.entries(pending).map(([t, r]) => [t, r.length])),
+      });
+      throw e;
+    }
     this._runHooks('afterFlush', []);
     return flushed;
   }
 
+  /** 返回历次 flush 失败的记录（坏行不会回写 buffer，只能从这里查） */
+  lastFlushErrors() {
+    return (this._flushErrors || []).slice();
+  }
+
   _flushOpsNow() {
     if (this._opTimer) {
       clearTimeout(this._opTimer);
@@ -479,7 +536,11 @@ class JSQL {
   }
 
   async insert(table, data) {
+    // 入参校验：null / undefined / 非对象会在下游 Object.entries() 处炸成
+    // 难以定位的 "Cannot convert undefined or null to object"，这里直接给明确 TypeError
+    // （与 lib/wasm_client.js 的 assertRowObject 保持一致）
     const arr = Array.isArray(data) ? data : [data];
+    arr.forEach((row, i) => assertRowObject(row, i, arr.length > 1 || Array.isArray(data)));
     var filtered = arr;
     if (!this._runHooks('beforeInsert', [table, filtered])) return [];
     if (arr.length > 1) {

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 };