jsql-neo 6.4.2 → 6.4.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, **and the browser**.
 
-> **v6.4.2** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.4.4** — official release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
 
 ![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)

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.4.2 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.4.4 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');

package/lib/sql.js

@@ -131,6 +131,40 @@ function nameOfToken(t) {
   return t && t.text !== undefined ? t.text : (t ? t.value : undefined);
 }
 
+/**
+ * 按 JSONPath 取值（$.a、$.a.b、$.a[0].b、$）。
+ *
+ * 原先是 JSON_EXTRACT 里的一段内联逻辑。`->` / `->>` 同样接受 JSONPath
+ * （MySQL 5.7+ 的写法，也是 doc/sql-reference.md 里给出的示例），
+ * 但此前把 '$' 开头的路径当成字面键名去取（v['$.name']），永远取不到 ——
+ * 所以抽出来共用，避免两处实现漂移。
+ */
+function jsonPathGet(data, path) {
+  const p = path == null ? '' : String(path);
+  if (p === '$' || p === '') return data;
+  const m = p.match(/^\$\.?([^.\[]+)/);
+  if (!m) return null;
+  let current = data;
+  for (const seg of p.replace(/^\$\.?/, '').split('.')) {
+    if (current === null || current === undefined) return null;
+    const arrMatch = seg.match(/^([^\[]*)\[(\d+)\]$/);
+    if (arrMatch) {
+      const key = arrMatch[1];
+      const idx = parseInt(arrMatch[2], 10);
+      if (key) {
+        if (typeof current !== 'object' || current === null) return null;
+        current = current[key];
+      }
+      if (!Array.isArray(current)) return null;
+      current = current[idx];
+    } else {
+      if (typeof current !== 'object' || current === null) return null;
+      current = current[seg];
+    }
+  }
+  return current === undefined ? null : current;
+}
+
 function tokenize(sql) {
   const tokens = [];
   let i = 0;
@@ -2779,6 +2813,40 @@ function rowHasPrefixedKeys(row) {
   return false;
 }
 
+/**
+ * 整棵语句树里有没有出现过「表.列」形式的限定引用。
+ *
+ * executeSelect 会给每一行调用 _prefixRow，把键复制成「表.列」形式。
+ * 单表查询里这些键根本没被引用，10 万行就是 10 万个白造对象
+ * （node --prof 显示占整个查询 30% 的 GC）。
+ *
+ * 但限定引用不一定长在 {type:/column/} 节点里 —— ORDER BY 的 o.column
+ * 就是纯字符串 "t.age"，HAVING / pushdown 的键也是。只扫对象节点会漏，
+ * 漏了就少加前缀，相关子查询和限定列全部解析错。两种形态都要查。
+ *
+ * 消费方清单（摸清这些才敢跳过前缀）：
+ *   1. resolveOperand 的 column 分支 —— 限定引用解析
+ *   2. rowHasPrefixedKeys —— 未知限定符的防自匹配守卫
+ *   3. SELECT * 的 starKeys —— 单表时取 Object.keys(schema)，与行前缀无关
+ *   4. JOIN 右表 —— 多表同名列消歧，本来就强制前缀
+ */
+const QUALIFIED_REF_RE = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+function hasQualifiedRef(node, depth) {
+  if (!node || typeof node !== "object" || depth > 200) return false;
+  if (Array.isArray(node)) {
+    for (const n of node) if (hasQualifiedRef(n, depth + 1)) return true;
+    return false;
+  }
+  if (node.type === "column" && typeof node.name === "string" && node.name.indexOf(".") !== -1) return true;
+  for (const k in node) {
+    if (k === "ctx" || k === "engine" || k === "session") continue;
+    const v = node[k];
+    if (typeof v === "string") { if (QUALIFIED_REF_RE.test(v)) return true; }
+    else if (v && typeof v === "object" && hasQualifiedRef(v, depth + 1)) return true;
+  }
+  return false;
+}
+
 /**
  * 字符串能否当作数值参与算术运算。
  * MySQL 里 '5' + 5 = 10、'5' + '5' = 10、'abc' + 1 = 1（非数字按 0）。
@@ -2986,6 +3054,14 @@ function resolveOperand(operand, row, ctx) {
       if (typeof base === 'string') {
         try { base = JSON.parse(base); } catch (e) { return null; }
       }
+      // '$' 开头是 JSONPath（MySQL 5.7+ 的写法，`d->>'$.name'`、`d->>'$.a.b'`）。
+      // 此前把它当字面键名去取（v['$.name']），于是文档里那条示例永远返回 null。
+      if (!operand.isPath && typeof operand.key === 'string' && operand.key.trim().charAt(0) === '$') {
+        const jv = jsonPathGet(base, operand.key.trim());
+        if (jv === null || jv === undefined) return null;
+        if (operand.asText) return typeof jv === 'object' ? JSON.stringify(jv) : String(jv);
+        return jv;
+      }
       const keys = operand.isPath ? parsePgPath(operand.key) : [operand.key];
       let v = base;
       for (const key of keys) {
@@ -3607,6 +3683,55 @@ function applyScalarFunction(fnNode, row, ctx) {
       return idx + 1;
     }
     case 'REVERSE': return args[0] == null ? null : String(args[0]).split('').reverse().join('');
+
+    // ---- 以下这批此前没有实现：调用时静默返回 null（不报错），
+    //      只有拿标准答案对照才发现。语义按 MySQL 8.0。
+    case 'ASCII': {
+      // 最左字符的数值；空串返回 0，NULL 返回 NULL
+      if (args[0] == null) return null;
+      const s = String(args[0]);
+      return s.length ? s.charCodeAt(0) : 0;
+    }
+    case 'ORD': {
+      if (args[0] == null) return null;
+      const s = String(args[0]);
+      return s.length ? s.codePointAt(0) : 0;
+    }
+    case 'CHAR': {
+      // CHAR(65,66) → 'AB'；跳过 NULL 参数
+      const codes = args.filter(a => a != null).map(a => Number(a));
+      if (!codes.length) return '';
+      return codes.map(n => String.fromCharCode(n)).join('');
+    }
+    case 'SPACE': {
+      if (args[0] == null) return null;
+      const n = Math.max(0, Math.floor(Number(args[0])) || 0);
+      return ' '.repeat(n);
+    }
+    case 'FIELD': {
+      // FIELD(x, a, b, ...) → x 在列表中的 1 基下标；找不到返回 0；x 为 NULL 返回 NULL
+      if (args[0] == null) return null;
+      const needle = String(args[0]);
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] != null && String(args[i]) === needle) return i;
+      }
+      return 0;
+    }
+    case 'ELT': {
+      // ELT(n, a, b, ...) → 第 n 个；越界或 n 为 NULL 返回 NULL
+      if (args[0] == null) return null;
+      const idx = Math.floor(Number(args[0]));
+      if (!Number.isFinite(idx) || idx < 1 || idx >= args.length) return null;
+      return args[idx] == null ? null : String(args[idx]);
+    }
+    case 'JSON_ARRAY_LENGTH': {
+      if (args[0] == null) return null;
+      let v = args[0];
+      if (typeof v === 'string') {
+        try { v = JSON.parse(v); } catch (e) { return null; }
+      }
+      return Array.isArray(v) ? v.length : null;
+    }
     case 'LPAD': {
       if (args[0] == null) return null;
       let s = String(args[0]);
@@ -3685,34 +3810,7 @@ function applyScalarFunction(fnNode, row, ctx) {
       if (typeof json === 'string') {
         try { data = JSON.parse(json); } catch (e) { return null; }
       }
-      // 解析 JSONPath: $.key 或 $.a.b 或 $.a[0].b
-      const m = path.match(/^\$\.?([^.\[]+)/);
-      if (!m) {
-        // 尝试 $ 开头后直接跟 key
-        if (path === '$') return data;
-        return null;
-      }
-      const firstKey = m[1];
-      if (firstKey === '') return data;
-      let current = data;
-      // 逐段解析路径
-      const segments = path.replace(/^\$\.?/, '').split('.');
-      for (const seg of segments) {
-        if (current == null) return null;
-        // 处理数组索引: key[0] 或 [0]
-        const arrMatch = seg.match(/^([^\[]*)\[(\d+)\]$/);
-        if (arrMatch) {
-          const key = arrMatch[1];
-          const idx = parseInt(arrMatch[2], 10);
-          if (key) current = current[key];
-          if (Array.isArray(current)) current = current[idx];
-          else return null;
-        } else {
-          if (typeof current !== 'object' || current === null) return null;
-          current = current[seg];
-        }
-      }
-      return current === undefined ? null : current;
+      return jsonPathGet(data, path);
     }
     case 'JSON_KEYS': {
       // JSON_KEYS(json) → [key1, key2, ...]
@@ -4255,11 +4353,22 @@ function evaluateExpr(expr, row, ctx) {
       if (v === null || v === undefined) return null;  // NULL IN (...) → NULL（三值逻辑）
       if (expr.subquery && expr.subquery._values !== undefined) expr.list = expr.subquery._values;
       if (!expr.list) return expr.not ? true : false;
-      // 列表中出现 NULL 时：三值逻辑 → NULL IN (1,2,NULL) 为 NULL（UNKNOWN）
+
+      // 先找匹配：只要有一个非 NULL 元素等于 v，整个 IN 就是 TRUE ——
+      // 列表里别的位置有没有 NULL 都不影响。
+      //
+      // 此前是先判「列表里有 NULL 就返回 NULL」，于是 `v IN (10, NULL)`
+      // 连 v=10 的行都匹配不上（实测返回 0 行，应为 2 行）。
+      // 三值逻辑里 NULL 只在**没匹配上**的时候才让结果变 UNKNOWN。
+      const matched = expr.list.some(x =>
+        x !== null && x !== undefined && (x === v || String(x) === String(v))
+      );
+      if (matched) return expr.not ? false : true;
+
+      // 没匹配上：列表里有 NULL → UNKNOWN，否则是确定的 FALSE
       const hasNull = expr.list.some(x => x === null || x === undefined);
       if (hasNull) return null;
-      const r = expr.list.some(x => x === v || String(x) === String(v));
-      return expr.not ? !r : r;
+      return expr.not ? true : false;
     }
     case 'like': {
       const v = resolveOperand(expr.operand, row, ctx);
@@ -6485,7 +6594,26 @@ class SQLExecutor {
         // 帧范围（ROWS 帧；RANGE 在当前实现下退化为整个分区，保守处理）
         const frameIdx = (i) => {
           const f = w.over.frame;
-          if (!f) return { start: 0, end: ordered.length - 1 };
+          if (!f) {
+            // 没显式写帧时的默认帧，按 SQL 标准分两种情况：
+            //   有 ORDER BY → RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+            //   无 ORDER BY → 整个分区
+            //
+            // 此前一律返回整个分区，于是
+            //   SUM(sal) OVER (PARTITION BY dept ORDER BY id)
+            // 得到的是分区总和（500）而不是累计值（100/300/500）。
+            //
+            // 用 RANGE 而非 ROWS 语义：ORDER BY 值相同的行互为 peer，
+            // 要一并纳入当前行（这正是 RANGE 与 ROWS 的区别）。
+            if (!orderBy.length) return { start: 0, end: ordered.length - 1 };
+            const curKey = this._windowPeerKey(rows[ordered[i]], orderBy, this.ctx);
+            let end = i;
+            while (end + 1 < ordered.length &&
+                   this._windowPeerKey(rows[ordered[end + 1]], orderBy, this.ctx) === curKey) {
+              end++;
+            }
+            return { start: 0, end };
+          }
           let start = 0, end = ordered.length - 1;
           const apply = (b, isStart) => {
             if (!b) return isStart ? 0 : ordered.length - 1;
@@ -6749,10 +6877,25 @@ class SQLExecutor {
             return (a && String(a).includes('.') ? String(a) : `${firstPrefix}.${a}`);
           }).filter(Boolean)
         : null;
+      /*
+       * 曾经试着在「单表 + 无 JOIN」时跳过 _prefixRow 以省掉 10 万次对象分配
+       * （node --prof 显示它占 30% GC）。实测确实快 2~3 倍，但相关子查询
+       * （EXISTS / 标量 / IN）靠 `外层表.列` 引用外层行，没前缀就解析不到，
+       * 而 _collectSubqueries 在这个位置抓不到它们（前面已被改写）。
+       * 收益真实但边界没摸清，先回退，留待摸清后再上。
+       */
+      /*
+       * 单表 + 无 JOIN + 无派生表 + 整棵树没有限定引用时，跳过前缀。
+       * 不缓存到 statement 上：语句对象可能被 prepare() 复用，挂属性会串味。
+       */
+      const needPrefix = isVirtualSource
+        || !!(statement.from.joins && statement.from.joins.length)
+        || hasQualifiedRef(statement, 0);
       let rows = isVirtualSource
         ? rowsAll.rows.map(r => this._prefixRow(r, firstPrefix))
-        : (firstItem._virtualRows ? rowsAll.rows : rowsAll.rows.map(r => this._prefixRow(r, firstPrefix)));
-
+        : (needPrefix || firstItem._virtualRows
+            ? rowsAll.rows.map(r => this._prefixRow(r, firstPrefix))
+            : rowsAll.rows);
       for (const j of statement.from.joins) {
         // 虚拟行（递归 CTE 物化的派生表）要直接取行，不能当普通子查询执行
         const jVirtual = j.item._virtualRows ||
@@ -7038,28 +7181,54 @@ class SQLExecutor {
     if (statement.orderBy) {
       // ORDER BY 项可能是列名字符串、表达式节点，或列的位置序号（ORDER BY 1，1-based）
       const ordNames = statement.columns.map(c => scalarColumnName(c));
-      const ordVal = (row, o) => {
+      /*
+       * 把排序键的解析**预先编译**，比较器里只做数组下标访问。
+       *
+       * 此前每次比较都调 `resolveOperand({type:'column', name}, row, ctx)` ——
+       * 那个对象字面量是每次新建的。6.8 万行排序约 230 万次比较，
+       * 就是 230 万次白白分配，实测占掉整个 ORDER BY 的大半时间
+       * （10 万行 WHERE+ORDER+LIMIT 从 133ms 量级大幅下降）。
+       *
+       * 同时按「投影列名 → 下标」解析；命中就直接 `row[idx]`，
+       * 不再走 resolveOperand 的通用路径。
+       */
+      const ordKeys = statement.orderBy.map(o => {
+        const dir = o.dir === 'asc' ? 1 : -1;
+        // 位置序号：ORDER BY 1
         const pos = (o.column && typeof o.column === 'object' && o.column.type === 'value' && typeof o.column.value === 'number')
           ? o.column.value
           : (typeof o.column === 'number' ? o.column : null);
         if (pos !== null && pos !== undefined) {
           const name = ordNames[pos - 1];
-          if (name !== undefined && name !== null) return resolveOperand({ type: 'column', name }, row, this.ctx);
+          return { dir, at: (name === undefined || name === null) ? () => null : (r) => (r == null ? null : r[name]) };
         }
-        return typeof o.column === 'string'
-          ? resolveOperand({ type: 'column', name: o.column }, row, this.ctx)
-          : resolveOperand(o.column, row, this.ctx);
-      };
+        if (typeof o.column === 'string') {
+          const f = o.column;
+          // 节点对象提到循环外复用 —— 此前每次比较都新建一个 {type:'column',name}
+          const node = { type: 'column', name: f };
+          return {
+            dir,
+            at: (r) => {
+              // 先按字段名直取；取不到再走 resolveOperand（点号路径、表达式等）
+              const v = (r == null) ? undefined : r[f];
+              return v !== undefined ? v : resolveOperand(node, r, this.ctx);
+            },
+          };
+        }
+        return { dir, at: (r) => resolveOperand(o.column, r, this.ctx) };
+      });
+
       const cmp = (a, b) => {
-        for (const o of statement.orderBy) {
-          const av = ordVal(a, o);
-          const bv = ordVal(b, o);
+        for (let i = 0; i < ordKeys.length; i++) {
+          const k = ordKeys[i];
+          const av = k.at(a);
+          const bv = k.at(b);
           if (av === bv || (av === undefined && bv === undefined)) continue;
-          if (av === undefined || av === null) return o.dir === 'asc' ? -1 : 1;
-          if (bv === undefined || bv === null) return o.dir === 'asc' ? 1 : -1;
+          if (av === undefined || av === null) return -1 * k.dir;
+          if (bv === undefined || bv === null) return 1 * k.dir;
           // P2-1: localeCompare 对字符串排序受 locale 影响，应使用简单字符串比较
           const r = typeof av === 'number' && typeof bv === 'number' ? av - bv : (String(av) < String(bv) ? -1 : String(av) > String(bv) ? 1 : 0);
-          if (r !== 0) return o.dir === 'asc' ? r : -r;
+          if (r !== 0) return r * k.dir;
         }
         return 0;
       };
@@ -7158,16 +7327,42 @@ class SQLExecutor {
         if (c.expr === '*') { for (const k of starKeys) cols.push(k.includes('.') ? k.slice(k.indexOf('.') + 1) : k); }
         else cols.push(scalarColumnName(c));
       }
+      /*
+       * 预先编译每列的取值函数。
+       *
+       * 此前循环里每次调用都新建 `{type:'column', name}` 对象字面量，
+       * 10 万行 × N 列就是 10 万 × N 次白分配 —— 实测光 `SELECT id FROM t`
+       * 就要 94ms，其中绝大部分是这个。
+       *
+       * 最常见的「普通列名」直接走属性访问，不再过 resolveOperand 的通用路径；
+       * 取不到值才退回（兼容点号路径、限定引用等）。
+       */
+      const starIdx = [];
+      const colGetters = statement.columns.map((c, ci) => {
+        if (c.expr === '*') { starIdx.push(ci); return null; }
+        if (c.over || (c.scalar && c.scalar.over)) return (r) => windowColumnValue(c, r);
+        if (c.scalar) return (r) => projectScalar(resolveOperand(c.scalar, r, this.ctx));
+        if (c.literal !== undefined) return () => c.literal;
+        if (c.caseExpr) return (r) => projectScalar(evaluateCaseVal(c.caseExpr, r));
+        if (typeof c.expr === 'string') {
+          const f = c.expr;
+          const node = { type: 'column', name: f };
+          return (r) => {
+            const v = (r == null) ? undefined : r[f];
+            return v === undefined ? projectScalar(resolveOperand(node, r, this.ctx)) : projectScalar(v);
+          };
+        }
+        const node2 = { type: 'column', name: c.expr };
+        return (r) => projectScalar(resolveOperand(node2, r, this.ctx));
+      });
+
       const mapped = await this._projectRows(statement, rows, (r) => {
         const out = [];
-        for (const c of statement.columns) {
-          if (c.expr === '*') {
+        for (let ci = 0; ci < colGetters.length; ci++) {
+          const g = colGetters[ci];
+          if (g === null) {
             for (const k of starKeys) out.push(r[k] !== undefined ? r[k] : r[String(k).slice(String(k).indexOf('.') + 1)]);
-          } else if (c.over || (c.scalar && c.scalar.over)) out.push(windowColumnValue(c, r));
-          else if (c.scalar) out.push(projectScalar(resolveOperand(c.scalar, r, this.ctx)));
-          else if (c.literal !== undefined) out.push(c.literal);
-          else if (c.caseExpr) out.push(projectScalar(evaluateCaseVal(c.caseExpr, r)));
-          else out.push(projectScalar(resolveOperand({ type: 'column', name: c.expr }, r, this.ctx)));
+          } else out.push(g(r));
         }
         return out;
       });

package/lib/table.js

@@ -9,6 +9,19 @@ const BTree = require('./btree');
 const { validateDateType, now } = require('./date-types');
 const { createError } = require('./errors');
 
+/**
+ * 会被 _compileMatcher 编译成快路径的操作符。
+ *
+ * 收录标准：语义简单、求值廉价，且能在编译期确定目标值。
+ * 不在表内的操作符（$inSub / $elemMatch / $textSearch / $expr / 作为值级
+ * 逻辑的 $and $or $not …）走退回路径，逐字段交给 _matchOperator，语义不变。
+ */
+const FAST_MATCH_OPS = new Set([
+    '$eq', '$ne', '$gt', '$gte', '$lt', '$lte',
+    '$in', '$nin', '$between', '$exists', '$isNull',
+    '$startsWith', '$endsWith', '$contains', '$type', '$size',
+]);
+
 function isSafeRegex(pattern) {
     if (typeof pattern !== 'string') return false;
     if (pattern.length > 256) return false;
@@ -1020,14 +1033,179 @@ class Table {
         return this._applyFilter(rows, query);
     }
 
+    /**
+     * 把 filter 编译成一个谓词函数。
+     *
+     * 动机（实测数据，10 万行）：
+     *   _matchRow 每行都要做 Object.entries(query)、Object.keys(condition)、
+     *   以及一串 startswith 判断。这部分占单次全表扫描耗时的 **98%** ——
+     *   点查 13.9ms/次，其中 13.6ms 是反射；同样语义的手写循环只要 0.28ms。
+     *   $like / $regex 更糟：正则每行每字段重编一次。
+     *
+     * 做法：编译一次，把字段、路径、操作符、正则全部预先解析好，
+     * 循环里只剩取值和比较。语义与 _matchRow 逐一对应。
+     *
+     * 遇到冷门操作符（$inSub / $elemMatch / $textSearch / $expr …）
+     * 时**只把那一个字段**退回 _matchRow，其余字段仍走快路径 ——
+     * 既保住语义，也不让混合查询整体退回。
+     */
+    _compileMatcher(query) {
+        const self = this;
+        const parts = [];
+        for (const [field, condition] of Object.entries(query)) {
+            // --- 顶层逻辑操作符 ---
+            if (field === '$or' || field === '$and') {
+                if (!Array.isArray(condition)) { parts.push({ k: 0 }); continue; }   // 原实现直接 return false
+                parts.push({ k: field === '$or' ? 3 : 4, subs: condition.map(c => self._compileMatcher(c)) });
+                continue;
+            }
+            if (field === '$not') {
+                // $not 的条件形态太多（对象/标量都合法），整体退回，保证逐字一致
+                parts.push({ k: 7, q: { $not: condition } });
+                continue;
+            }
+
+            // --- 字段路径：点号路径预先切好，循环里不再 split/includes ---
+            const path = (field.indexOf('.') !== -1 && field[0] !== '$') ? field.split('.') : null;
+
+            const plainObj = condition !== null && typeof condition === 'object'
+                && !Array.isArray(condition) && !(condition instanceof RegExp);
+
+            if (!plainObj) {
+                parts.push({ k: 1, path, field, target: condition });   // 等值
+                continue;
+            }
+
+            const keys = Object.keys(condition);
+            const isOp = keys.length > 0 && keys.every(k => k[0] === '$');
+            if (!isOp) {
+                // 嵌套对象匹配
+                parts.push({ k: 5, path, field, sub: self._compileMatcher(condition) });
+                continue;
+            }
+
+            // --- 操作符：能编译的编译，不能的整体退回这一字段 ---
+            const ops = [];
+            let ok = true;
+            for (const [op, target] of Object.entries(condition)) {
+                if (op === '$like' && typeof target === 'string') {
+                    const escaped = target
+                        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                        .replace(/%/g, '.*')
+                        .replace(/_/g, '.');
+                    ops.push({ op, re: new RegExp('^' + escaped + '$', 'i') });
+                } else if (op === '$regex' && !(target instanceof RegExp) && typeof target === 'string') {
+                    if (!isSafeRegex(target)) throw createError('ER_BAD_REGEX', String(target));
+                    ops.push({ op, re: new RegExp(target) });
+                } else if (FAST_MATCH_OPS.has(op)) {
+                    ops.push({ op, target });
+                } else {
+                    ok = false;
+                    break;
+                }
+            }
+            if (!ok) { parts.push({ k: 7, q: { [field]: condition } }); continue; }
+            parts.push({ k: 2, path, field, ops });
+        }
+
+        return function match(row) {
+            for (let i = 0; i < parts.length; i++) {
+                const p = parts[i];
+                switch (p.k) {
+                    case 1: {   // 等值
+                        const v = p.path ? self._walk(row, p.path) : row[p.field];
+                        if (v !== p.target) return false;
+                        break;
+                    }
+                    case 2: {   // 操作符
+                        const v = p.path ? self._walk(row, p.path) : row[p.field];
+                        const ops = p.ops;
+                        for (let j = 0; j < ops.length; j++) {
+                            const o = ops[j];
+                            const op = o.op;
+                            if (op === '$eq') { if (v !== o.target) return false; }
+                            else if (op === '$ne') { if (v === o.target) return false; }
+                            else if (op === '$gt') { if (!(v > o.target)) return false; }
+                            else if (op === '$gte') { if (!(v >= o.target)) return false; }
+                            else if (op === '$lt') { if (!(v < o.target)) return false; }
+                            else if (op === '$lte') { if (!(v <= o.target)) return false; }
+                            else if (op === '$in') { if (!Array.isArray(o.target) || o.target.indexOf(v) === -1) return false; }
+                            else if (op === '$nin') {
+                                // 非数组 target 时原实现返回 false（不匹配），不能当成通过
+                                if (!Array.isArray(o.target) || o.target.indexOf(v) !== -1) return false;
+                            }
+                            else if (op === '$between') {
+                                if (!Array.isArray(o.target) || o.target.length !== 2
+                                    || !(v >= o.target[0]) || !(v <= o.target[1])) return false;
+                            }
+                            else if (op === '$exists') { if (o.target ? v === undefined : v !== undefined) return false; }
+                            else if (op === '$isNull') {
+                                const isn = v === null || v === undefined;
+                                if (o.target ? !isn : isn) return false;
+                            }
+                            else if (op === '$startsWith') { if (typeof v !== 'string' || !v.startsWith(o.target)) return false; }
+                            else if (op === '$endsWith') { if (typeof v !== 'string' || !v.endsWith(o.target)) return false; }
+                            else if (op === '$contains') { if (!Array.isArray(v) || v.indexOf(o.target) === -1) return false; }
+                            else if (op === '$type') { if (typeof v !== o.target) return false; }
+                            else if (op === '$size') { if (!Array.isArray(v) || v.length !== o.target) return false; }
+                            else if (op === '$like') {
+                                if (typeof v !== 'string') return false;
+                                if (!o.re.test(v)) return false;
+                            }
+                            else if (op === '$regex') {
+                                if (o.re instanceof RegExp) { if (!o.re.test(String(v))) return false; }
+                                else if (!o.re.test(v)) return false;
+                            }
+                            else { if (!self._matchOperator(v, op, o.target)) return false; }
+                        }
+                        break;
+                    }
+                    case 3: {   // $or
+                        let hit = false;
+                        for (let j = 0; j < p.subs.length; j++) { if (p.subs[j](row)) { hit = true; break; } }
+                        if (!hit) return false;
+                        break;
+                    }
+                    case 4: {   // $and
+                        for (let j = 0; j < p.subs.length; j++) if (!p.subs[j](row)) return false;
+                        break;
+                    }
+                    case 5: {   // 嵌套对象
+                        const v = p.path ? self._walk(row, p.path) : row[p.field];
+                        if (v === null || typeof v !== 'object') return false;
+                        if (!p.sub(v)) return false;
+                        break;
+                    }
+                    case 7: {   // 退回原有逐字段求值
+                        if (!self._matchRow(row, p.q)) return false;
+                        break;
+                    }
+                    default: return false;   // k===0：原实现直接 return false
+                }
+            }
+            return true;
+        };
+    }
+
+    /** 点号路径取值，与 _resolvePath 的分支语义一致 */
+    _walk(row, parts) {
+        let v = row;
+        for (let i = 0; i < parts.length; i++) {
+            if (v === null || v === undefined) return undefined;
+            v = v[parts[i]];
+        }
+        return v;
+    }
+
     _applyFilter(rows, query) {
+        const match = this._compileMatcher(query);
+        const soft = this._softDelete;
         const result = [];
         for (let i = 0; i < rows.length; i++) {
+            const r = rows[i];
             // 软删除行不应出现在任何查询结果中
-            if (this._softDelete && rows[i]._deleted) continue;
-            if (this._matchRow(rows[i], query)) {
-                result.push(rows[i]);
-            }
+            if (soft && r._deleted) continue;
+            if (match(r)) result.push(r);
         }
         return result;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.4.2",
+  "version": "6.4.4",
   "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",
@@ -51,7 +51,7 @@
     "test:btree": "node test/btree.test.js",
     "test:native": "node test/native.test.js",
     "test:regress": "node test/regress-5.1.0.js",
-    "test:all": "node test/smoke.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/native.test.js && node test/native-multi-instance.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/wasm.test.js && node test/coverage.js && node test/regress-5.1.0.js && node test/join.test.js && node test/btree.test.js && node test/dml-constraints.test.js && node test/savepoint.test.js && node test/alter-table.test.js && node test/null-semantics.test.js && node test/identifier-keywords.test.js && node test/recursive-cte.test.js && node test/index-ddl.test.js",
+    "test:all": "node test/smoke.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/native.test.js && node test/native-multi-instance.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/wasm.test.js && node test/coverage.js && node test/regress-5.1.0.js && node test/join.test.js && node test/btree.test.js && node test/dml-constraints.test.js && node test/savepoint.test.js && node test/alter-table.test.js && node test/null-semantics.test.js && node test/identifier-keywords.test.js && node test/sql-semantics.test.js && node test/extra-coverage.test.js && node test/filter-compile.test.js && node test/recursive-cte.test.js && node test/index-ddl.test.js",
     "test:coverage": "c8 --all --include='lib/**' --exclude='lib/web_ui.js' --reporter=text --reporter=lcov node test/coverage.js",
     "test:orms": "node examples/orms/run-all.js",
     "test:dml": "node test/dml-constraints.test.js",
@@ -61,7 +61,9 @@
     "test:savepoint": "node test/savepoint.test.js",
     "test:alter": "node test/alter-table.test.js",
     "test:ident": "node test/identifier-keywords.test.js",
-    "test:null": "node test/null-semantics.test.js"
+    "test:null": "node test/null-semantics.test.js",
+    "test:semantics": "node test/sql-semantics.test.js",
+    "test:filter": "node test/filter-compile.test.js"
   },
   "keywords": [
     "database",

package/test/extra-coverage.test.js

@@ -1,7 +1,7 @@
 /*
  * extra-coverage.test.js — JSQL-neo 边界情况全覆盖测试
  *
- * 运行：npx vitest run test/extra-coverage.test.js
+ * 运行：node test/extra-coverage.test.js
  *
  * 覆盖五大类边界情况：
  *   1. SQL 语义边界（NULL、除零、精度、Unicode、日期、BETWEEN）
@@ -12,10 +12,21 @@
  */
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { test } from 'vitest';
 import assert from 'assert';
 import { createRequire } from 'module';
 
+/*
+ * 原先这里是 `import { test } from 'vitest'`。但 vitest 既不在 package.json 的
+ * 依赖里、也没安装，而这个文件又不在 test:all 里 —— 结果是这 68 个用例
+ * **从来没跑过一次**，纯摆设。死测试比没有测试更糟：它给人虚假的信心。
+ *
+ * 好在断言本来就全用 Node 内置的 assert，需要替换的只有 test 这一层。
+ * 下面这个极简 runner 行为对齐 vitest：顺序执行、逐个报结果、
+ * 有失败就以非零码退出。
+ */
+const _tests = [];
+const test = (name, fn) => { _tests.push({ name, fn }); };
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
@@ -68,9 +79,15 @@ test('NULL NOT IN (1,2) 返回 NULL（UNKNOWN）', async () => {
   assert.strictEqual(await one(q, 'SELECT NULL NOT IN (1,2)'), null);
 });
 
-test('1 IN (1,NULL) 返回 NULL（列表含 NULL → UNKNOWN）', async () => {
+test('1 IN (1,NULL) 返回 TRUE（有一个元素匹配就成立）', async () => {
   const { q } = makeDb();
-  assert.strictEqual(await one(q, 'SELECT 1 IN (1,NULL)'), null);
+  // 等价于 `1=1 OR 1=NULL` —— TRUE OR UNKNOWN 还是 TRUE。
+  // 列表里别的位置有没有 NULL 不影响；只有**没匹配上**时才是 UNKNOWN。
+  // （原先这里断言的是 null，即「列表含 NULL 就 UNKNOWN」——那是个常见误解，
+  //   MySQL / PostgreSQL 实测都返回 TRUE。）
+  assert.strictEqual(await one(q, 'SELECT 1 IN (1,NULL)'), 1);
+  assert.strictEqual(await one(q, 'SELECT 1 IN (NULL,1)'), 1);
+  assert.strictEqual(await one(q, 'SELECT 99 IN (1,NULL)'), null);
 });
 
 test('3 NOT IN (1,2) 返回 1（正常匹配）', async () => {
@@ -363,12 +380,20 @@ test('IN 子查询', async () => {
   );
 });
 
-test('IN 子查询含 NULL 导致 UNKNOWN（返回 0 行）', async () => {
+test('IN 子查询含 NULL：匹配上的行仍应返回', async () => {
   const { q } = makeDb();
   await q('CREATE TABLE t (id INT PRIMARY KEY, g INT)');
   await q('INSERT INTO t VALUES (1,1),(2,NULL)');
+  // 子查询结果是 {1, NULL}。g=1 那行匹配得上（1 IN (1,NULL) 为 TRUE），
+  // 只有 g=NULL 那行是 UNKNOWN 被过滤 —— 所以是 1 行，不是 0 行。
+  // （原先断言 0 行，把 bug 当成了预期。）
   assert.strictEqual(
     await one(q, 'SELECT COUNT(*) FROM t WHERE g IN (SELECT g FROM t)'),
+    1
+  );
+  // 反过来：NOT IN 的列表含 NULL 时恒为 UNKNOWN，一行都不返回
+  assert.strictEqual(
+    await one(q, 'SELECT COUNT(*) FROM t WHERE g NOT IN (SELECT g FROM t)'),
     0
   );
 });
@@ -567,3 +592,27 @@ test('IF 函数三值行为（NULL / 0 / 空串均为假）', async () => {
   assert.strictEqual(await one(q, "SELECT IF('', 'a', 'b')"), 'b');
   assert.strictEqual(await one(q, "SELECT IF(1, 'a', 'b')"), 'a');
 });
+
+// ---- runner：顺序执行全部用例，按 vitest 的习惯输出与退出码 ----
+;(async () => {
+  let pass = 0, fail = 0;
+  const failures = [];
+  for (const t of _tests) {
+    try {
+      await t.fn();
+      pass++;
+      console.log('[OK]  ', t.name);
+    } catch (e) {
+      fail++;
+      failures.push(t.name);
+      const msg = e && e.message ? e.message : String(e);
+      console.log('[FAIL]', t.name, '->', msg.slice(0, 130));
+    }
+  }
+  console.log(`\n${pass} passed, ${fail} failed`);
+  if (failures.length) {
+    console.log('\n失败用例：');
+    for (const n of failures) console.log('  - ' + n);
+  }
+  process.exit(fail === 0 ? 0 : 1);
+})();

package/test/filter-compile.test.js

@@ -0,0 +1,199 @@
+/*
+ * 差分模糊测试：_compileMatcher（快路径）必须与 _matchRow（原实现）逐行一致。
+ *
+ * 背景：_matchRow 每行都做 Object.entries(query) / Object.keys(condition) /
+ * 一串 startswith 判断。实测这部分占单次全表扫描耗时的 **98%** ——
+ * 10 万行点查 13.9ms/次，其中 13.6ms 是反射开销；同样语义的手写循环只要 0.28ms。
+ * $like / $regex 更糟：正则每行每字段重编一次。
+ *
+ * _compileMatcher 把这些一次性挪到循环外。语义必须一字不差 ——
+ * 这个测试用随机数据 × 随机查询做交叉验证来保证。
+ *
+ * 它抓到过真 bug：$nin 的 target 非数组时，原实现返回 false（不匹配），
+ * 而编译版一度漏判、当成通过。
+ */
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const Database = require(path.join(ROOT, 'lib/database'));
+
+let pass = 0, fail = 0;
+const failures = [];
+function ok(name, cond, extra) {
+  if (cond) { pass++; } else { fail++; failures.push(name + (extra !== undefined ? '  -> ' + JSON.stringify(extra).slice(0, 170) : '')); }
+}
+
+(async () => {
+  const db = new Database(':memory:', { autoSave: false });
+  await db.createTable('f', {
+    id: { type: 'integer', primaryKey: true },
+    num: { type: 'integer' },
+    str: { type: 'string' },
+    flt: { type: 'float' },
+    arr: { type: 'array' },
+    obj: { type: 'object' },
+  });
+  const STRS = ['a', 'ab', 'Ab', 'abc', 'b', '', 'a%b', 'a_b', 'A', 'zzz', 'aXb'];
+  const NUMS = [0, 1, 2, 3, 5, 10, -1, -5, 100, 25, 50];   // num 是 integer 列
+  const rows = [];
+  for (let i = 1; i <= 400; i++) {
+    rows.push({
+      id: i,
+      num: NUMS[i % NUMS.length],
+      str: STRS[i % STRS.length],
+      flt: (i % 17) / 2,
+      arr: i % 3 === 0 ? [1, 2, 3] : (i % 3 === 1 ? ['x', 'y'] : []),
+      obj: i % 4 === 0 ? { city: 'SH', n: i } : (i % 4 === 1 ? { city: 'BJ' } : { n: 1 }),
+    });
+  }
+  await db.insert('f', rows);
+  const t = db._tables.f;
+  const all = t._rows;
+
+  // ---- 可复现的伪随机（固定种子，失败可重放）----
+  let seed = 12345;
+  const rnd = () => { seed = (seed * 1103515245 + 12345) & 0x7fffffff; return seed / 0x7fffffff; };
+  const pick = (a) => a[Math.floor(rnd() * a.length)];
+
+  const FIELDS = ['num', 'str', 'flt', 'arr', 'obj', 'obj.city', 'id'];
+  const OPS = ['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin', '$between',
+    '$exists', '$isNull', '$startsWith', '$endsWith', '$contains', '$type', '$size',
+    '$like', '$regex'];
+
+  const genValue = (op) => {
+    switch (op) {
+      case '$in': case '$nin':
+        return [pick(NUMS), pick(STRS), pick(NUMS)].slice(0, 1 + Math.floor(rnd() * 3));
+      case '$between': return [pick(NUMS), pick(NUMS)].sort((a, b) => a - b);
+      case '$exists': case '$isNull': return rnd() < 0.5;
+      case '$type': return pick(['string', 'number', 'object', 'undefined', 'boolean']);
+      case '$size': return pick([0, 1, 2, 3]);
+      case '$startsWith': case '$endsWith': return pick(['a', 'A', 'b', 'ab', '']);
+      case '$like': return pick(['a%', '%b', 'a_b', '%', 'a%b', 'A%', '_', 'abc']);
+      case '$regex': return pick(['^a', 'b$', '[0-9]+', 'a.*b', '.']);
+      case '$gt': case '$gte': case '$lt': case '$lte': case '$eq': case '$ne':
+        return rnd() < 0.25 ? null : pick(rnd() < 0.5 ? NUMS : STRS);
+      default: return pick(NUMS);
+    }
+  };
+  const genFieldCond = () => {
+    const f = pick(FIELDS);
+    if (rnd() < 0.35) return { [f]: genValue(pick(OPS)) };
+    const ops = {};
+    const n = 1 + Math.floor(rnd() * 2);
+    for (let i = 0; i < n; i++) ops[pick(OPS)] = genValue(pick(OPS));
+    return { [f]: ops };
+  };
+  const genQuery = () => {
+    const r = rnd();
+    if (r < 0.12) return {};                                     // 空查询
+    if (r < 0.30) {                                              // $or
+      const n = 1 + Math.floor(rnd() * 3);
+      return { $or: Array.from({ length: n }, () => genFieldCond()) };
+    }
+    if (r < 0.42) {                                              // $and
+      const n = 1 + Math.floor(rnd() * 3);
+      return { $and: Array.from({ length: n }, () => genFieldCond()) };
+    }
+    if (r < 0.50) return { $not: genFieldCond() };               // $not
+    const q = {};                                                // 普通多字段
+    const n = 1 + Math.floor(rnd() * 3);
+    for (let i = 0; i < n; i++) Object.assign(q, genFieldCond());
+    return q;
+  };
+
+  // ---- 差分比对 ----
+  const N = 4000;
+  let mismatches = 0, empty = 0;
+  for (let i = 0; i < N; i++) {
+    const q = genQuery();
+    if (Object.keys(q).length === 0) empty++;
+    let fast, slow, e1 = null, e2 = null;
+    try { fast = all.filter(r => t._compileMatcher(q)(r)); } catch (e) { e1 = e.message; }
+    try { slow = all.filter(r => t._matchRow(r, q)); } catch (e) { e2 = e.message; }
+    if (e1 || e2) {
+      // 抛错行为也必须一致
+      if (!!e1 !== !!e2) { mismatches++; if (failures.length < 10) failures.push('抛错不一致 ' + JSON.stringify(q)); }
+      continue;
+    }
+    if (fast.length !== slow.length) {
+      mismatches++;
+      if (failures.length < 10) failures.push(`行数不一致 ${fast.length} vs ${slow.length} : ${JSON.stringify(q)}`);
+      continue;
+    }
+    for (let j = 0; j < fast.length; j++) {
+      if (fast[j] !== slow[j]) { mismatches++; if (failures.length < 10) failures.push('行内容不一致 ' + JSON.stringify(q)); break; }
+    }
+  }
+  ok(`差分模糊测试 ${N} 个随机查询零偏差（含 ${empty} 个空查询）`, mismatches === 0, failures.slice(0, 4));
+  console.log(`  随机查询 ${N} 个，偏差 ${mismatches}`);
+
+  // ---- 定向验证：逐个操作符 + 边界 ----
+  const dir = [
+    [{ num: 25 }, '等值'],
+    [{ num: { $eq: 25 } }, '$eq'],
+    [{ num: { $ne: 25 } }, '$ne'],
+    [{ num: { $gt: 50 } }, '$gt'],
+    [{ num: { $gte: 100 } }, '$gte'],
+    [{ num: { $lt: 0 } }, '$lt'],
+    [{ num: { $lte: 0 } }, '$lte'],
+    [{ num: { $in: [1, 25] } }, '$in'],
+    [{ num: { $nin: [1, 25] } }, '$nin'],
+    [{ num: { $nin: true } }, '$nin 非数组 target（曾在此分歧）'],
+    [{ num: { $nin: 'Ab' } }, '$nin 字符串 target'],
+    [{ num: { $in: true } }, '$in 非数组 target'],
+    [{ num: { $between: [1, 50] } }, '$between'],
+    [{ num: { $between: true } }, '$between 非数组'],
+    [{ num: { $exists: true } }, '$exists'],
+    [{ num: { $isNull: true } }, '$isNull'],
+    [{ str: { $startsWith: 'a' } }, '$startsWith'],
+    [{ str: { $endsWith: 'b' } }, '$endsWith'],
+    [{ arr: { $contains: 1 } }, '$contains'],
+    [{ arr: { $size: 3 } }, '$size'],
+    [{ obj: { $type: 'object' } }, '$type'],
+    [{ str: { $like: 'a%' } }, '$like'],
+    [{ str: { $like: 'a_b' } }, '$like _'],
+    [{ str: { $like: 'a%b' } }, '$like 转义 %'],
+    [{ str: { $regex: '^a' } }, '$regex'],
+    [{ 'obj.city': 'SH' }, '点号路径'],
+    [{ obj: { city: 'SH' } }, '嵌套对象'],
+    [{ obj: { city: 'SH', n: 1 } }, '嵌套对象两字段'],
+    [{ $or: [{ num: 1 }, { str: 'b' }] }, '$or'],
+    [{ $and: [{ num: 1 }, { str: 'a' }] }, '$and'],
+    [{ $not: { num: 1 } }, '$not'],
+    [{ num: { $gt: 0 }, str: { $startsWith: 'a' } }, '多字段'],
+    [{}, '空查询'],
+    [{ $or: [{ num: { $nin: true } }] }, '$or 内 $nin 非数组'],
+  ];
+  for (const [q, label] of dir) {
+    const fast = all.filter(r => t._compileMatcher(q)(r));
+    const slow = all.filter(r => t._matchRow(r, q));
+    ok('定向: ' + label, fast.length === slow.length && fast.every((r, i) => r === slow[i]),
+      { fast: fast.length, slow: slow.length });
+  }
+
+  // ---- 软删除模式下也必须一致 ----
+  {
+    await db.query('DELETE FROM f WHERE id <= 40', { safety: false });
+    const q = { num: 25 };
+    const fast = t._applyFilterOptimized(t._getVisibleRows(), q);
+    const slow = t._rows.filter(r => !r._deleted).filter(r => t._matchRow(r, q));
+    ok('软删除模式下一致', fast.length === slow.length && fast.every((r, i) => r === slow[i]),
+      { fast: fast.length, slow: slow.length });
+  }
+
+  // ---- LIKE / REGEX 的正则只编译一次（性能回归护栏）----
+  {
+    const q = { str: { $like: 'a%' } };
+    const m = t._compileMatcher(q);
+    const t0 = Date.now();
+    for (let i = 0; i < 300; i++) all.filter(r => m(r));
+    const ms = Date.now() - t0;
+    ok(`编译版 LIKE 300 次全表扫描在 ${ms}ms 内（原实现每行重编正则）`, ms < 1500, ms);
+    console.log(`  编译版 LIKE ×300 全表扫描: ${ms}ms`);
+  }
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  if (failures.length) { console.log('\n失败项:'); failures.slice(0, 15).forEach(f => console.log('  - ' + f)); }
+  process.exit(fail === 0 ? 0 : 1);
+})().catch(e => { console.error('💥', e); process.exit(1); });

package/test/sql-semantics.test.js

@@ -0,0 +1,131 @@
+/*
+ * SQL 语义修正测试（IN 的三值逻辑 / 窗口默认帧 / JSON 路径操作符 / 补齐的标量函数）。
+ *
+ * 这一批全是「不报错、结果错」——静默失败最难发现，靠拿标准答案逐条对照才挖出来。
+ *
+ *   1. IN 列表里含 NULL 时整体失效：`v IN (10, NULL)` 连 v=10 的行都匹配不上。
+ *      正确语义是 `v=10 OR v=NULL` —— 有一个元素匹配就是 TRUE，
+ *      列表里别的位置有没有 NULL 都不影响；只有**没匹配上**时才变 UNKNOWN。
+ *   2. 窗口函数默认帧算错：`SUM(x) OVER (ORDER BY id)` 返回分区总和而不是累计值。
+ *      SQL 标准：有 ORDER BY 且未指定帧 → RANGE UNBOUNDED PRECEDING TO CURRENT ROW。
+ *   3. `d->>'$.name'`（文档里给的示例）永远返回 null —— 求值层把 '$' 开头的
+ *      JSONPath 当成字面键名去取了。纯键名写法 `d->>'name'` 一直是对的。
+ *   4. ASCII / CHAR / SPACE / FIELD / ELT / JSON_ARRAY_LENGTH 根本没实现，
+ *      调用时静默返回 null。
+ */
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const { Database } = require(path.join(ROOT, 'index.js'));
+const { executeSQL } = require(path.join(ROOT, 'lib/sql.js'));
+
+const OPTS = { safety: false };
+let pass = 0, fail = 0;
+
+function ok(name, cond, extra) {
+  if (cond) { pass++; console.log('[OK]  ', name); }
+  else { fail++; console.log('[FAIL]', name, extra !== undefined ? '-> ' + JSON.stringify(extra).slice(0, 150) : ''); }
+}
+const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+(async () => {
+  const db = new Database(':memory:');
+  const q = (sql) => executeSQL(db, sql, OPTS);
+  const rows = async (sql) => (await q(sql)).rows;
+  const one = async (sql) => (await q(sql)).rows[0][0];
+
+  await q('CREATE TABLE t (id INT PRIMARY KEY, g TEXT, v INT, s TEXT)');
+  await q(`INSERT INTO t VALUES
+    (1,'a',10,'x'),(2,'a',20,'y'),(3,'b',10,NULL),(4,'b',30,'x'),(5,NULL,20,'y'),(6,NULL,NULL,'z')`);
+
+  console.log('\n--- IN 的三值逻辑 ---');
+  ok('v IN (10) 正常匹配', eq(await rows('SELECT COUNT(*) FROM t WHERE v IN (10)'), [[2]]));
+  ok('v IN (10, NULL) 仍能匹配 v=10（关键用例）',
+    eq(await rows('SELECT COUNT(*) FROM t WHERE v IN (10, NULL)'), [[2]]),
+    await rows('SELECT COUNT(*) FROM t WHERE v IN (10, NULL)'));
+  ok('NULL 在列表开头也一样', eq(await rows('SELECT COUNT(*) FROM t WHERE v IN (NULL, 10)'), [[2]]));
+  ok('多个非 NULL 元素', eq(await rows('SELECT COUNT(*) FROM t WHERE v IN (10,20,30)'), [[5]]));
+  ok('v IN (NULL) 恒为空集', eq(await rows('SELECT COUNT(*) FROM t WHERE v IN (NULL)'), [[0]]));
+  ok('v NOT IN (10)', eq(await rows('SELECT COUNT(*) FROM t WHERE v NOT IN (10)'), [[3]]));
+  ok('v NOT IN (10, NULL) 恒为空集（UNKNOWN 取反仍是 UNKNOWN）',
+    eq(await rows('SELECT COUNT(*) FROM t WHERE v NOT IN (10, NULL)'), [[0]]));
+  ok('与等价的 OR 写法结果一致',
+    eq(await rows('SELECT COUNT(*) FROM t WHERE v = 10 OR v = NULL'),
+      await rows('SELECT COUNT(*) FROM t WHERE v IN (10, NULL)')));
+  ok('字符串 IN 含 NULL', eq(await rows("SELECT COUNT(*) FROM t WHERE s IN ('x', NULL)"), [[2]]));
+  ok('字面量 "null" 不会被 NULL 误匹配',
+    eq(await rows("SELECT COUNT(*) FROM t WHERE s IN ('null')"), [[0]]));
+  ok('子查询 IN（结果含 NULL）',
+    eq(await rows('SELECT COUNT(*) FROM t WHERE v IN (SELECT v FROM t WHERE v = 10 OR v IS NULL)'), [[2]]));
+  ok('NOT IN 子查询含 NULL → 空集',
+    eq(await rows('SELECT COUNT(*) FROM t WHERE v NOT IN (SELECT v FROM t WHERE v = 10 OR v IS NULL)'), [[0]]));
+
+  console.log('\n--- 窗口函数默认帧 ---');
+  await q('CREATE TABLE e (id INT PRIMARY KEY, dept TEXT, sal INT)');
+  await q(`INSERT INTO e VALUES (1,'a',100),(2,'a',200),(3,'a',200),(4,'b',50),(5,'b',300)`);
+  ok('SUM OVER (ORDER BY) 是累计值（关键用例）',
+    eq(await rows('SELECT id, SUM(sal) OVER (PARTITION BY dept ORDER BY id) s FROM e ORDER BY id'),
+      [[1,100],[2,300],[3,500],[4,50],[5,350]]),
+    await rows('SELECT id, SUM(sal) OVER (PARTITION BY dept ORDER BY id) s FROM e ORDER BY id'));
+  ok('无 ORDER BY 时是整分区总和',
+    eq(await rows('SELECT id, SUM(sal) OVER (PARTITION BY dept) s FROM e ORDER BY id'),
+      [[1,500],[2,500],[3,500],[4,350],[5,350]]));
+  ok('无分区无排序 = 全表总和',
+    eq(await rows('SELECT id, SUM(sal) OVER () s FROM e ORDER BY id'),
+      [[1,850],[2,850],[3,850],[4,850],[5,850]]));
+  ok('COUNT OVER (ORDER BY) 累计',
+    eq(await rows('SELECT id, COUNT(*) OVER (ORDER BY id) c FROM e ORDER BY id'),
+      [[1,1],[2,2],[3,3],[4,4],[5,5]]));
+  ok('AVG OVER (ORDER BY) 累计',
+    eq(await rows("SELECT id, AVG(sal) OVER (PARTITION BY dept ORDER BY id) a FROM e WHERE dept='a' ORDER BY id"),
+      [[1,100],[2,150],[3,166.66666666666666]]));
+  ok('默认帧按 RANGE 语义：同值 peer 一并纳入',
+    eq(await rows("SELECT id, SUM(sal) OVER (PARTITION BY dept ORDER BY sal) s FROM e WHERE dept='a' ORDER BY id"),
+      [[1,100],[2,500],[3,500]]));
+  ok('显式 ROWS 帧不受 peer 影响',
+    eq(await rows("SELECT id, SUM(sal) OVER (PARTITION BY dept ORDER BY sal ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) s FROM e WHERE dept='a' ORDER BY id"),
+      [[1,100],[2,300],[3,500]]));
+  ok('ROW_NUMBER 不受默认帧影响',
+    eq(await rows('SELECT id, ROW_NUMBER() OVER (PARTITION BY dept ORDER BY sal DESC, id) r FROM e ORDER BY id'),
+      [[1,3],[2,1],[3,2],[4,2],[5,1]]));
+
+  console.log('\n--- JSON 路径操作符 ---');
+  await q('CREATE TABLE j (id INT PRIMARY KEY, d TEXT)');
+  await q(`INSERT INTO j VALUES (1,'{"name":"ann","n":5,"addr":{"city":"SH"},"arr":[10,20]}')`);
+  ok("d->>'$.name'（文档里的写法）", await one("SELECT d->>'$.name' FROM j") === 'ann');
+  ok("d->'$.name'", await one("SELECT d->'$.name' FROM j") === 'ann');
+  ok("d->>'$.n' 数字转文本", await one("SELECT d->>'$.n' FROM j") === '5');
+  ok("d->'$.n' 保留数字类型", await one("SELECT d->'$.n' FROM j") === 5);
+  ok("d->>'$.addr.city' 嵌套", await one("SELECT d->>'$.addr.city' FROM j") === 'SH');
+  ok("d->'$.addr' 返回对象", eq(await one("SELECT d->'$.addr' FROM j"), { city: 'SH' }));
+  ok("d->>'$.arr[1]' 数组下标", await one("SELECT d->>'$.arr[1]' FROM j") === '20');
+  ok("d->>'$.nope' 不存在 → null", await one("SELECT d->>'$.nope' FROM j") === null);
+  ok("纯键名写法不受影响 d->>'name'", await one("SELECT d->>'name' FROM j") === 'ann');
+  ok("链式 d->'addr'->>'city'", await one("SELECT d->'addr'->>'city' FROM j") === 'SH');
+  ok('JSON_EXTRACT 未受影响',
+    await one("SELECT JSON_EXTRACT(d,'$.addr.city') FROM j") === 'SH');
+  ok("JSON_EXTRACT '$' 取根", eq(await one("SELECT JSON_EXTRACT('{\"a\":1}','$')"), { a: 1 }));
+
+  console.log('\n--- 补齐的标量函数 ---');
+  ok("ASCII('A')", await one("SELECT ASCII('A')") === 65);
+  ok("ASCII('abc')", await one("SELECT ASCII('abc')") === 97);
+  ok("ASCII('') 为 0", await one("SELECT ASCII('')") === 0);
+  ok('ASCII(NULL) 为 NULL', await one('SELECT ASCII(NULL)') === null);
+  ok('CHAR(65)', await one('SELECT CHAR(65)') === 'A');
+  ok('CHAR 多参数', await one('SELECT CHAR(72,105)') === 'Hi');
+  ok('SPACE(3)', await one('SELECT LENGTH(SPACE(3))') === 3);
+  ok('SPACE(0)', await one('SELECT LENGTH(SPACE(0))') === 0);
+  ok("FIELD 命中", await one("SELECT FIELD('b','a','b','c')") === 2);
+  ok('FIELD 未命中为 0', await one("SELECT FIELD('z','a','b')") === 0);
+  ok('FIELD(NULL) 为 NULL', await one("SELECT FIELD(NULL,'a')") === null);
+  ok('ELT 命中', await one("SELECT ELT(2,'a','b','c')") === 'b');
+  ok('ELT 越界为 NULL', await one("SELECT ELT(9,'a','b')") === null);
+  ok('ELT(0) 为 NULL', await one("SELECT ELT(0,'a','b')") === null);
+  ok('JSON_ARRAY_LENGTH', await one("SELECT JSON_ARRAY_LENGTH('[1,2,3]')") === 3);
+  ok('JSON_ARRAY_LENGTH 非数组 → NULL',
+    await one("SELECT JSON_ARRAY_LENGTH('{\"a\":1}')") === null);
+  ok('JSON_ARRAY_LENGTH 空数组', await one("SELECT JSON_ARRAY_LENGTH('[]')") === 0);
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail === 0 ? 0 : 1);
+})().catch(e => { console.error('💥', e); process.exit(1); });