jsql-neo 6.5.26 → 6.5.29

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.5.26** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.29** — stable release · [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)
@@ -171,6 +171,31 @@ await db.start();
 
 ---
 
+## Query results
+
+`db.query()` / `executeSQL()` return **one result in three shapes**:
+
+```js
+const r = await db.query('SELECT city, COUNT(*) AS c FROM users GROUP BY city');
+r.columns   // ['city', 'c']
+r.rows      // [['LA', 1], ['NY', 2]]
+r.raw       // [{ city: 'LA', c: 1 }, { city: 'NY', c: 2 }]
+```
+
+`raw` is the object form of `rows`: its keys are exactly `columns`, and that
+includes computed, aggregate and scalar-subquery columns. It is **not** the
+pre-projection source row. For SELECT results `raw.length === rows.length`
+always holds; non-SELECT statements may omit `raw`.
+
+To check which native addon this installation is actually using:
+
+- `jsql native status` — tag/version match (`0` = OK, `1` = mismatch or unverified)
+- `jsql native verify` — re-hashes the `.node` on disk against the checksum recorded
+  at install time, so a swapped or corrupted binary is caught too. `--json` prints
+  a structured result for CI. States: `OK` / `MISMATCH` / `CORRUPT` / `MISSING` /
+  `UNVERIFIED` / `UNREADABLE`.
+- `jsql native refresh` — re-fetches a checksum-verified addon
+
 ## ✨ XQL 集成
 
 用 [XQL](https://github.com/vexify-org/XQL) 查询 JSQL 表：把 SQL 直接接到文档上，

package/bin/jsql

@@ -531,6 +531,38 @@ const cli = (yaggs || require('./yaggs-fallback').buildYaggsFallback(_pkg))({
   .command('update', 'Update jsql-neo to the latest version', updateOptions, updateHandler)
   .command('uninstall', 'Remove jsql user data and/or the global package', uninstallOptions, uninstallHandler)
   .command('remove', 'Alias of uninstall', uninstallOptions, uninstallHandler)
+  .command('native', 'Inspect or refresh the Rust native addon', (sub) => {
+    sub.option('json', { type: 'boolean', description: 'Machine-readable output (verify only)' });
+  }, async (argv) => {
+    const action = argv._[0] || 'status';
+    const pi = require('../postinstall.js');
+    if (action === 'verify') {
+      // 内容级：重算 .node 的 SHA256 与安装记录比对，status 只看 tag 发现不了替换/损坏
+      const r = pi.verifyNative();
+      if (argv.json) {
+        console.log(JSON.stringify(r, null, 2));
+      } else {
+        console.log(`[jsql-neo] VERIFY : ${r.state}`);
+        console.log(`[jsql-neo] tag    : ${r.installedTag || 'unknown'}  (expect ${r.expectedTag})`);
+        console.log(`[jsql-neo] sha256 : ${r.actualSha256 || 'n/a'}`);
+        if (r.state !== 'OK') console.log('[jsql-neo] refresh with: jsql native refresh');
+      }
+      process.exitCode = r.state === 'OK' ? 0 : 1;
+      return;
+    }
+    if (action === 'status') {
+      // 0 = 当前 .node 与包版本匹配；1 = 错配 / 未记录（可直接当 CI 门禁）
+      process.exitCode = pi.nativeStatus();
+      return;
+    }
+    if (action === 'refresh') {
+      await pi.ensureNativeNode();
+      process.exitCode = pi.nativeStatus();
+      return;
+    }
+    console.error(`Unknown native action: ${action}. Usage: jsql native <status|refresh|verify>`);
+    process.exitCode = 1;
+  })
   .command('version', 'Show version', null, () => {
     console.log(require('../package.json').version);
   })

package/index.d.ts

@@ -272,9 +272,16 @@ declare namespace JSQLNeo {
     ok: boolean;
     type: string;
     table?: string | null;
+    /** 投影列名；rows[i][j] 与 columns[j] 一一对应。 */
     columns?: string[];
+    /** 投影后的二维数组形式。 */
     rows?: unknown[][];
-    raw?: unknown[];
+    /**
+     * 与 rows 指向**同一份结果**的对象形式：raw[i] 的键恰好是 columns，
+     * 值取自 rows[i]。聚合 / 计算列 / 标量子查询都包含在内（issue #43）。
+     * 非 SELECT 语句可能没有此字段。
+     */
+    raw?: Array<Record<string, unknown>>;
     affectedRows?: number;
     insertId?: number | null;
     ids?: unknown[];

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.5.26 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.29 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');
@@ -153,6 +153,10 @@ module.exports = {
     SQL: sql,
     executeSQL: sql.executeSQL,
     parseSQL: sql.parseSQL,
+    // Issue #46：index.d.ts 早就声明了这三个顶层导出，index.js 却一直没给
+    applyParams: sql.applyParams,
+    escapeValue: sql.escapeValue,
+    escapeId: sql.escapeId,
     // AST 访问与改写（5.5.0+）
     AST: sql.AST,
     walk: sql.walk,

package/lib/ast.js

@@ -128,40 +128,47 @@ function transform(ast, fn) {
   return visit(ast);
 }
 
-/** 原地改写：fn(node) 返回值非 undefined 时替换原节点。 */
+/**
+ * 原地改写：fn(node) 返回值非 undefined 时替换原节点。
+ *
+ * 根节点同样可替换（#58）：此前 visit 只在 `parent && key` 时才调用 fn 并回写，
+ * 根节点 parent===null 一律被跳过，于是 rewrite 无法替换整棵树，而 transform 可以。
+ * 现在数组容器本身作为父级传入（数组元素按 index 回写），根节点替换通过
+ * 返回值交回调用方。
+ */
 function rewrite(ast, fn) {
   const seen = new Set();
+  let root = ast;
+
+  const assign = (parent, key, value) => {
+    if (parent === null || parent === undefined) { root = value; return; }
+    parent[key] = value;
+  };
 
-  const visit = (value, parent, key, index) => {
+  const visit = (value, parent, key) => {
     if (value === null || typeof value !== 'object') {
-      if (parent && key) {
-        const r = fn(value);
-        if (r !== undefined) {
-          if (index === undefined) parent[key] = r; else parent[key][index] = r;
-        }
-      }
+      const r = fn(value);
+      if (r !== undefined) assign(parent, key, r);
       return;
     }
     if (seen.has(value)) return;
     seen.add(value);
 
     if (Array.isArray(value)) {
-      for (let i = 0; i < value.length; i++) visit(value[i], parent, key, i);
+      for (let i = 0; i < value.length; i++) visit(value[i], value, i);
       return;
     }
 
     for (const k of childKeys(value)) visit(value[k], value, k);
 
-    if (isNode(value) && parent && key) {
+    if (isNode(value)) {
       const r = fn(value);
-      if (r !== undefined) {
-        if (index === undefined) parent[key] = r; else parent[key][index] = r;
-      }
+      if (r !== undefined) assign(parent, key, r);
     }
   };
 
   visit(ast, null, null);
-  return ast;
+  return root;
 }
 
 /** 语句引用的所有表名（含 JOIN / 子查询）。 */

package/lib/btree.js

@@ -296,31 +296,37 @@ class BTree {
     remove(key, rowIndex) {
         if (!this._root) return false;
         const removed = this._removeFromNode(this._root, key, rowIndex);
-        // 删掉整个键（而非仅删某个 rowIndex）后，叶子的键域可能缩小，
-        // 沿途的分隔键副本可能已指向不存在的键 —— 自顶向下重建一次。
-        if (removed) {
+        // 返回值区分三种情况：
+        //   0        → 什么都没删（key 或 rowIndex 不存在）
+        //   1 / 'key'→ 整个键被删掉（该 key 的最后一个 rowIndex）
+        //   2 / 'row'→ 只删掉该 key 下的某一行，键仍在（#53）
+        // size 统计的是 distinct keys，所以只有「键消失」时才递减。
+        if (removed === 2) {
+            // 键仍存在，size 不变；分隔键也无需重建
+        } else if (removed) {
             this._size--;
             if (!this._root.leaf) this._fixSeparators(this._root);
         }
         if (this._root.keys.length === 0 && !this._root.leaf && this._root.children.length > 0) {
             this._root = this._root.children[0];
         }
-        return removed;
+        // 对外契约是布尔值：删掉了行就是 true（此前重复 key 场景错误地返回 false）
+        return !!removed;
     }
 
     _removeFromNode(node, key, rowIndex) {
         if (node.leaf) {
             const i = this._lowerBound(node.keys, key);
-            if (i >= node.keys.length || node.keys[i] !== key) return false;
-            if (!node.values[i].includes(rowIndex)) return false;
+            if (i >= node.keys.length || node.keys[i] !== key) return 0;
+            if (!node.values[i].includes(rowIndex)) return 0;
             const vals = node.values[i].filter(v => v !== rowIndex);
             if (vals.length === 0) {
                 node.keys.splice(i, 1);
                 node.values.splice(i, 1);
-                return true;
+                return 1;
             }
             node.values[i] = vals;
-            return false;
+            return 2;
         }
 
         let i = this._route(node, key);

package/lib/database.js

@@ -1837,7 +1837,11 @@ class Database {
 
     _resolveId(table, id) {
         const pk = this._pkOf(table);
-        if (pk) return table._rows.find(r => r[pk] === id) || null;
+        if (pk) {
+            // Issue #44：主键查询值按列类型归一（'5' → 5），与索引/insert 保持一致
+            const key = typeof table._coerceQueryValue === 'function' ? table._coerceQueryValue(pk, id) : id;
+            return table._rows.find(r => r[pk] === key || r[pk] === id) || null;
+        }
         // 无主键表：id 是行对象（可能是 find() 返回的浅拷贝）时，用内容匹配代替引用比较。
         // 做法：逐行比对所有字段值是否相等；是数字时当 1-based 行号。
         if (id && typeof id === 'object') {

package/lib/date-types.js

@@ -35,6 +35,25 @@ function validateDateType(value, type, fieldName) {
 
 function pad2(n) { return String(n).padStart(2, '0'); }
 
+/**
+ * 解析 ISO-8601 字符串尾部残余部分里的时区标记，返回「相对 UTC 的分钟偏移」。
+ * 输入形如 'Z'、'z'、'+08:00'、'-0500'、'.500Z'、' +02:00'。
+ * 没有时区标记（或无法识别）返回 null —— 调用方按本地时间字面值处理。
+ */
+function parseIsoTimezone(rest) {
+    let s = String(rest == null ? '' : rest).trim();
+    // 去掉小数秒
+    if (s.startsWith('.')) s = s.replace(/^\.\d+/, '');
+    if (s === 'Z' || s === 'z') return 0;
+    const m = s.match(/^([+-])(\d{2}):?(\d{2})$/);
+    if (!m) return null;
+    const hh = parseInt(m[2], 10);
+    const mm = parseInt(m[3], 10);
+    if (hh > 23 || mm > 59) return null;   // 非法偏移：交给后续校验报错
+    const sign = m[1] === '-' ? -1 : 1;
+    return sign * (hh * 60 + mm);
+}
+
 /**
  * 本地时区的 'YYYY-MM-DD'。
  * 不能用 toISOString().slice(0,10) —— 那是 UTC：东八区 2023-01-01 00:00 本地
@@ -115,7 +134,7 @@ function validateDateTime(value, fieldName) {
         return toLocalDateTimeString(new Date(value * 1000));
     }
     if (typeof value === 'string') {
-        // ISO format: 2024-01-15T10:30:00.000Z（带时区标记，按字面取日期+时间）
+        // ISO format: 2024-01-15T10:30:00.000Z / +08:00（可能带时区标记）
         const isoMatch = value.match(/^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})/);
         if (isoMatch) {
             // P2-35: 验证日期和时间有效性
@@ -129,6 +148,15 @@ function validateDateTime(value, fieldName) {
                 const dt = new Date(y, mo - 1, d);
                 if (dt.getFullYear() === y && dt.getMonth() === mo - 1 && dt.getDate() === d &&
                     h >= 0 && h < 24 && mi >= 0 && mi < 60 && s >= 0 && s < 60) {
+                    // #50：带 Z / ±HH:MM 时区标记时必须换算到本地时区。
+                    // 此前无条件按字面值存储，'2024-01-15T10:30:00Z'（UTC）在 UTC+8
+                    // 会被存成本地 10:30，整体偏 8 小时。
+                    const tz = parseIsoTimezone(value.slice(isoMatch[0].length));
+                    if (tz !== null) {
+                        const ms = Date.UTC(y, mo - 1, d, h, mi, s) - tz * 60000;
+                        return toLocalDateTimeString(new Date(ms));
+                    }
+                    // 无时区标记：按本地时间字面值（MySQL 语义）
                     return datePart + ' ' + timePart;
                 }
             }

package/lib/mongo_server.js

@@ -430,9 +430,16 @@ class MongoServer {
         for (const d of docs) {
           const doc2 = { ...d };
           // 检查 _id 唯一性
+          // Issue #44：索引查找是严格相等的，空结果不能直接当「不存在」——
+          // 查询值与已存值的类型不一致时会漏判。这里再加一道按 schema 归一的直接扫描。
           if (doc2._id !== undefined) {
             const existing = await engine.find(coll, { _id: doc2._id });
             if (existing.length > 0) continue; // 跳过重复 _id
+            const table = typeof engine._ensureTable === 'function' ? engine._ensureTable(coll) : null;
+            if (table && Array.isArray(table._rows) && typeof table._coerceQueryValue === 'function') {
+              const idKey = table._coerceQueryValue('_id', doc2._id);
+              if (table._rows.some((r) => r && !r._deleted && r._id === idKey)) continue;
+            }
           }
           await engine.insert(coll, doc2);
           ids.push(doc2._id);
@@ -568,10 +575,13 @@ class MongoServer {
               for (const [k, dir] of sortKeys) {
                 const av = a[k]; const bv = b[k];
                 if (av === bv) continue;
-                if (av == null) return 1;
-                if (bv == null) return -1;
+                const desc = Number(dir) < 0;
+                // Issue #47：NULL 的位置随排序方向走（升序在前、降序在后），
+                // 与 MongoDB 一致；此前固定返回 1/-1，升序时 null 恒排最后。
+                if (av == null) return desc ? 1 : -1;
+                if (bv == null) return desc ? -1 : 1;
                 const cmp = av < bv ? -1 : 1;
-                return Number(dir) < 0 ? -cmp : cmp;
+                return desc ? -cmp : cmp;
               }
               return 0;
             });
@@ -643,8 +653,14 @@ class MongoServer {
                         const sum = grow.reduce((s, r) => s + (Number(r[field]) || 0), 0);
                         doc[k] = (doc[k] || 0) + sum;
                       } else if (v.$avg !== undefined) {
-                        const vals = grow.map(r => Number(r[field]) || 0);
-                        doc[k] = vals.reduce((a, b) => a + b, 0) / vals.length;
+                        // Issue #45：null/undefined 不计入分子的同时也不计入分母；
+                        // 全空组返回 null（MongoDB 语义），而不是 0。
+                        const vals = grow
+                          .map(r => r[field])
+                          .filter(x => x !== null && x !== undefined)
+                          .map(Number)
+                          .filter(x => !Number.isNaN(x));
+                        doc[k] = vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : null;
                       } else if (v.$min !== undefined) {
                         const vals = grow.map(r => r[field]).filter(v => v != null);
                         let best = null;

package/lib/mysql_compat.js

@@ -20,7 +20,7 @@ function toResultPacket(r, table, rowsAsArray) {
     const fields = columns.map(name => {
       let type = 253; // VAR_STRING
       const val = rawRows[0] ? rawRows[0][columns.indexOf(name)] : null;
-      if (typeof val === 'number') type = 8; // LONGLONG
+      if (typeof val === 'number') type = Number.isInteger(val) ? 8 : 5; // LONGLONG / DOUBLE（Issue #48：浮点列曾被误报为 8）
       else if (typeof val === 'boolean') type = 1; // TINY
       else if (val instanceof Date) type = 12; // DATETIME
       else if (Buffer.isBuffer(val)) type = 252; // BLOB

package/lib/query.js

@@ -6,6 +6,36 @@
 
 const { createError } = require('./errors');
 
+/**
+ * 稳定序列化（#55）：把查询参数变成可比较的缓存键。
+ * 普通对象的键排序，函数/RegExp/BigInt/Date 保留可辨识信息，循环引用截断。
+ */
+function stableKey(value, seen) {
+    seen = seen || new Set();
+    if (value === null) return 'null';
+    const t = typeof value;
+    if (t === 'bigint') return value.toString() + 'n';
+    if (t === 'number') return Object.is(value, -0) ? '-0' : String(value);
+    if (t === 'string') return JSON.stringify(value);
+    if (t === 'boolean') return String(value);
+    if (t === 'undefined') return 'undefined';
+    if (t === 'function') return 'fn:' + String(value);
+    if (t === 'symbol') return 'sym:' + String(value);
+    if (value instanceof RegExp) return 're:' + value.source + '/' + value.flags;
+    if (value instanceof Date) return 'date:' + value.getTime();
+    if (seen.has(value)) return '[circular]';
+    seen.add(value);
+    let out;
+    if (Array.isArray(value)) {
+        out = '[' + value.map(v => stableKey(v, seen)).join(',') + ']';
+    } else {
+        out = '{' + Object.keys(value).sort()
+            .map(k => JSON.stringify(k) + ':' + stableKey(value[k], seen)).join(',') + '}';
+    }
+    seen.delete(value);
+    return out;
+}
+
 class Query {
     constructor(table, conditions = {}) {
         this._table = table;
@@ -210,12 +240,46 @@ class Query {
     // 缓存
     // ============================================================
 
+    /**
+     * 缓存键（#55）：必须覆盖所有影响结果的参数。
+     * 旧实现只按 TTL 判断，同一 Query 实例换 where/orderBy/limit/offset 后
+     * 仍命中旧缓存，返回过期结果。
+     */
+    _cacheKey(depth = 0) {
+        if (depth > 5) return '[deep]';
+        const joins = this._joins.map(j => ({
+            type: j.type,
+            table: j.table && (j.table._name || j.table.name) || j.table,
+            localField: j.localField,
+            foreignField: j.foreignField,
+            as: j.as,
+        }));
+        return stableKey({
+            table: this._table && this._table._name,
+            conditions: this._conditions,
+            orderBy: this._orderBy,
+            limit: this._limitCount,
+            offset: this._offsetCount,
+            select: this._selectFields,
+            groupBy: this._groupBy,
+            having: this._having,
+            distinct: this._distinct,
+            distinctField: this._distinctField,
+            joins,
+            union: this._union ? this._union._cacheKey(depth + 1) : null,
+            caseExpr: this._caseExpr,
+            caseAs: this._caseAs,
+            window: this._window,
+            forUpdate: this._forUpdate,
+        });
+    }
+
     /**
      * 缓存查询结果
      * @param {number} ttlMs - 缓存有效期（毫秒），默认 60000
      */
     cache(ttlMs = 60000) {
-        this._cache = { ttl: ttlMs, result: null, timestamp: 0 };
+        this._cache = { ttl: ttlMs, result: null, timestamp: 0, key: null };
         return this;
     }
 
@@ -227,8 +291,11 @@ class Query {
         const startTime = Date.now();
         if (this._explain) return this._getExplain();
 
+        // 缓存键要包含 where/orderBy/limit/offset 等全部参数（#55）
+        const cacheKey = this._cache ? this._cacheKey() : null;
         // 缓存命中: 返回每行的浅拷贝，与未命中路径一致，避免调用方修改污染缓存
-        if (this._cache && this._cache.result && (Date.now() - this._cache.timestamp < this._cache.ttl)) {
+        if (this._cache && this._cache.result && this._cache.key === cacheKey &&
+            (Date.now() - this._cache.timestamp < this._cache.ttl)) {
             // #37：命中返回副本，而不是内部数组引用——调用方对返回值做变更
             // （push/splice/改字段）会污染缓存；未命中路径返回的是新数组，行为应一致。
             return this._cache.result.map(row => (row && typeof row === 'object' ? { ...row } : row));
@@ -334,6 +401,7 @@ class Query {
         if (this._cache) {
             this._cache.result = rows.map(row => (row && typeof row === 'object' ? { ...row } : row));
             this._cache.timestamp = Date.now();
+            this._cache.key = cacheKey;
         }
 
         this._table._db._logSlowQuery(`get ${this._table._name}`, Date.now() - startTime, rows.length);
@@ -428,6 +496,7 @@ class Query {
         if (this._cache) {
             this._cache.result = null;
             this._cache.timestamp = 0;
+            this._cache.key = null;
         }
         return this;
     }