jsql-neo 6.0.2 → 6.0.4

package/README.md

@@ -835,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
@@ -1102,24 +1102,24 @@ ORDER BY avg_sal DESC;
 
 **Bitwise** — `& | ^ ~ << >>`（`^` 是按位异或，`~` 是按位取反）。
 
-> **运算符方言说明。** `^` 与 `~` 在 MySQL（位运算）和 PostgreSQL（`^` 为幂、
-> `~` 为正则匹配）中含义冲突，本实现统一采用 **MySQL 语义**：`^` = 按位异或、
-> `~` = 按位取反。需要幂运算请用 `POWER(x, n)`，需要正则请用 `REGEXP` / `~*`。
-> 因此 PG 风格的 `^`（幂）、`~ ~* !~ !~*`（正则）与 JSON 操作符
-> （`-> ->> #> #>> @> <@`）**暂不支持**。
+> **运算符方言说明。** `^` 与 `~` 在 MySQL 与 PostgreSQL 中含义冲突，本实现按上下文区分：
+> - `^` 统一为**按位异或**（MySQL 语义）；幂运算请用 `POWER(x, n)`。
+> - `~` 在**单目**位置是按位取反（MySQL），在**双目**位置是正则匹配（PG），
+>   另有 `~*`（不敏感）、`!~`、`!~*`。
+> - 需要正则时也可用 `REGEXP` / `RLIKE`；PG 的 `^`（幂）**暂不支持**。
 
-**JSON (PG style)** — `->` (JSON result), `->>` (text), `#>`, `#>>` (paths), `@>` `<@`
-(containment), `?` `?|` `?&` (key existence).
+**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
@@ -1270,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.
 
 #### 参数绑定：两种方式
@@ -3137,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]
@@ -3403,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 |
 
 #### 比较运算符
 
@@ -3445,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 / 正则
 
@@ -3466,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
@@ -5800,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 ')'
@@ -5846,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 解析为函数）
 ```
 
 ### 关键词语法表
@@ -7452,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` | 两者 |

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) {