jsql-neo 6.5.22 → 6.5.24

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.22** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.24** — 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)

package/index.js

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

package/lib/bigint_json.js

@@ -0,0 +1,39 @@
+// © Vexify 2026 All Rights Reserved.
+/**
+ * BigInt 安全的 JSON 序列化（Issue #38）。
+ *
+ * 行数据里可能出现 >2^53 的 BigInt（integer/int/bigint 列）。原生
+ * JSON.stringify 遇到 BigInt 直接抛 "Do not know how to serialize a BigInt"，
+ * 于是 WAL、事务快照、统计等路径会整条失败。
+ *
+ * 这里用一个单键标记对象 `{ __jsql_bigint__: "9223372036854775807" }`
+ * 在 JSON 中无损往返；反序列化时还原成 BigInt。只有「对象恰好只有这一个键」
+ * 时才还原，尽量避免误伤用户自己的同名字段。
+ */
+
+const MARKER = '__jsql_bigint__';
+
+function replacer(_key, value) {
+    if (typeof value === 'bigint') return { [MARKER]: value.toString() };
+    return value;
+}
+
+function reviver(_key, value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const keys = Object.keys(value);
+        if (keys.length === 1 && keys[0] === MARKER && typeof value[MARKER] === 'string') {
+            try { return BigInt(value[MARKER]); } catch (_) { return value; }
+        }
+    }
+    return value;
+}
+
+function stringify(value, space) {
+    return JSON.stringify(value, replacer, space);
+}
+
+function parse(text) {
+    return JSON.parse(text, reviver);
+}
+
+module.exports = { stringify, parse, MARKER };

package/lib/database.js

@@ -10,6 +10,7 @@ const os = require('os');
 const crypto = require('crypto');
 const Table = require('./table');
 const { createError, JSQL_Error, ErrorCodes } = require('./errors');
