jsql-neo 6.0.2 → 6.1.0

package/README.md

@@ -1104,22 +1104,22 @@ ORDER BY avg_sal DESC;
 
 > **运算符方言说明。** `^` 与 `~` 在 MySQL（位运算）和 PostgreSQL（`^` 为幂、
 > `~` 为正则匹配）中含义冲突，本实现统一采用 **MySQL 语义**：`^` = 按位异或、
-> `~` = 按位取反。需要幂运算请用 `POWER(x, n)`，需要正则请用 `REGEXP` / `~*`。
-> 因此 PG 风格的 `^`（幂）、`~ ~* !~ !~*`（正则）与 JSON 操作符
-> （`-> ->> #> #>> @> <@`）**暂不支持**。
+> `~` = 按位取反。需要幂运算请用 `POWER(x, n)`，需要正则请用 `REGEXP`。
+> 因此 PG 风格的 `^`（幂）与 `~ ~* !~ !~*`（正则）**暂不支持**。
 
-**JSON (PG style)** — `->` (JSON result), `->>` (text), `#>`, `#>>` (paths), `@>` `<@`
-(containment), `?` `?|` `?&` (key existence).
+**JSON (PG style)** — `->`（返回 JSON）、`->>`（返回文本），可链式
+（`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
@@ -1162,7 +1162,7 @@ INSERT INTO users (id, meta) VALUES
   (1, '{"name":"Alice","tags":["admin","ops"],"addr":{"city":"SH"}}');
 
 SELECT meta->>'name' AS name, meta->'addr'->>'city' AS city
-FROM users WHERE meta @> '{"tags":["admin"]}';
+FROM users;
 ```
 
 JSON columns are fully interoperable with Mongo document views.
@@ -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.
 
 #### 参数绑定：两种方式
@@ -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,10 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 |---|---|---|
 | `->` | 取 JSON 字段（返回 JSON） | `meta->'name'` |
 | `->>` | 取 JSON 字段（返回文本） | `meta->>'name'` |
-| `#>`, `#>>` | 路径访问 | `meta#>>'{a,b}'` |
-| `@>` | 包含 | `meta @> '{"plan":"pro"}'` |
-| `<@` | 被包含 | `'{"a":1}'::jsonb <@ meta` |
-| `?` / `?|` / `?&` | 键存在 | `meta ? 'plan'` |
+
+可链式取值：`meta->'addr'->>'city'`。
+
+> `#>` `#>>`（路径访问）、`@>` `<@`（包含）、`?` `?|` `?&`（键存在）**暂不支持** —— 使用时会抛出明确错误，不会静默退化成别的运算。
 
 ### LIKE / ILIKE / 正则
 
@@ -3466,14 +3466,12 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 
 - 基于 JS RegExp 引擎
 - 支持 flags：`i`（忽略大小写）、`m`（多行）、`s`（点匹配换行）