+const bigintJson = require('./bigint_json');
 
 /**
  * 构造带补充说明的错误。
@@ -463,7 +464,7 @@ class Database {
             // 只追加尚未落盘的记录
             const pending = this._walOps.slice(this._walFlushedCount);
             if (pending.length === 0) return;
-            const lines = pending.map(o => JSON.stringify(o)).join('\n') + '\n';
+            const lines = pending.map(o => bigintJson.stringify(o)).join('\n') + '\n';
             const fd = fs.openSync(this._walPath, 'a');
             try {
                 fs.writeSync(fd, lines, null, 'utf8');
@@ -528,7 +529,7 @@ class Database {
         const trimmed = raw.trim();
         if (trimmed.startsWith('[')) {
             try {
-                const parsed = JSON.parse(trimmed);
+                const parsed = bigintJson.parse(trimmed);
                 if (Array.isArray(parsed)) {
                     ops = parsed.filter(o => o && typeof o.op === 'string');
                 }
@@ -541,7 +542,7 @@ class Database {
                 const t = line.trim();
                 if (!t) continue;
                 try {
-                    const o = JSON.parse(t);
+                    const o = bigintJson.parse(t);
                     if (o && typeof o.op === 'string') ops.push(o);
                 } catch (e) {
                     // 崩溃时写半的尾行，丢弃
@@ -1129,7 +1130,7 @@ class Database {
             const rowCount = table._rows.length;
             const indexCount = Object.keys(table._indexes).length;
             const btreeCount = Object.keys(table._btrees).length;
-            const sizeEstimate = JSON.stringify(table._rows).length;
+            const sizeEstimate = bigintJson.stringify(table._rows).length;
             tableStats[name] = {
                 rowCount,
                 indexCount: indexCount + btreeCount,
@@ -1263,7 +1264,7 @@ class Database {
         const snap = {};
         for (const [name, table] of Object.entries(this._tables)) {
             snap[name] = {
-                rows: JSON.parse(JSON.stringify(table.toJSON())),
+                rows: bigintJson.parse(bigintJson.stringify(table.toJSON())),
                 schema: table._schema,
                 // 自增计数器也要存：否则回滚掉刚插入的行之后，
                 // 下一次插入会跳过已用过的号（用户看到 id 从 2 开始会困惑）。
@@ -1290,7 +1291,7 @@ class Database {
             if (!snap[name]) delete this._tables[name];
         }
         for (const [name, entry] of Object.entries(snap)) {
-            const rows = JSON.parse(JSON.stringify(entry.rows));
+            const rows = bigintJson.parse(bigintJson.stringify(entry.rows));
             let table = this._tables[name];
             if (!table) {
                 table = new Table(name, entry.schema, this);
@@ -1507,7 +1508,7 @@ class Database {
 
         if (table._rows.length === 0) return;
 
-        const currentHash = JSON.stringify(table._rows);
+        const currentHash = bigintJson.stringify(table._rows);
         const versions = this._versions[tableName];
         if (versions.length > 0 && versions[versions.length - 1]._hash === currentHash) return;
 
@@ -2234,8 +2235,8 @@ class Database {
     backup(filePath) {
         const data = this.export();
         const json = this._options.pretty
-            ? JSON.stringify(data, null, 2)
-            : JSON.stringify(data);
+            ? bigintJson.stringify(data, 2)
+            : bigintJson.stringify(data);
         this._writeFile(filePath, json);
         return filePath;
     }
@@ -2245,7 +2246,7 @@ class Database {
             throw createError('ER_FILE_NOT_FOUND', filePath);
         }
         const json = this._readFile(filePath);
-        const data = JSON.parse(json);
+        const data = bigintJson.parse(json);
         for (const [name, rows] of Object.entries(data)) {
             if (this._tables[name]) {
                 this._tables[name]._loadRows(rows);
@@ -2296,8 +2297,8 @@ class Database {
         }
 
         const json = this._options.pretty
-            ? JSON.stringify(data, null, 2)
-            : JSON.stringify(data);
+            ? bigintJson.stringify(data, 2)
+            : bigintJson.stringify(data);
         this._writeFile(this._filePath, json);
         this._dirty = false;
 
@@ -2328,7 +2329,7 @@ class Database {
             }
 
             const json = this._readFile(this._filePath);
-            const data = JSON.parse(json);
+            const data = bigintJson.parse(json);
 
             if (data.__schema__) {
                 for (const [name, schema] of Object.entries(data.__schema__)) {

package/lib/jsql_format.js

@@ -25,6 +25,7 @@ function tag(v) {
     }
     return TYPE.F64;
   }
+  if (typeof v==='bigint') return TYPE.I64;
   if (typeof v==='string') return TYPE.STR;
   if (v instanceof Buffer) return TYPE.BUF;
   return Array.isArray(v)?TYPE.ARR:TYPE.OBJ;
@@ -51,7 +52,12 @@ function dec(buf, off) {
     case TYPE.NUL: return {v:null,off};
     case TYPE.BOL: return {v:buf[off]!==0,off:off+1};
     case TYPE.I32: return {v:buf.readInt32LE(off),off:off+4};
-    case TYPE.I64: return {v:Number(buf.readBigInt64LE(off)),off:off+8};
+    case TYPE.I64: {
+      // 安全范围内的值仍还原成 number（兼容旧数据/行为）；超出范围返回 BigInt，避免精度丢失（Issue #38）
+      const b = buf.readBigInt64LE(off);
+      const safe = b >= BigInt(Number.MIN_SAFE_INTEGER) && b <= BigInt(Number.MAX_SAFE_INTEGER);
+      return {v: safe ? Number(b) : b, off:off+8};
+    }
     case TYPE.F64: return {v:buf.readDoubleLE(off),off:off+8};
     case TYPE.STR: { const l=buf.readUInt32LE(off);off+=4; return {v:buf.toString('utf8',off,off+l),off:off+l}; }
     case TYPE.BUF: { const l=buf.readUInt32LE(off);off+=4; return {v:Buffer.from(buf.subarray(off,off+l)),off:off+l}; }
@@ -78,6 +84,10 @@ function writeEnc(buf, off, v) {
     }
     buf[off] = 3; buf.writeDoubleLE(v, off+1); return off + 9;
   }
+  if (typeof v === 'bigint') {
+    // Issue #38：64 位整数精确保存，读回时再决定还原成 number 还是 BigInt
+    buf[off] = 8; buf.writeBigInt64LE(v, off+1); return off + 9;
+  }
   if (typeof v === 'string') {
     buf[off] = 4;
     const encoded = Buffer.from(v, 'utf8');

package/lib/native_client.js

@@ -1,7 +1,8 @@
 const path = require('path');
 const os = require('os');
 const { executeSQL } = require('./sql');
-const { JSQL_Error, ErrorCodes } = require('./errors');
+const { JSQL_Error, ErrorCodes, createError } = require('./errors');
+const bigintJson = require('./bigint_json');
 const {
   createHookRegistry, applyPlugin, buildPluginContext, registerHook,
   runHooks, getPluginApis
@@ -155,6 +156,69 @@ function assertRowObject(row, index, isBatch) {
   throw new TypeError(`insert(): expected a row object${where}, got ${got}`);
 }
 
+const INT64_MIN = -9223372036854775808n;
+const INT64_MAX = 9223372036854775807n;
+const SAFE_INT_MIN = BigInt(Number.MIN_SAFE_INTEGER);
+const SAFE_INT_MAX = BigInt(Number.MAX_SAFE_INTEGER);
+const DECIMAL_INT_RE = /^[+-]?\d+$/;
+
+function isIntegerType(t) {
+  return t === 'integer' || t === 'int' || t === 'bigint';
+}
+
+/** 与 lib/table.js 的 normalizeInteger 一致（Issue #38）。 */
+function normalizeInteger(v, type) {
+  let b;
+  if (typeof v === 'bigint') b = v;
+  else {
+    try { b = BigInt(String(v).trim()); } catch (_) { throw createError('ER_TRUNCATED_WRONG_VALUE', type, v); }
+  }
+  if (b < INT64_MIN || b > INT64_MAX) throw createError('ER_TRUNCATED_WRONG_VALUE', type, b.toString());
+  return (b >= SAFE_INT_MIN && b <= SAFE_INT_MAX) ? Number(b) : b;
+}
+
+/** Rust 绑定层把 >2^53 的整数以十进制字符串返回，这里还原为 BigInt。 */
+function restoreInteger(v) {
+  if (typeof v === 'bigint') return v;
+  if (typeof v === 'string' && DECIMAL_INT_RE.test(v)) {
+    const b = BigInt(v);
+    return (b >= SAFE_INT_MIN && b <= SAFE_INT_MAX) ? Number(b) : b;
+  }
+  if (typeof v === 'number' && Number.isInteger(v) && !Number.isSafeInteger(v)) return BigInt(v);
+  return v;
+}
+
+function normalizeIntegerInput(v, type) {
+  if (typeof v === 'bigint') return normalizeInteger(v, type);
+  if (typeof v === 'number') {
+    if (!Number.isInteger(v) || !Number.isSafeInteger(v)) throw createError('ER_TRUNCATED_WRONG_VALUE', type, v);
+    return v;
+  }
+  if (typeof v === 'string' && DECIMAL_INT_RE.test(v.trim())) return normalizeInteger(v.trim(), type);
+  throw createError('ER_TRUNCATED_WRONG_VALUE', type, v);
+}
+
+/** 按 schema 做插入/更新前的值归一（JSON 列序列化、整数列精确化）。 */
+function normalizeRowForRust(table, schema, row) {
+  const out = {};
+  for (const [k, v] of Object.entries(row)) {
+    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 !== null && v !== undefined && isIntegerType(t)) {
+      out[k] = normalizeIntegerInput(v, t);
+    } else if (v instanceof Date) {
+      out[k] = v.toISOString();
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
 const NATIVE_TYPE_MAP = {
   text: 'string',
   varchar: 'string',
@@ -169,7 +233,7 @@ const NATIVE_TYPE_MAP = {
   array: 'string',
   object: 'string',
   bool: 'boolean',
-  bigint: 'string',
+  bigint: 'bigint',
   int: 'integer',
 };
 
@@ -260,9 +324,9 @@ function restoreRow(row, schema) {
     if (typeof colDef === 'string') t = colDef.toLowerCase();
     else if (colDef && typeof colDef === 'object' && colDef.type) t = String(colDef.type).toLowerCase();
     if (['json', 'array', 'object'].includes(t) && typeof value === 'string') {
-      try { out[field] = JSON.parse(value); } catch (e) { out[field] = value; }
-    } else if ((t === 'integer' || t === 'int' || t === 'bigint') && typeof value === 'string' && /^-?\d+$/.test(value)) {
-      out[field] = Number(value);
+      try { out[field] = bigintJson.parse(value); } catch (e) { out[field] = value; }
+    } else if (isIntegerType(t)) {
+      out[field] = restoreInteger(value);
     } else if ((t === 'float' || t === 'double' || t === 'number') && typeof value === 'string' && !Number.isNaN(Number(value))) {
       out[field] = Number(value);
     } else {
@@ -274,6 +338,7 @@ function restoreRow(row, schema) {
 
 function _encodedFieldSize(v) {
   if (v === null || v === undefined) return 1;
+  if (typeof v === 'bigint') return 1 + 8;
   if (typeof v === 'number') {
     if (Number.isInteger(v)) return (v >= -2147483648 && v <= 2147483647) ? 1 + 4 : 1 + 8;
     return 1 + 8;
@@ -287,6 +352,9 @@ function encodeField(buf, off, v) {
   if (v === null || v === undefined) {
     buf.writeUInt8(0, off); return off + 1;
   }
+  if (typeof v === 'bigint') {
+    buf.writeUInt8(INT64_TAG, off); buf.writeBigInt64LE(v, off + 1); return off + 9;
+  }
   if (typeof v === 'number') {
     if (Number.isInteger(v)) {
       if (v >= -2147483648 && v <= 2147483647) {
@@ -554,7 +622,9 @@ class JSQL {
     let t = null;
     if (typeof def === 'string') t = def.trim().split(/\s+/)[0].toLowerCase();
     else if (def && typeof def === 'object' && def.type) t = String(def.type).toLowerCase();
-    if (['integer', 'int', 'bigint'].includes(t)) return Number(id);
+    if (isIntegerType(t)) {
+      try { return normalizeIntegerInput(id, t); } catch (_) { return id; }
+    }
     return id;
   }
 
@@ -578,7 +648,7 @@ class JSQL {
     if (pk) {
       if (this._isAutoIntPk(table)) {
         const n = toNonNeg('id', id, NaN);
-        if (Number.isFinite(n)) {
+        if (typeof id !== 'bigint' && Number.isSafeInteger(n)) {
           // 负 id 会被原生层 `i64 -> u64` 静默回绕成 usize::MAX，导致
           // findById 误报 not found（行明明存在却取不到）。在此显式拒绝。
           if (n < 0) throw new Error('id must be a non-negative number');
@@ -589,7 +659,7 @@ class JSQL {
       }
       const filter = {};
       filter[pk] = this._coercePkId(table, id);
-      const r = safeParse(this._n('jsqlFind', table, JSON.stringify(filter), 1, 0));
+      const r = safeParse(this._n('jsqlFind', table, bigintJson.stringify(filter), 1, 0));
       if (r && r.error) return r;
       return Array.isArray(r) && r.length > 0 ? r[0] : null;
     }
@@ -601,7 +671,7 @@ class JSQL {
     if (pk) {
       if (this._isAutoIntPk(table)) {
         const n = toNonNeg('id', id, NaN);
-        if (Number.isFinite(n)) {
+        if (typeof id !== 'bigint' && Number.isSafeInteger(n)) {
           // 负 id 在原生层回绕为 usize::MAX 后静默 not found，update/remove
           // 会无提示地什么都不做 —— 这里显式拒绝（见 issue #35）。
           if (n < 0) throw new Error('id must be a non-negative number');
@@ -612,7 +682,7 @@ class JSQL {
       }
       const filter = {};
       filter[pk] = this._coercePkId(table, id);
-      const r = safeParse(this._n('jsqlFind', table, JSON.stringify(filter), 1, 0));
+      const r = safeParse(this._n('jsqlFind', table, bigintJson.stringify(filter), 1, 0));
       if (Array.isArray(r) && r.length > 0) return r[0].id;
       return null;
     }
@@ -639,23 +709,7 @@ class JSQL {
     const schema = this._schemas[table];
     // 对 JSON/array/object 列保留 safeStringify 以给出可读错误（环形对象等）
     if (schema) {
-      rows = rows.map(row => {
-        const out = {};
-        for (const [k, v] of Object.entries(row)) {
-          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;
-      });
+      rows = rows.map(row => normalizeRowForRust(table, schema, row));
     }
     // 批量插入优先走二进制格式：整批只在 JS 侧 encode 一次，Rust 直接按
     // tag 解析成 FieldValue，省掉「JS JSON.stringify → Rust serde 解析 →
@@ -666,7 +720,7 @@ class JSQL {
     if (typeof native.jsqlInsertBuf === 'function' && _canEncodeBatch(rows)) {
       r = safeParse(this._n('jsqlInsertBuf', table, encodeBatch(rows)));
     } else if (typeof native.jsqlInsertRaw === 'function') {
-      r = safeParse(this._n('jsqlInsertRaw', table, JSON.stringify(rows)));
+      r = safeParse(this._n('jsqlInsertRaw', table, bigintJson.stringify(rows)));
     } else {
       r = safeParse(this._n('jsqlInsertBuf', table, encodeBatch(rows)));
     }
@@ -704,7 +758,7 @@ class JSQL {
     for (var table in update) {
       var entries = update[table];
       if (entries.length === 0) continue;
-      var r = safeParse(this._n('jsqlUpdateByIds', table, JSON.stringify(entries)));
+      var r = safeParse(this._n('jsqlUpdateByIds', table, bigintJson.stringify(entries)));
       this._emit('update', { table, entries, result: r });
     }
     this._opBuffer = { remove: {}, update: {} };
@@ -844,7 +898,7 @@ class JSQL {
     this._flushOpsNow();
     if (!(await this._runHooks('beforeFind', [table, { ids }]))) return null;
     let r;
-    if (this._isAutoIntPk(table) && ids.every(id => Number.isFinite(Number(id)))) {
+    if (this._isAutoIntPk(table) && ids.every(id => typeof id !== 'bigint' && Number.isSafeInteger(Number(id)))) {
       // 自增主键：内部 id 即主键值，一次批量调用即可，避免 N 次往返。
       // #35：负 id 在原生层 `i64 -> u64` 回绕成 usize::MAX，静默 not found；
       // NaN/Infinity 同样不允许。绑定层先校验，绝不把非法值传给原生模块。
@@ -869,7 +923,7 @@ class JSQL {
   async find(table, filter, opts = {}) {
     this._flushOpsNow();
     if (!(await this._runHooks('beforeFind', [table, { filter, opts }]))) return [];
-    const filterStr = filter ? JSON.stringify(filter) : '';
+    const filterStr = filter ? bigintJson.stringify(filter) : '';
     const { limit = 100, offset = 0 } = opts;
     // #35：原生层把 limit/offset 按 `as usize` 无符号转换，负数会静默回绕
     // （release 下空结果 / debug 下 usize::MAX+1 溢出 panic）。绑定层先校验，
@@ -894,10 +948,11 @@ class JSQL {
   }
 
   async updateByIds(table, entries) {
+    const schema = this._schemas[table];
     const pairs = [];
     for (const [id, data] of entries) {
       const seq = this._seqIdByPk(table, id);
-      if (seq !== null) pairs.push([seq, data]);
+      if (seq !== null) pairs.push([seq, schema ? normalizeRowForRust(table, schema, data) : data]);
     }
     if (!(await this._runHooks('beforeUpdate', [table, pairs]))) return;
     if (!this._opBuffer.update[table]) this._opBuffer.update[table] = [];
@@ -922,8 +977,10 @@ class JSQL {
     // 改主键 / UNIQUE 列前先查冲突（同步版，与 lib/database.js 的修复对齐）。
     // 此前直接写入，导致 UPDATE t SET id = 1 WHERE id = 2 静默产生两行同主键。
     this._assertNoKeyConflictSync(table, id, data);
+    const schema = this._schemas[table];
+    const payload = schema ? normalizeRowForRust(table, schema, data) : data;
     if (!this._opBuffer.update[table]) this._opBuffer.update[table] = [];
-    this._opBuffer.update[table].push([seq, data]);
+    this._opBuffer.update[table].push([seq, payload]);
     this._scheduleOpFlush();
   }
 
@@ -953,7 +1010,7 @@ class JSQL {
       if (valOf(self, f) === nv) continue;                            // 值没变
       // 只需知道「是否还存在另一行占用了这个键值」：limit 2 让原生层命中即停，
       // 输出量恒定，不随表规模增长。
-      const probe = safeParse(this._n('jsqlFind', table, JSON.stringify({ [f]: nv }), 2, 0));
+      const probe = safeParse(this._n('jsqlFind', table, bigintJson.stringify({ [f]: nv }), 2, 0));
       if (!Array.isArray(probe)) continue;
       if (probe.some(r => String(idOf(r)) !== String(id))) {
         const e = new Error(`Duplicate entry '${nv}' for key '${f}'`);

package/lib/sql.js

@@ -201,6 +201,19 @@ function jsonPathGet(data, path) {
   return current === undefined ? null : current;
 }
 
+/**
+ * 16 进制整数字面量（0x?? / X'??'）的精确解析（Issue #38）。
+ *
+ * 旧的 parseInt(hexStr, 16) 在 >2^53 时直接丢精度，且与十进制字面量
+ * （已被解析成 BigInt）行为不一致；这里统一成同样的规则：
+ * 安全范围内 → number；超出 → BigInt（精确值保留给 int64 列）。
+ */
+function parseHexIntegerLiteral(hexStr) {
+  if (hexStr.length === 0) throw new Error('Invalid hexadecimal literal');
+  const b = BigInt('0x' + hexStr);
+  return b <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(b) : b;
+}
+
 function tokenize(sql) {
   const tokens = [];
   let i = 0;
@@ -303,7 +316,7 @@ function tokenize(sql) {
         while (j < n && /[0-9A-Fa-f]/.test(sql[j])) j++;
         if (j === i + 2) throw new Error(`Invalid hexadecimal literal at position ${i}`);
         const hexStr = sql.slice(i + 2, j);
-        const numVal = parseInt(hexStr, 16);
+        const numVal = parseHexIntegerLiteral(hexStr);
         tokens.push(new SQLToken('number', numVal, i));
         i = j;
         continue;
@@ -317,7 +330,7 @@ function tokenize(sql) {
           j++;
         }
         if (j >= n) throw new Error(`Unterminated hexadecimal literal at position ${i}`);
-        const numVal = parseInt(hexStr, 16);
+        const numVal = parseHexIntegerLiteral(hexStr);
         tokens.push(new SQLToken('number', numVal, i));
         i = j + 1;
         continue;
@@ -3121,6 +3134,26 @@ function mysqlNum(v) {
   return 0;
 }
 
+/**
+ * BigInt 参与的整数算术（Issue #38）。
+ *
+ * BigInt 与 number 不能直接运算（TypeError），而 Number(BigInt) 会丢精度。
+ * 两侧都是整数（BigInt 或整数值 number）且至少一侧是 BigInt 时，用 BigInt
+ * 精确计算；否则返回 undefined，调用方退回 double 语义。
+ */
+function bigintExactArith(l, r, op) {
+  if (typeof l !== 'bigint' && typeof r !== 'bigint') return undefined;
+  const lb = typeof l === 'bigint' ? l : (typeof l === 'number' && Number.isInteger(l) ? BigInt(l) : null);
+  const rb = typeof r === 'bigint' ? r : (typeof r === 'number' && Number.isInteger(r) ? BigInt(r) : null);
+  if (lb === null || rb === null) return undefined;
+  switch (op) {
+    case '+': return lb + rb;
+    case '-': return lb - rb;
+    case '*': return lb * rb;
+    default: return undefined;
+  }
+}
+
 function resolveOperand(operand, row, ctx) {
   if (operand === null || operand === undefined) return null;
   if (typeof operand === 'string') return resolveOperand({ type: 'column', name: operand }, row, ctx);
@@ -3203,6 +3236,8 @@ function resolveOperand(operand, row, ctx) {
         // 数字与字符串混合的算术会一路错下去。
         // 判据：任一侧是 number，或字符串能被完整解析为数字 → 走数值加法。
         case '+': {
+          const bx = bigintExactArith(l, r, '+');
+          if (bx !== undefined) return bx;
           // MySQL / SQLite 语义（已用 sqlite3 实测核对）：
           //   '5' + 5 = 10   '5' + '5' = 10   'abc' + 1 = 1   'a' + 'b' = 0
           // 任一侧是「数值」时做算术加法，另一侧非数值按 0；
@@ -3217,12 +3252,16 @@ function resolveOperand(operand, row, ctx) {
           return 0;
         }
         case '-': {
+          const bx = bigintExactArith(l, r, '-');
+          if (bx !== undefined) return bx;
           // P1-21: 'abc'-1 → NaN，应返回 null
           const ln = Number(l), rn = Number(r);
           if (isNaN(ln) || isNaN(rn)) return null;
           return ln - rn;
         }
         case '*': {
+          const bx = bigintExactArith(l, r, '*');
+          if (bx !== undefined) return bx;
           const ln = Number(l), rn = Number(r);
           if (isNaN(ln) || isNaN(rn)) return null;
           return ln * rn;
@@ -3270,6 +3309,8 @@ function resolveOperand(operand, row, ctx) {
       if (l === null || r === null || l === undefined || r === undefined) return null;
       switch (operand.op) {
         case '+': {
+          const bx = bigintExactArith(l, r, '+');
+          if (bx !== undefined) return bx;
           if (typeof l === 'number' || typeof r === 'number') {
             const ln = numericIfNumeric(l), rn = numericIfNumeric(r);
             return (ln === null ? 0 : ln) + (rn === null ? 0 : rn);
@@ -3279,8 +3320,8 @@ function resolveOperand(operand, row, ctx) {
           if (rn !== null) return rn;
           return 0;
         }
-        case '-': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln - rn; }
-        case '*': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln * rn; }
+        case '-': { const bx = bigintExactArith(l, r, '-'); if (bx !== undefined) return bx; const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln - rn; }
+        case '*': { const bx = bigintExactArith(l, r, '*'); if (bx !== undefined) return bx; const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln * rn; }
         case '/': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) || rn === 0 ? null : ln / rn; }
         case '%': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) || rn === 0 ? null : ln % rn; }
         case 'DIV': return r === 0 ? null : Math.trunc(Number(l) / Number(r));
@@ -4880,6 +4921,8 @@ function evaluateExpr(expr, row, ctx) {
       if (l === null || r === null || l === undefined || r === undefined) return null;
       switch (expr.op) {
         case '+': {
+          const bx = bigintExactArith(l, r, '+');
+          if (bx !== undefined) return bx;
           if (typeof l === 'number' || typeof r === 'number') {
             const ln = numericIfNumeric(l), rn = numericIfNumeric(r);
             return (ln === null ? 0 : ln) + (rn === null ? 0 : rn);
@@ -4889,8 +4932,8 @@ function evaluateExpr(expr, row, ctx) {
           if (rn !== null) return rn;
           return 0;
         }
-        case '-': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln - rn; }
-        case '*': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln * rn; }
+        case '-': { const bx = bigintExactArith(l, r, '-'); if (bx !== undefined) return bx; const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln - rn; }
+        case '*': { const bx = bigintExactArith(l, r, '*'); if (bx !== undefined) return bx; const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) ? null : ln * rn; }
         case '/': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) || rn === 0 ? null : ln / rn; }
         case '%': { const ln = Number(l), rn = Number(r); return isNaN(ln) || isNaN(rn) || rn === 0 ? null : ln % rn; }
         case 'DIV': return r === 0 ? null : Math.trunc(Number(l) / Number(r));
@@ -6108,6 +6151,14 @@ class SQLExecutor {
     const type = colDef && colDef.type;
     if (!type) return val;
     if (type === 'integer' || type === 'int' || type === 'bigint' || type === 'smallint' || type === 'tinyint') {
+      // BigInt 必须原样保留：Number(val) 会在 >2^53 时丢精度，
+      // 下推成索引后与行里的 BigInt 严格比较永远不相等（Issue #38）。
+      if (typeof val === 'bigint') return val;
+      // 十进制字符串（参数内联后常见）同样要精确解析，不能用 Number()
+      if (typeof val === 'string' && /^[+-]?\d+$/.test(val.trim())) {
+        const b = BigInt(val.trim());
+        return (b >= BigInt(Number.MIN_SAFE_INTEGER) && b <= BigInt(Number.MAX_SAFE_INTEGER)) ? Number(b) : b;
+      }
       const n = Number(val);
       return Number.isNaN(n) ? val : n;
     }
@@ -8045,6 +8096,7 @@ function escapeId(name) {
 
 function escapeValue(value) {
   if (value === null || value === undefined) return 'NULL';
+  if (typeof value === 'bigint') return value.toString();   // Issue #38：精确的整数字面量
   if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'NULL';
   if (typeof value === 'boolean') return value ? 'true' : 'false';
   if (value instanceof Date) {