-- PG 风格的 `~` / `~*` / `!~` / `!~*` 运算符也支持：
-  - `name ~ '^A'`（大小写敏感匹配）
-  - `name ~* '^a'`（不敏感）
-  - `name !~ '^X'`（不匹配）
+- PG 风格的 `~` / `~*` / `!~` / `!~*` 运算符**暂不支持**（`~` 已被用作按位取反）。
+  正则匹配请用 `REGEXP` / `RLIKE`。
 
 ```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
@@ -3572,7 +3570,7 @@ INSERT INTO users (id, meta) VALUES
 -- 查询路径
 SELECT meta->>'name' AS name,
        meta->'addr'->>'city' AS city
-FROM users WHERE meta @> '{"tags":["admin"]}';
+FROM users;
 ```
 
 JSON 函数见 [系统与杂项函数](#系统与杂项函数)。Mongo 客户端视角下，JSON 列与 BSON 文档完全互通。
@@ -5800,7 +5798,6 @@ 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 IS [NOT] NULL | expr IS [NOT] TRUE | expr IS [NOT] FALSE
       | expr [NOT] IN ( ... )
       | expr [NOT] ANY '(' select_statement ')'
@@ -5846,16 +5843,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 解析为函数）
 ```
 
 ### 关键词语法表
@@ -7447,12 +7445,12 @@ jsql import ./data app.sql
 | 冲突处理 | `ON DUPLICATE KEY UPDATE` | `ON CONFLICT ... DO ...` | 两者都支持 |
 | 占位符 | `?` | `$1, $2` | 两者（分协议） |
 | 模糊匹配 | `LIKE`（大小写敏感） | `LIKE` + `ILIKE` | 两者 |
-| 正则 | `REGEXP` | `~` `~*` | 两者 + `RLIKE` |
+| 正则 | `REGEXP` | `REGEXP` | 两者 + `RLIKE` |
 | 标识符引用 | 反引号 `` ` `` | 双引号 `"` | 两者 |
 | 字符串字面量 | 单引号 | 单引号 | 单引号（双引号按标识符，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) {

package/lib/sql.js

@@ -79,6 +79,11 @@ function tokenize(sql) {
       while (i < n && sql[i] !== '\n') i++;
       continue;
     }
+    // PG 的 JSON 路径操作符 #> / #>> 尚未实现。
+    // 若不在这里拦截，'#' 会被当成行注释吃掉，导致 SQL 后半段被静默丢弃。
+    if (c === '#' && sql[i + 1] === '>') {
+      throw new Error("JSON 路径操作符 '#>' / '#>>' 暂不支持，请改用 '->' / '->>'");
+    }
     if (c === '#' || (c === '/' && sql[i + 1] === '*')) {
       if (c === '#') { while (i < n && sql[i] !== '\n') i++; continue; }
       i += 2;
@@ -95,7 +100,10 @@ function tokenize(sql) {
         if (sql[j] === '\\' && j + 1 < n) {
           const esc = sql[j + 1];
           const map = { n: '\n', t: '\t', r: '\r', '0': '\0', "'": "'", '"': '"', '\\': '\\', b: '\b', Z: '\x1a', a: '\a' };
-          str += map[esc] !== undefined ? map[esc] : esc;
+          // MySQL 语义：\% 与 \_ 保留反斜杠（供 LIKE 匹配字面量通配符），其余未知转义忽略反斜杠
+          if (map[esc] !== undefined) str += map[esc];
+          else if (esc === '%' || esc === '_') str += '\\' + esc;
+          else str += esc;
           j += 2;
         } else if (sql[j] === quote) {
           break;
@@ -150,6 +158,12 @@ function tokenize(sql) {
       continue;
     }
 
+    // PG 的 JSON 包含操作符 @> 尚未实现。
+    // 若不拦截，'@' 会被 sysvar 分支静默吞掉、'>' 退化成普通大于号，产生错误结果。
+    if (c === '@' && sql[i + 1] === '>') {
+      throw new Error("JSON 包含操作符 '@>' 暂不支持");
+    }
+
     if (c === '@') {
       let j = i;
       while (j < n && sql[j] === '@') j++;
@@ -177,9 +191,20 @@ function tokenize(sql) {
       continue;
     }
 
+    const three = sql.slice(i, i + 3);
+    if (sql.slice(i, i + 2) === '<@') {
+      throw new Error("JSON 包含操作符 '<@' 暂不支持");
+    }
+    if (three === '->>' || three === '<=>') {
+      tokens.push(new SQLToken('op', three, i));
+      i += 3;
+      continue;
+    }
+
     const two = sql.slice(i, i + 2);
     if (two === '<=' || two === '>=' || two === '!=' || two === '<>' || two === '==' ||
-        two === '<<' || two === '>>') {
+        two === '<<' || two === '>>' || two === '->' || two === '::' ||
+        two === '&&' || two === '||') {
       tokens.push(new SQLToken('op', two, i));
       i += 2;
       continue;
@@ -523,19 +548,27 @@ class Parser {
   parseColumnDef() {
     const def = {};
     const typeTok = this.next();
-    if (typeTok.type !== 'keyword') throw new Error(`Expected column type, got '${typeTok.value}'`);
-    const type = typeTok.value.toLowerCase();
+    const typeRaw = String(typeTok.value);
+    // 这些类型不在 KEYWORDS 里（避免影响同名标识符），按上下文识别
+    const IDENT_TYPES = /^(BIG)?SERIAL$|^JSONB$|^TIMESTAMPTZ$|^BYTEA$|^UUID$/i;
+    const isIdentType = IDENT_TYPES.test(typeRaw);
+    if (typeTok.type !== 'keyword' && !isIdentType) throw new Error(`Expected column type, got '${typeTok.value}'`);
+    const type = typeRaw.toLowerCase();
     const typeMap = {
       integer: 'integer', int: 'integer', bigint: 'integer', tinyint: 'integer', smallint: 'integer',
       string: 'string', text: 'string', varchar: 'string', char: 'string',
       float: 'number', double: 'number', real: 'number', numeric: 'number', decimal: 'number',
       boolean: 'boolean', bool: 'boolean',
-      date: 'date', datetime: 'datetime', timestamp: 'timestamp',
-      any: 'any', object: 'object', json: 'object', array: 'array'
+      date: 'date', datetime: 'datetime', timestamp: 'timestamp', timestamptz: 'timestamp',
+      any: 'any', object: 'object', json: 'object', jsonb: 'object', array: 'array',
+      bytea: 'string', uuid: 'string',
+      // PG 自增序列类型：等价于整型 + 自增 + NOT NULL
+      serial: 'integer', bigserial: 'integer'
     };
     const mapped = typeMap[type];
     if (!mapped) throw new Error(`Unsupported column type: ${typeTok.value}`);
     def.type = mapped;
+    if (/^(BIG)?SERIAL$/i.test(typeRaw)) { def.autoIncrement = true; def.required = true; }
 
     // 长度限制: TEXT(255) / VARCHAR(100) / INTEGER(11) ...
     if (this.peek().type === 'op' && this.peek().value === '(') {
@@ -598,6 +631,11 @@ class Parser {
               def.defaultExpr = true;
             } else {
               def.default = this.parseValue();
+              // 允许字面量后带 :: 类型转换：DEFAULT '{}'::jsonb
+              if (this.peek().type === 'op' && this.peek().value === '::') {
+                this.next();
+                if (this.peek().type === 'keyword' || this.peek().type === 'ident') this.next();
+              }
             }
             break;
           case 'COLLATE':
@@ -772,7 +810,7 @@ class Parser {
           for (;;) {
             const col = this.parseColumnRef();
             this.expect('op', '=');
-            const val = this.parseValue();
+            const val = this.parseConflictValue();
             sets.push([col, val]);
             if (this.peek().value === ',') { this.next(); continue; }
             break;
@@ -852,6 +890,21 @@ class Parser {
     throw new Error(`Expected value, got '${t.value}'`);
   }
 
+  /**
+   * ON CONFLICT DO UPDATE 赋值右侧：
+   *   EXCLUDED.col —— PG：引用"本次本应插入的值"
+   *   VALUES(col)  —— MySQL 同义（在 parseValue 中处理）
+   *   其他字面量
+   */
+  parseConflictValue() {
+    if (this.isWord('EXCLUDED') && this.peek(1).type === 'op' && this.peek(1).value === '.') {
+      this.next(); this.next();
+      const col = this.parseColumnRef();
+      return { _excludedOf: col };
+    }
+    return this.parseValue();
+  }
+
   /**
    * WITH [RECURSIVE] name [(col, ...)] AS (SELECT ...), ... <statement>
    * CTE 在语法层解析为 { type:'with', ctes:[{name, columns, select}], statement }。
@@ -1628,18 +1681,33 @@ class Parser {
   }
 
   parseOr() {
+    let left = this.parseXor();
+    for (;;) {
+      const isOr = this.isKeyword('OR') || (this.peek().type === 'op' && this.peek().value === '||');
+      if (!isOr) break;
+      this.next();
+      const right = this.parseXor();
+      left = { type: 'or', left, right };
+    }
+    return left;
+  }
+
+  // 逻辑异或 XOR（MySQL 优先级：OR < XOR < AND）
+  parseXor() {
     let left = this.parseAnd();
-    while (this.isKeyword('OR')) {
+    while (this.isWord('XOR')) {
       this.next();
       const right = this.parseAnd();
-      left = { type: 'or', left, right };
+      left = { type: 'xor', left, right };
     }
     return left;
   }
 
   parseAnd() {
     let left = this.parseNot();
-    while (this.isKeyword('AND')) {
+    for (;;) {
+      const isAnd = this.isKeyword('AND') || (this.peek().type === 'op' && this.peek().value === '&&');
+      if (!isAnd) break;
       this.next();
       const right = this.parseNot();
       left = { type: 'and', left, right };
@@ -1981,15 +2049,58 @@ class Parser {
   }
 
   parseTerm() {
-    let node = this.parseOperand();
+    let node = this.parsePostfix(this.parseOperand());
     for (;;) {
       const t = this.peek();
       if (t.type === 'op' && (t.value === '*' || t.value === '/' || t.value === '%')) {
         this.next();
-        const right = this.parseOperand();
+        const right = this.parsePostfix(this.parseOperand());
         node = { type: 'arith', op: t.value, left: node, right };
         continue;
       }
+      // MySQL 整数除法：7 DIV 2 → 3
+      if (this.isWord('DIV')) {
+        this.next();
+        const right = this.parsePostfix(this.parseOperand());
+        node = { type: 'arith', op: 'DIV', left: node, right };
+        continue;
+      }
+      break;
+    }
+    return node;
+  }
+
+  /**
+   * 后缀运算符（绑定最紧）：PG 风格 `::` 类型转换、`->` / `->>` JSON 取值。
+   * 例：'5'::INT、meta->>'name'、meta->'addr'->>'city'。
+   */
+  parsePostfix(node) {
+    for (;;) {
+      const t = this.peek();
+      if (t.type === 'op' && t.value === '::') {
+        this.next();
+        const typeTok = this.next();
+        let dataType = String(typeTok.value).toUpperCase();
+        if (this.peek().type === 'op' && this.peek().value === '(') {
+          this.next();
+          let depth = 1, spec = '';
+          while (depth > 0 && this.peek().type !== 'eof') {
+            const tk = this.next();
+            if (tk.type === 'op' && tk.value === '(') depth++;
+            else if (tk.type === 'op' && tk.value === ')') { depth--; if (depth === 0) break; }
+            spec += tk.value;
+          }
+          dataType += '(' + spec + ')';
+        }
+        node = { type: 'cast', expr: node, dataType };
+        continue;
+      }
+      if (t.type === 'op' && (t.value === '->' || t.value === '->>')) {
+        this.next();
+        const key = this.parseValue();
+        node = { type: 'jsonAccess', operand: node, key, asText: t.value === '->>' };
+        continue;
+      }
       break;
     }
     return node;
@@ -2085,7 +2196,10 @@ class Parser {
       const isILike = !(t2.type === 'keyword' && t2.value === 'LIKE');
       this.next();
       const pattern = this.parseValue();
-      return { type: 'like', operand: left, pattern, not, ci: isILike };
+      // 可选 ESCAPE 子句：LIKE '...' ESCAPE '!'
+      let escape = null;
+      if (this.isWord('ESCAPE')) { this.next(); escape = this.parseValue(); }
+      return { type: 'like', operand: left, pattern, not, ci: isILike, escape };
     }
 
     // MySQL 中 RLIKE 是 REGEXP 的同义词
@@ -2095,7 +2209,7 @@ class Parser {
       return { type: 'regexp', operand: left, pattern, not };
     }
 
-    if (t2.type === 'op' && ['=', '!=', '<>', '<', '<=', '>', '>='].includes(t2.value)) {
+    if (t2.type === 'op' && ['=', '!=', '<>', '<', '<=', '>', '>=', '<=>'].includes(t2.value)) {
       this.next();
       // = ANY (SELECT ...) / > ALL (SELECT ...)
       const anyAll = this.isWord('ANY') || this.isWord('ALL') || this.isWord('SOME');
@@ -2209,6 +2323,8 @@ function resolveOperand(operand, row, ctx) {
         case '*': return l * r;
         case '/': return r === 0 ? null : l / r;
         case '%': return r === 0 ? null : l % r;
+        // MySQL 整数除法 DIV（结果向零取整）
+        case 'DIV': return r === 0 ? null : Math.trunc(Number(l) / Number(r));
         // 位运算：先按整数归一，与 MySQL 的整数位运算语义一致
         case '&': return (Number(l) | 0) & (Number(r) | 0);
         case '|': return (Number(l) | 0) | (Number(r) | 0);
@@ -2229,6 +2345,7 @@ function resolveOperand(operand, row, ctx) {
     case 'compare':
     case 'and':
     case 'or':
+    case 'xor':
     case 'not':
     case 'in':
     case 'isNull':
@@ -2253,6 +2370,30 @@ function resolveOperand(operand, row, ctx) {
       const v = resolveOperand(operand.expr, row, ctx);
       return applyCast(v, operand.dataType);
     }
+    case 'jsonAccess': {
+      let base = resolveOperand(operand.operand, row, ctx);
+      if (base === null || base === undefined) return null;
+      // JSON 列可能以字符串形式存储，先解析
+      if (typeof base === 'string') {
+        try { base = JSON.parse(base); } catch (e) { return null; }
+      }
+      const key = operand.key;
+      let v;
+      if (Array.isArray(base)) {
+        const idx = Number(key);
+        v = Number.isInteger(idx) ? (idx < 0 ? base[base.length + idx] : base[idx]) : undefined;
+      } else if (base && typeof base === 'object') {
+        v = base[key];
+      } else {
+        return null;
+      }
+      if (v === undefined) return null;
+      if (operand.asText) {
+        if (v === null) return null;
+        return typeof v === 'object' ? JSON.stringify(v) : String(v);
+      }
+      return v;
+    }
     case 'quantified': {
       // = ANY / > ALL (SELECT ...) —— 需先由执行层物化成 operand._list
       const v = resolveOperand(operand.operand, row, ctx);
@@ -2471,13 +2612,25 @@ function seedRand(seed) {
 }
 
 // ci 默认 true：保持 LIKE 既有的大小写不敏感行为不变；ILIKE 同为不敏感。
-function likeMatch(value, pattern, ci = true) {
+// escape：可选转义符（ESCAPE 子句），默认反斜杠；转义符后跟 % _ 或转义符本身按字面量匹配。
+function likeMatch(value, pattern, ci = true, escape = '\\') {
   if (typeof value !== 'string') return false;
-  const regex = pattern
-    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    .replace(/%/g, '.*')
-    .replace(/_/g, '.');
-  return new RegExp('^' + regex + '$', ci ? 'i' : '').test(value);
+  const p = String(pattern);
+  const e = (escape === null || escape === undefined || escape === '') ? '\\' : String(escape);
+  const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  let out = '';
+  for (let i = 0; i < p.length; i++) {
+    const ch = p[i];
+    if (ch === e && i + 1 < p.length && (p[i + 1] === '%' || p[i + 1] === '_' || p[i + 1] === e)) {
+      out += reEsc(p[i + 1]);
+      i++;
+      continue;
+    }
+    if (ch === '%') out += '.*';
+    else if (ch === '_') out += '.';
+    else out += reEsc(ch);
+  }
+  return new RegExp('^' + out + '$', ci ? 'i' : '').test(value);
 }
 
 function extractEqualPushdown(expr, schema) {
@@ -2529,10 +2682,18 @@ function evaluateExpr(expr, row, ctx) {
   switch (expr.type) {
     case 'and': return evaluateExpr(expr.left, row, ctx) && evaluateExpr(expr.right, row, ctx);
     case 'or': return evaluateExpr(expr.left, row, ctx) || evaluateExpr(expr.right, row, ctx);
+    case 'xor': return Boolean(evaluateExpr(expr.left, row, ctx)) !== Boolean(evaluateExpr(expr.right, row, ctx));
     case 'not': return !evaluateExpr(expr.expr, row, ctx);
     case 'compare': {
       const l = resolveOperand(expr.left, row, ctx);
       const r = resolveOperand(expr.right, row, ctx);
+      // MySQL NULL 安全相等：NULL <=> NULL 为真；NULL <=> 值 为假
+      if (expr.op === '<=>') {
+        const ln = l === null || l === undefined;
+        const rn = r === null || r === undefined;
+        if (ln || rn) return ln && rn;
+        return l === r || String(l) === String(r);
+      }
       // SQL 标准：任何与 NULL 的比较结果为 UNKNOWN（在 WHERE/ON/HAVING 中视为 false）
       if (l === null || r === null) return false;
       // 布尔与数值互通（MySQL: 1 = TRUE、0 = FALSE）
@@ -2555,7 +2716,7 @@ function evaluateExpr(expr, row, ctx) {
     }
     case 'like': {
       const v = resolveOperand(expr.operand, row, ctx);
-      const r = likeMatch(v, expr.pattern, !!expr.ci);
+      const r = likeMatch(v, expr.pattern, !!expr.ci, expr.escape);
       return expr.not ? !r : r;
     }
     case 'quantified':
@@ -2858,7 +3019,23 @@ class SQLExecutor {
         if (pkCols.length > 0) {
           const keyOf = (row) => pkCols.map(c => (row[c] !== undefined && row[c] !== null ? String(row[c]) : '')).join('|');
           const hasExplicitPk = (row) => pkCols.some(c => row[c] !== undefined && row[c] !== null);
-          const explicit = dataRows.filter(hasExplicitPk);
+          // 冲突判定的额外列组：
+          //   ON CONFLICT (col) DO UPDATE → 指定列（PG）
+          //   ON DUPLICATE KEY UPDATE     → 各唯一列（MySQL：任一唯一键冲突都触发）
+          // 此前只认主键，导致这两者在唯一列冲突时会插入重复行而不是更新。
+          const ocTarget = (statement.onConflict && Array.isArray(statement.onConflict.target))
+            ? statement.onConflict.target.map(c => (c && c.name !== undefined ? c.name : c)).filter(Boolean)
+            : null;
+          const extraIdx = [];
+          if (ocTarget && ocTarget.length) extraIdx.push(ocTarget);
+          else if (statement.onDuplicate && schema) {
+            for (const [c, def] of Object.entries(schema)) {
+              if (def && def.unique && !def.primaryKey) extraIdx.push([c]);
+            }
+          }
+          const hasAllOf = (cols) => (row) => cols.every(c => row[c] !== undefined && row[c] !== null);
+
+          const explicit = dataRows.filter((row) => hasExplicitPk(row) || extraIdx.some((cols) => hasAllOf(cols)(row)));
           if (explicit.length > 0) {
             const all = (await this.engine.find(statement.name, {}, { limit: 1e9, offset: 0 })).map(r => normalizeRow(r, schema));
             const pkMap = new Map();
@@ -2866,15 +3043,31 @@ class SQLExecutor {
               const keys = pkCols.map(c => row[c]).filter(v => v !== undefined && v !== null);
               if (keys.length === pkCols.length) pkMap.set(keyOf(row), keys);
             }
+            const pkValsOf = (row) => pkCols.map(c => row[c]).filter(v => v !== undefined && v !== null);
+            const extraMaps = extraIdx.map((cols) => {
+              const m = new Map();
+              const pick = hasAllOf(cols);
+              const key = (row) => cols.map(c => String(row[c])).join('|');
+              for (const row of all) {
+                if (!pick(row)) continue;
+                m.set(key(row), pkValsOf(row));
+              }
+              return { pick, key, m };
+            });
             const conflicts = [];
             const fresh = [];
             for (const d of dataRows) {
-              const key = keyOf(d);
-              if (hasExplicitPk(d) && pkMap.has(key)) {
-                conflicts.push({ d, existingId: pkMap.get(key) });
-              } else {
-                fresh.push(d);
+              let existingId = null;
+              if (hasExplicitPk(d) && pkMap.has(keyOf(d))) existingId = pkMap.get(keyOf(d));
+              if (!existingId) {
+                for (const { pick, key, m } of extraMaps) {
+                  if (!pick(d)) continue;
+                  const k = key(d);
+                  if (m.has(k)) { existingId = m.get(k); break; }
+                }
               }
+              if (existingId) conflicts.push({ d, existingId });
+              else fresh.push(d);
             }
             const conflictAction = this._conflictAction(statement);
             const conflictSets = this._conflictSets(statement);
@@ -2902,10 +3095,14 @@ class SQLExecutor {
                 const data = {};
                 if (conflictSets) {
                   for (const [col, val] of conflictSets) {
-                    // VALUES(col) 引用本次本应插入的值
-                    data[col] = (val && typeof val === 'object' && val._valuesOf !== undefined)
-                      ? (d[val._valuesOf] !== undefined ? d[val._valuesOf] : null)
-                      : val;
+                    // VALUES(col) 引用本次本应插入的值；EXCLUDED.col 为 PG 同义写法
+                    if (val && typeof val === 'object' && val._valuesOf !== undefined) {
+                      data[col] = d[val._valuesOf] !== undefined ? d[val._valuesOf] : null;
+                    } else if (val && typeof val === 'object' && val._excludedOf !== undefined) {
+                      data[col] = d[val._excludedOf] !== undefined ? d[val._excludedOf] : null;
+                    } else {
+                      data[col] = val;
+                    }
                   }
                 } else {
                   for (const k of Object.keys(d)) if (!pkCols.includes(k)) data[k] = d[k];
@@ -4678,6 +4875,44 @@ function applyParams(sql, values) {
   return out;
 }
 
+// 把执行器结果补齐为 README 承诺的结果信封
+// （columnTypes / rowCount / message / command / durationMs / warnings）
+function buildResultEnvelope(stmt, r, durationMs) {
+  if (r === null || typeof r !== 'object' || Array.isArray(r)) return r;
+  const out = { ...r };
+  const t = stmt && stmt.type;
+  if (out.command === undefined) out.command = String(t || '').toUpperCase();
+  if (out.affectedRows === undefined) out.affectedRows = 0;
+  if (out.rowCount === undefined) {
+    out.rowCount = Array.isArray(out.rows) ? out.rows.length
+      : (typeof out.affectedRows === 'number' ? out.affectedRows : 0);
+  }
+  if (out.warnings === undefined) out.warnings = [];
+  if (out.durationMs === undefined) out.durationMs = durationMs;
+  if (out.message === undefined) {
+    out.message = t === 'select'
+      ? `${out.rowCount} row${out.rowCount === 1 ? '' : 's'} selected`
+      : `${out.affectedRows} row${out.affectedRows === 1 ? '' : 's'} affected`;
+  }
+  return out;
+}
+
+// SELECT 结果的列类型：单表查询按 schema 推断；表达式/多表查询该列为 null
+async function inferColumnTypes(engine, stmt, r) {
+  if (!r || !Array.isArray(r.columns)) return undefined;
+  let schema = null;
+  try {
+    const t = stmt && stmt.type === 'select' && stmt.from &&
+      Array.isArray(stmt.from.tables) && stmt.from.tables.length === 1
+      ? stmt.from.tables[0].table : null;
+    if (t && engine && typeof engine.getTableSchema === 'function') schema = await engine.getTableSchema(t);
+  } catch (e) { schema = null; }
+  return r.columns.map((name) => {
+    const def = schema && schema[name];
+    return def && def.type ? sqlTypeName(def.type).toUpperCase() : null;
+  });
+}
+
 async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
   // 参数守卫：engine 必须是引擎对象，sql 必须是字符串。误用时报清晰错误，
   // 而不是在后续像 `reading 'length'` 那样抛出令人费解的 TypeError。
@@ -4727,7 +4962,14 @@ async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
   const results = [];
   for (const stmtSql of statements) {
     const stmt = parseSQL(stmtSql);
-    results.push(await executor.execute(stmt));
+    const t0 = process.hrtime.bigint();
+    let r = await executor.execute(stmt);
+    const durationMs = Number(process.hrtime.bigint() - t0) / 1e6;
+    r = buildResultEnvelope(stmt, r, Math.round(durationMs * 1000) / 1000);
+    if (r && r.columns && r.columnTypes === undefined) {
+      r.columnTypes = await inferColumnTypes(engine, stmt, r);
+    }
+    results.push(r);
   }
   return results.length === 1 ? results[0] : results;
 }

package/nativesrc/jsql-neo-native/Cargo.lock

@@ -205,7 +205,7 @@ dependencies = [
 
 [[package]]
 name = "jsql-neo-core"
-version = "5.6.0"
+version = "6.0.0"
 dependencies = [
  "bincode",
  "chrono",
@@ -220,7 +220,7 @@ dependencies = [
 
 [[package]]
 name = "jsql-neo-native"
-version = "5.6.0"
+version = "6.0.0"
 dependencies = [
  "jsql-neo-core",
  "napi",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.0.2",
+  "version": "6.1.0",
   "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",

package/test/readme-audit.test.js

@@ -139,6 +139,51 @@ async function main() {
       JSON.stringify(await rowsOf('SELECT name FROM (SELECT name, sal FROM emp WHERE sal > 150)')) === '[["b"],["c"],["d"]]');
   }
 
+  console.log('\n--- 方言特性：DIV / XOR / && / || / <=> / :: / -> ->> / LIKE ESCAPE ---');
+  {
+    const data = [
+      { id: 1, n: 10, flag: 1, s: '100%', meta: '{"name":"Alice","addr":{"city":"SH"},"tags":["x","y"]}' },
+      { id: 2, n: 20, flag: 0, s: '1000', meta: '{"name":"Bob","addr":{"city":"BJ"},"tags":[]}' },
+      { id: 3, n: 30, flag: 1, s: '100', meta: null },
+    ];
+    const engine = {
+      hasTable: () => true, truncate: async () => {}, flush: async () => {},
+      find: async () => data.map(r => ({ ...r })),
+      getTableSchema: async () => ({
+        id: { type: 'integer', primaryKey: true }, n: { type: 'integer' }, flag: { type: 'integer' },
+        s: { type: 'string' }, meta: { type: 'json' },
+      }),
+    };
+    const rowsOf = async (sql) => {
+      const r = await executeSQL(engine, sql, OPTS);
+      return (Array.isArray(r) ? r[0] : r).rows;
+    };
+
+    ok('DIV 整数除法', JSON.stringify(await rowsOf('SELECT 7 DIV 2 AS r')) === '[[3]]');
+    ok('DIV 负数向零取整', JSON.stringify(await rowsOf('SELECT -7 DIV 2 AS r')) === '[[-3]]');
+    ok("'5'::INT 类型转换", JSON.stringify(await rowsOf("SELECT '5'::INT AS r")) === '[[5]]');
+    ok('XOR 逻辑异或（WHERE）',
+      JSON.stringify(await rowsOf('SELECT id FROM tbl WHERE flag = 1 XOR n = 20')) === '[[1],[2],[3]]');
+    ok('&& 是 AND 别名',
+      JSON.stringify(await rowsOf('SELECT id FROM tbl WHERE flag = 1 && n > 10')) === '[[3]]');
+    ok('|| 是 OR 别名',
+      JSON.stringify(await rowsOf('SELECT id FROM tbl WHERE flag = 0 || n > 20')) === '[[2],[3]]');
+    ok('<=> 非空相等', JSON.stringify(await rowsOf('SELECT id FROM tbl WHERE n <=> 20')) === '[[2]]');
+    ok('<=> NULL 安全（NULL<=>NULL 为真）',
+      JSON.stringify(await rowsOf('SELECT id FROM tbl WHERE meta <=> NULL')) === '[[3]]');
+    ok("->>'name'", JSON.stringify(await rowsOf("SELECT meta->>'name' AS x FROM tbl WHERE id = 1")) === '[["Alice"]]');
+    ok("->'addr'->>'city' 链式",
+      JSON.stringify(await rowsOf("SELECT meta->'addr'->>'city' AS x FROM tbl WHERE id = 1")) === '[["SH"]]');
+    ok("->'tags'->>0 数组下标",
+      JSON.stringify(await rowsOf("SELECT meta->'tags'->>0 AS x FROM tbl WHERE id = 1")) === '[["x"]]');
+    ok("LIKE ... ESCAPE '!' 匹配字面量 %",
+      JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE s LIKE '100!%' ESCAPE '!'")) === '[[1]]');
+    ok('LIKE 反斜杠转义匹配字面量 %',
+      JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE s LIKE '100\\%'")) === '[[1]]');
+    ok('LIKE 普通 % 仍为通配',
+      JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE s LIKE '100%'")) === '[[1],[2],[3]]');
+  }
+
   console.log('\n--- DDL / 解析器节点覆盖 ---');
   {
     ok('CREATE INDEX 可解析', parseSQL('CREATE INDEX i ON t (a)').type === 'createIndex');
@@ -156,6 +201,30 @@ async function main() {
       const st = parseSQL('CREATE TABLE t (id INT PRIMARY KEY, c DATETIME DEFAULT CURRENT_TIMESTAMP)');
       return st.schema.c.default === 'CURRENT_TIMESTAMP';
     })());
+    ok('SERIAL 折叠为整型+自增', (() => {
+      const st = parseSQL('CREATE TABLE t (id SERIAL PRIMARY KEY, n TEXT)');
+      return st.schema.id.type === 'integer' && st.schema.id.autoIncrement === true;
+    })());
+    ok('BIGSERIAL 折叠为整型+自增', (() => {
+      const st = parseSQL('CREATE TABLE t (id BIGSERIAL PRIMARY KEY)');
+      return st.schema.id.type === 'integer' && st.schema.id.autoIncrement === true;
+    })());
+  }
+
+  console.log('\n--- executeSQL 结果信封（README 承诺的字段）---');
+  {
+    const engine = {
+      hasTable: () => true, truncate: async () => {}, flush: async () => {},
+      find: async () => [{ id: 1, name: 'a' }, { id: 2, name: 'b' }],
+      getTableSchema: async () => ({ id: { type: 'integer', primaryKey: true }, name: { type: 'string' } }),
+    };
+    const r = await executeSQL(engine, 'SELECT * FROM t', OPTS);
+    for (const f of ['columns', 'columnTypes', 'rows', 'rowCount', 'affectedRows', 'message', 'command', 'durationMs', 'warnings']) {
+      ok(`信封含 ${f}`, r[f] !== undefined, Object.keys(r));
+    }
+    ok('rowCount = 2', r.rowCount === 2);
+    ok('command = SELECT', r.command === 'SELECT');
+    ok('columnTypes 可推断（id → INT）', Array.isArray(r.columnTypes) && r.columnTypes[0] === 'INT');
   }
 
   console.log('\n--- 顶层工厂导出不得为 undefined ---');
@@ -214,29 +283,32 @@ async function main() {
 
   console.log('\n--- 并发 insert 不得重复写（曾行数暴涨 / 丢失）---');
   {
-    const { JSQL } = require('../lib/wasm_client.js');
-    let db;
-    try {
-      db = new JSQL();
-      await db.start();
-    } catch (e) {
-      console.log('[SKIP] WASM 客户端不可用：' + e.message.slice(0, 60));
-    }
-    if (db) {
+    // 两个引擎都要验收：曾只测 wasm，导致 native（默认引擎）的同款竞态长期漏网。
+    for (const engineName of ['wasm_client', 'native_client']) {
+      let JSQL, db;
+      try {
+        ({ JSQL } = require('../lib/' + engineName + '.js'));
+        db = new JSQL();
+        await db.start();
+      } catch (e) {
+        console.log(`[SKIP] ${engineName} 不可用：` + e.message.slice(0, 60));
+        continue;
+      }
+      const tag = `[${engineName}]`;
       let id = 0;
       await db.createTable('conc', { id: { type: 'INT', primaryKey: true }, b: { type: 'INT' } });
       await Promise.all(Array.from({ length: 200 }, () => db.insert('conc', { id: ++id, b: 5 })));
       const cnt = await db.count('conc');
-      ok(`并发 insert 200 行 → count 恰为 200（实际 ${cnt}）`, cnt === 200);
+      ok(`${tag} 并发 insert 200 行 → count 恰为 200（实际 ${cnt}）`, cnt === 200);
 
       // flush 失败不得把坏行留在 buffer 里二次爆炸
-      ok('insert(null) 抛 TypeError', await (async () => {
+      ok(`${tag} insert(null) 抛 TypeError`, await (async () => {
         try { await db.insert('conc', null); return false; } catch (e) { return e instanceof TypeError; }
       })());
-      ok('insert(undefined) 抛 TypeError', await (async () => {
+      ok(`${tag} insert(undefined) 抛 TypeError`, await (async () => {
         try { await db.insert('conc', undefined); return false; } catch (e) { return e instanceof TypeError; }
       })());
-      ok('insert(非对象) 抛 TypeError', await (async () => {
+      ok(`${tag} insert(非对象) 抛 TypeError`, await (async () => {
         try { await db.insert('conc', 42); return false; } catch (e) { return e instanceof TypeError; }
       })());
 
@@ -246,7 +318,7 @@ async function main() {
       cyc.self = cyc;
       let cycErr = null;
       try { await db.insert('cyc', { id: 1, meta: cyc }); } catch (e) { cycErr = e; }
-      ok('环形对象给出带表/列名的错误',
+      ok(`${tag} 环形对象给出带表/列名的错误`,
         !!cycErr && /Cannot serialize column 'meta'/.test(cycErr.message),
         cycErr && cycErr.message);
       await db.stop();