jsql-neo 6.5.26 → 6.5.28

package/postinstall.js

@@ -14,7 +14,11 @@ const BIN_NAME = process.platform === 'win32' ? 'jsql-neo-server.exe' : 'jsql-ne
 const BP = path.join(ROOT, 'bin', BIN_NAME);
 
 // Native N-API module (native/jsql-neo-native.node)
-const NATIVE_PATH = path.join(ROOT, 'native', 'jsql-neo-native.node');
+// 允许测试/自定义安装把 native 放到别处（JSQL_NATIVE_PATH 为绝对路径）。
+// 默认仍是包内 native/ 目录；META_PATH 会跟着 dirname 一起走。
+const NATIVE_PATH = process.env.JSQL_NATIVE_PATH
+  ? path.resolve(process.env.JSQL_NATIVE_PATH)
+  : path.join(ROOT, 'native', 'jsql-neo-native.node');
 
 // GitHub 加速代理前缀（可选）。加速站的用法是把原始 URL 直接拼在后面：
 //   https://<host>/https://github.com/owner/repo/releases/download/vX.Y.Z/asset
@@ -357,10 +361,36 @@ function installDownloadedModule(tmp) {
   try {
     fs.renameSync(tmp, NATIVE_PATH);
   } catch (e) {
-    // Windows 上 rename 覆盖已存在文件会 EEXIST/EPERM
+    // Windows 上 rename 覆盖已存在文件会 EEXIST/EPERM。
+    //
+    // 旧实现在这里 unlinkSync(旧文件) 并把失败 catch(_) 吞掉，然后第二次
+    // rename 必然再失败 —— 结果是「下载成功 + 校验通过」却静默留着旧二进制，
+    // 上层只看到一句轻描淡写的 "keeping the existing local native module"。
+    // .node 是 DLL，被加载过后 unlink 常常 EPERM，但把它 rename 挪开是可行的
+    // （实测 mv 能成功而 unlink 不能），所以改为「挪走 → 装新的」。
     if (e.code === 'EEXIST' || e.code === 'EPERM' || e.code === 'EACCES') {
-      try { fs.unlinkSync(NATIVE_PATH); } catch (_) { /* ignore */ }
-      fs.renameSync(tmp, NATIVE_PATH);
+      const parked = `${NATIVE_PATH}.${process.pid}.old`;
+      try {
+        fs.renameSync(NATIVE_PATH, parked);
+      } catch (moveErr) {
+        try { fs.unlinkSync(NATIVE_PATH); }
+        catch (unlinkErr) {
+          // 两条路都不通就把真实原因抛出去，绝不再静默降级
+          throw new Error(
+            `cannot replace ${NATIVE_PATH}: rename=${e.code}, move=${moveErr.code}, unlink=${unlinkErr.code}`
+          );
+        }
+      }
+      try {
+        fs.renameSync(tmp, NATIVE_PATH);
+      } catch (installErr) {
+        // 装不回去必须把旧文件还原，别让本机变成「完全没有 native」
+        if (fs.existsSync(parked)) {
+          try { fs.renameSync(parked, NATIVE_PATH); } catch (_) { /* 外层还有 backup 兜底 */ }
+        }
+        throw installErr;
+      }
+      try { if (fs.existsSync(parked)) fs.unlinkSync(parked); } catch (_) { /* 清理失败不影响安装 */ }
     } else {
       throw e;
     }
@@ -438,6 +468,7 @@ async function downloadAndVerify(opts = {}) {
         if (installed.backup) {
           try { fs.unlinkSync(installed.backup); } catch (_) { /* ignore */ }
         }
+        writeInstalledMeta(tag, sha256File(NATIVE_PATH));
         console.log(`[jsql-neo] native module updated: native/jsql-neo-native.node (${tag})`);
         return true;
       }
@@ -497,13 +528,108 @@ async function ensureNativeNode() {
 
   // 拉取失败：本地可用就继续用本地 —— 网络问题不该把已经能跑的安装搞坏
   if (tryLoadNative()) {
-    console.warn('[jsql-neo] remote refresh failed; keeping the existing local native module.');
+    console.warn('[jsql-neo] WARNING: remote refresh FAILED — keeping the EXISTING native module.');
+    console.warn('[jsql-neo] It may NOT match this package version, which can silently break native features.');
+    console.warn('[jsql-neo] Run "node postinstall.js --status" to check for a version mismatch.');
     return;
   }
   console.warn('[jsql-neo] could not fetch a verified native module; falling back to source build / WASM.');
   buildNativeFromSource();
 }
 
+/**
+ * native 安装状态自检。
+ *
+ * 背景：postinstall 之前在 Windows 上会「下载成功、校验通过、装不上」，
+ * 却只留一句 keeping the existing local native module —— 用户无从察觉
+ * 自己其实还在用旧二进制（issue-38 的 bigint 用例就是这么一直挂的）。
+ *
+ * 现在每次成功安装都落一份 .installed.json，`node postinstall.js --status`
+ * 能直接回答「当前 .node 是不是这个包版本该用的那个」，也可当 CI 门禁。
+ */
+const META_PATH = path.join(path.dirname(NATIVE_PATH), '.installed.json');
+
+function writeInstalledMeta(tag, sha256) {
+  try {
+    fs.writeFileSync(META_PATH, JSON.stringify({
+      tag,
+      sha256: sha256 || null,
+      packageVersion: pkg.version,
+      installedAt: new Date().toISOString(),
+      platform: process.platform,
+      arch: process.arch,
+    }, null, 2) + '\n');
+  } catch (_) { /* 元数据写不了不该让安装失败 */ }
+}
+
+function readInstalledMeta() {
+  try { return JSON.parse(fs.readFileSync(META_PATH, 'utf8')); }
+  catch (_) { return null; }
+}
+
+/** 返回 0 = 匹配，1 = 不匹配 / 未记录（可直接用于 CI 门禁）。 */
+function nativeStatus() {
+  const expected = `v${pkg.version}`;
+  const meta = readInstalledMeta();
+  const exists = fs.existsSync(NATIVE_PATH);
+  const size = exists ? fs.statSync(NATIVE_PATH).size : 0;
+  const out = [
+    `[jsql-neo] package version : ${pkg.version}  (expected native tag ${expected})`,
+    `[jsql-neo] native module   : ${exists ? `present (${size} bytes)` : 'MISSING'}`,
+  ];
+  if (meta) {
+    out.push(`[jsql-neo] installed tag   : ${meta.tag}  (${meta.installedAt})`);
+    out.push(`[jsql-neo] installed sha256: ${meta.sha256 || 'n/a'}`);
+  } else {
+    out.push('[jsql-neo] installed tag   : UNKNOWN (no .installed.json — installed by an older build)');
+  }
+  const match = !!meta && meta.tag === expected && exists;
+  const state = match ? 'OK' : (meta && meta.tag !== expected) ? 'MISMATCH' : 'UNVERIFIED';
+  out.push(`[jsql-neo] STATUS          : ${state}`);
+  if (!match) out.push('[jsql-neo] refresh with: node postinstall.js   (or npm rebuild jsql-neo)');
+  console.log(out.join('\n'));
+  return match ? 0 : 1;
+}
+
+/**
+ * 内容级校验。
+ *
+ * nativeStatus 只读 .installed.json 里记录的 tag —— 如果 .node 文件被替换、
+ * 损坏，或被人换成了别的版本但元数据没动，status 依然会报 OK。这里直接
+ * 重算当前文件的 SHA256 与安装时记录的比对，回答「磁盘上这个文件是不是
+ * 当初装进来的那个」。
+ *
+ * 返回结构化对象，便于 CLI 输出 JSON 给 CI 消费。
+ */
+function verifyNative() {
+  const expected = `v${pkg.version}`;
+  const meta = readInstalledMeta();
+  const exists = fs.existsSync(NATIVE_PATH);
+  const r = {
+    packageVersion: pkg.version,
+    expectedTag: expected,
+    installedTag: meta ? meta.tag : null,
+    present: exists,
+    size: exists ? fs.statSync(NATIVE_PATH).size : 0,
+    expectedSha256: meta ? (meta.sha256 || null) : null,
+    actualSha256: null,
+    state: 'UNVERIFIED',
+  };
+  if (!exists) { r.state = 'MISSING'; return r; }
+  try {
+    r.actualSha256 = sha256File(NATIVE_PATH);
+  } catch (e) {
+    r.state = 'UNREADABLE';
+    r.error = e.message;
+    return r;
+  }
+  if (!r.expectedSha256) return r;                       // 老安装没有校验和
+  if (r.actualSha256 !== r.expectedSha256) { r.state = 'CORRUPT'; return r; }
+  if (r.installedTag !== expected) { r.state = 'MISMATCH'; return r; }
+  r.state = 'OK';
+  return r;
+}
+
 function ensureServerBinary() {
   if (fs.existsSync(BP)) {
     fs.chmodSync(BP, 0o755);
@@ -541,7 +667,8 @@ async function main() {
 
 // 仅当直接执行时才运行（build:native / 测试可 require 本文件复用构建逻辑）
 if (require.main === module) {
-  main();
+  if (process.argv.includes('--status')) process.exitCode = nativeStatus();
+  else main();
 }
 
 module.exports = {
@@ -551,4 +678,7 @@ module.exports = {
   releaseTag,
   resolveLatestTag,
   installDownloadedModule,
+  nativeStatus,
+  verifyNative,
+  readInstalledMeta,
 };

package/test/coverage.js

@@ -166,7 +166,9 @@ function tmp(name) {
     ok('sql rollback', (await db.count('users')) === 1);
     await executeSQL(db, 'START TRANSACTION');
     await executeSQL(db, "INSERT INTO users (name, age) VALUES ('X', 1)");
-    await executeSQL(db, 'TRUNCATE TABLE users');
+    // TRUNCATE 被 findDestructiveSQL 判为破坏性语句，默认 safety 会拦。
+    // 这里就是要验证该功能，显式声明而不是放宽全局策略；断言保持不变。
+    await executeSQL(db, 'TRUNCATE TABLE users', { safety: false });
     ok('sql truncate', (await db.count('users')) === 0);
     const sqlApi = require(path.join(ROOT, 'lib/sql'));
     const parsed = sqlApi.parseSQL('SELECT * FROM t WHERE id = 5');

package/test/finalize-bigint.test.js

@@ -0,0 +1,55 @@
+/* ---- finalizeResultBigInts：性能优化不能丢 BigInt 语义 ---- */
+/*
+ * 优化前 executeSQL 用通用 finalizeBigInts 对结果深递归；优化后改成针对
+ * rows(二维) / raw(对象数组) 的紧凑循环，其余字段仍走通用实现。
+ * 这里钉死「>2^53 的值在 rows 和 raw 里都必须是可序列化的字符串」，
+ * 以及小整数仍是 number、结果整体可 JSON.stringify。
+ */
+const path = require('path');
+const ROOT = path.join(__dirname, '..');
+const { Database } = require(path.join(ROOT, 'index.js'));
+
+let pass = 0, fail = 0;
+function ok(name, cond, got) {
+  if (cond) { pass++; console.log('[OK]   ' + name); }
+  else { fail++; console.log('[FAIL] ' + name + ' -> ' + JSON.stringify(got, (k, v) => typeof v === 'bigint' ? v.toString() + 'n' : v)); }
+}
+
+(async () => {
+  const db = new Database(':memory:', { autoSave: false });
+  await db.createTable('t', { id: { type: 'integer', primaryKey: true, autoIncrement: true }, n: { type: 'integer' } });
+  await db.insert('t', [{ n: 1 }, { n: 2 }, { n: 3 }]);
+
+  const r = await db.query('SELECT 9007199254740993 AS big, 1 AS small');
+  ok('rows 里 >2^53 的 BigInt 已转字符串',
+    r.rows[0][0] === '9007199254740993' && typeof r.rows[0][0] === 'string', r.rows);
+  ok('raw 里 >2^53 的 BigInt 已转字符串',
+    r.raw[0].big === '9007199254740993' && typeof r.raw[0].big === 'string', r.raw);
+  ok('小整数仍是 number（没被无差别转字符串）',
+    r.rows[0][1] === 1 && r.raw[0].small === 1, r);
+  ok('结果整体可 JSON.stringify（BigInt 会抛错）',
+    (() => { try { JSON.stringify(r); return true; } catch (e) { return false; } })(), r);
+
+  const huge = await db.query('SELECT 9223372036854775807 AS huge');
+  ok('int64 最大值同样转字符串', huge.rows[0][0] === '9223372036854775807', huge.rows);
+
+  // 多行：rows 每一行、raw 每个对象都要处理到，不能只处理第一行
+  const many = await db.query('SELECT id, 9007199254740993 AS big FROM t');
+  ok('多行 rows 全部转换',
+    many.rows.length === 3 && many.rows.every((row) => row[1] === '9007199254740993'), many.rows);
+  ok('多行 raw 全部转换',
+    many.raw.length === 3 && many.raw.every((o) => o.big === '9007199254740993'), many.raw);
+  ok('多行场景下 id 仍是 number',
+    many.rows.every((row) => typeof row[0] === 'number'), many.rows);
+
+  // 其余字段走通用实现：columns / 元数据不能被跳过
+  const plain = await db.query('SELECT id FROM t WHERE id = 1');
+  ok('columns 等其余字段保留',
+    Array.isArray(plain.columns) && plain.columns[0] === 'id' && plain.rowCount === 1, plain);
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail === 0 ? 0 : 1);
+})().catch(e => {
+  console.log('[FAIL] unexpected exception: ' + e.message);
+  process.exit(1);
+});

package/test/issue-44.test.js

@@ -0,0 +1,92 @@
+/*
+ * Issue #44 — 索引等值查找忽略类型归一：字符串查询值在数值列上静默返回空。
+ *
+ * 复现（v6.5.26）：
+ *   db.find('u', { id: '5' })   -> []      （id 是 INT PRIMARY KEY，B-Tree）
+ *   db.findByIds('u', ['5'])    -> []
+ *   Mongo insert 的 _id 唯一性检查走同一套索引查找，也会被绕过。
+ *
+ * 修复：查询值先按列声明类型归一（'5' → 5），索引未命中再回落全表过滤。
+ */
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const { Database, createMongoServer } = require(path.join(ROOT, 'index.js'));
+
+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, 300) : ''); }
+}
+
+(async () => {
+  try {
+    const db = new Database(':memory:');
+    await db.createTable('u', {
+      id: 'INT PRIMARY KEY',
+      name: 'TEXT',
+      code: 'INT UNIQUE',
+      score: 'FLOAT',
+      active: 'BOOLEAN',
+    });
+    await db.insert('u', { id: 5, name: 'a', code: 100, score: 1.5, active: true });
+    await db.insert('u', { id: 6, name: 'b', code: 200, score: 2.5, active: false });
+
+    // --- B-Tree：UNIQUE 非主键列 ---
+    const byCode = await db.find('u', { code: '100' });
+    ok('#44 btree 唯一列：字符串查数值命中', byCode.length === 1 && byCode[0].id === 5, byCode);
+
+    // --- B-Tree：主键列 + $in ---
+    const byIn = await db.find('u', { id: { $in: ['5', '6'] } });
+    ok('#44 btree 主键 $in：字符串列表命中', byIn.length === 2, byIn.length);
+
+    // --- 主键 btree：findById / findByIds / updateById / removeById ---
+    const byId = await db.findById('u', '5');
+    ok('#44 findById("5") 命中数字主键', !!byId && byId.name === 'a', byId);
+
+    const byIds = await db.findByIds('u', ['5', '6']);
+    ok('#44 findByIds(["5","6"]) 命中', byIds.length === 2, byIds.length);
+
+    ok('#44 updateById("6") 生效', (await db.updateById('u', '6', { name: 'bb' })) && (await db.findById('u', 6)).name === 'bb');
+
+    // --- 其他声明类型的归一 ---
+    const byFloat = await db.find('u', { score: '1.5' });
+    ok('#44 float 列：字符串查数值命中', byFloat.length === 1 && byFloat[0].id === 5, byFloat);
+    const byBool = await db.find('u', { active: 1 });
+    ok('#44 boolean 列：1 命中 true', byBool.length === 1 && byBool[0].id === 5, byBool);
+    const byText = await db.find('u', { name: 'a' });
+    ok('#44 text 列：正常查询不受影响', byText.length === 1, byText.length);
+
+    // --- hash 索引（旧版 _indexes）路径 ---
+    await db.createTable('h', { v: 'INT', s: 'TEXT' });
+    const ht = db._ensureTable('h');
+    ht.createIndex('v');
+    await db.insert('h', { v: 7, s: 'x' });
+    const byHash = await db.find('h', { v: '7' });
+    ok('#44 hash 索引：字符串查数值命中', byHash.length === 1 && byHash[0].v === 7, byHash);
+
+    // --- Mongo _id 唯一性：索引不再被类型差异绕过 ---
+    const srv = createMongoServer({ port: 0, noAuth: true, dataDir: ':memory:' });
+    const engine = await srv._getEngine('test');
+    await engine.createTable('c', { _id: { type: 'integer', unique: true }, v: { type: 'integer' } });
+    const r1 = await srv._dispatch('insert', {
+      insert: 'c',
+      documents: [{ _id: 1, v: 10 }, { _id: '1', v: 99 }],
+      $db: 'test',
+    });
+    const cols = await engine.find('c', {});
+    ok('#44 Mongo _id 去重不被类型差异绕过',
+      r1.ok === 1 && r1.n === 1 && cols.length === 1 && cols[0].v === 10,
+      { r: r1, rows: cols });
+
+    // --- 清理路径同样按类型归一 ---
+    await db.removeById('u', '5');
+    ok('#44 removeById("5") 删除数字主键行', (await db.find('u', { id: 5 })).length === 0);
+  } catch (e) {
+    fail++;
+    console.log('[FAIL] unexpected exception:', e && e.stack || e);
+  }
+
+  console.log(`\n${fail === 0 ? 'ALL PASS' : 'FAILURES'} — ${pass} passed, ${fail} failed\n`);
+  if (fail > 0) process.exit(1);
+})();

package/test/issue-45.test.js

@@ -0,0 +1,62 @@
+/*
+ * Issue #45 — MongoDB $avg 把 NULL 当 0 且计入分母。
+ *
+ * [10, null, 30] 曾经得到 (10+0+30)/3 = 13.33，MongoDB 是 20；
+ * 全 null 的分组曾经返回 0，MongoDB 返回 null。
+ */
+const path = require('path');
+const { createMongoServer } = require(path.join(__dirname, '..', 'lib', 'mongo_server.js'));
+
+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, 300) : ''); }
+}
+
+(async () => {
+  try {
+    const srv = createMongoServer({ port: 0, noAuth: true, dataDir: ':memory:' });
+    const engine = await srv._getEngine('test');
+    await engine.createTable('m', {
+      _id: { type: 'integer' },
+      g: { type: 'string' },
+      x: { type: 'integer' },
+    });
+    const table = engine._ensureTable('m');
+    table._rows = [
+      { _id: 1, g: 'a', x: 10 },
+      { _id: 2, g: 'a', x: null },
+      { _id: 3, g: 'a', x: 30 },
+      { _id: 4, g: 'b', x: null },
+      { _id: 5, g: 'b', x: undefined },
+    ];
+
+    const r = await srv._dispatch('aggregate', {
+      aggregate: 'm',
+      pipeline: [{ $group: { _id: '$g', avg: { $avg: '$x' } } }],
+      $db: 'test',
+    });
+    const batch = r.cursor ? r.cursor.firstBatch : [];
+    const byGroup = {};
+    for (const row of batch) byGroup[row._id] = row.avg;
+
+    ok('#45 $avg 忽略 null：#a = (10+30)/2 = 20', byGroup.a === 20, byGroup);
+    ok('#45 全 null 组返回 null', byGroup.b === null, byGroup);
+
+    // $sum 语义不受影响（null 加 0 仍是 no-op）
+    const r2 = await srv._dispatch('aggregate', {
+      aggregate: 'm',
+      pipeline: [{ $group: { _id: '$g', total: { $sum: '$x' } } }],
+      $db: 'test',
+    });
+    const bySum = {};
+    for (const row of (r2.cursor ? r2.cursor.firstBatch : [])) bySum[row._id] = row.total;
+    ok('#45 $sum 不受影响：#a = 40', bySum.a === 40, bySum);
+  } catch (e) {
+    fail++;
+    console.log('[FAIL] unexpected exception:', e && e.stack || e);
+  }
+
+  console.log(`\n${fail === 0 ? 'ALL PASS' : 'FAILURES'} — ${pass} passed, ${fail} failed\n`);
+  if (fail > 0) process.exit(1);
+})();

package/test/issue-46.test.js

@@ -0,0 +1,42 @@
+/*
+ * Issue #46 — index.d.ts 声明了 applyParams / escapeValue / escapeId，
+ * index.js 却没有导出，按类型调用会 TypeError。
+ */
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const jsql = require(path.join(ROOT, 'index.js'));
+
+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, 300) : ''); }
+}
+
+try {
+  ok('#46 applyParams 是函数', typeof jsql.applyParams === 'function', typeof jsql.applyParams);
+  ok('#46 escapeValue 是函数', typeof jsql.escapeValue === 'function', typeof jsql.escapeValue);
+  ok('#46 escapeId 是函数', typeof jsql.escapeId === 'function', typeof jsql.escapeId);
+
+  if (typeof jsql.applyParams === 'function') {
+    ok('#46 applyParams 参数替换生效', jsql.applyParams('SELECT ?', [1]) === 'SELECT 1', jsql.applyParams('SELECT ?', [1]));
+  }
+  if (typeof jsql.escapeValue === 'function') {
+    ok("#46 escapeValue 转义单引号", jsql.escapeValue("a'b") === "'a\\'b'", jsql.escapeValue("a'b"));
+  }
+  if (typeof jsql.escapeId === 'function') {
+    ok('#46 escapeId 反引号包裹', jsql.escapeId('a`b') === '`a``b`', jsql.escapeId('a`b'));
+  }
+
+  // .d.ts 与 .js 的导出面必须一致（防止再漂移）
+  const dts = require('fs').readFileSync(path.join(ROOT, 'index.d.ts'), 'utf8');
+  for (const name of ['applyParams', 'escapeValue', 'escapeId']) {
+    ok(`#46 index.d.ts 声明的 ${name} 已导出`, dts.includes(`export function ${name}`) && name in jsql);
+  }
+} catch (e) {
+  fail++;
+  console.log('[FAIL] unexpected exception:', e && e.stack || e);
+}
+
+console.log(`\n${fail === 0 ? 'ALL PASS' : 'FAILURES'} — ${pass} passed, ${fail} failed\n`);
+if (fail > 0) process.exit(1);

package/test/issue-47.test.js

@@ -0,0 +1,65 @@
+/*
+ * Issue #47 — MongoDB $sort 无论升降序都把 NULL 排在最后。
+ *
+ * MongoDB 语义：升序 null 在最前，降序 null 在最后。
+ * v6.5.26 的比较器在应用方向之前就 return 1 / -1，导致升序时 null 恒在末尾。
+ */
+const path = require('path');
+const { createMongoServer } = require(path.join(__dirname, '..', 'lib', 'mongo_server.js'));
+
+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, 300) : ''); }
+}
+
+async function sorted(srv, dir) {
+  const r = await srv._dispatch('aggregate', {
+    aggregate: 's',
+    pipeline: [{ $sort: { score: dir } }],
+    $db: 'test',
+  });
+  const batch = r.cursor ? r.cursor.firstBatch : [];
+  return batch.map(x => (x.score === undefined ? null : x.score));
+}
+
+(async () => {
+  try {
+    const srv = createMongoServer({ port: 0, noAuth: true, dataDir: ':memory:' });
+    const engine = await srv._getEngine('test');
+    await engine.createTable('s', { _id: { type: 'integer' }, score: { type: 'integer' } });
+    const table = engine._ensureTable('s');
+    table._rows = [
+      { _id: 1, score: 20 },
+      { _id: 2, score: null },
+      { _id: 3, score: 10 },
+      { _id: 4, score: 30 },
+    ];
+
+    const asc = await sorted(srv, 1);
+    ok('#47 升序 null 排最前', JSON.stringify(asc) === JSON.stringify([null, 10, 20, 30]), asc);
+
+    const desc = await sorted(srv, -1);
+    ok('#47 降序 null 排最后', JSON.stringify(desc) === JSON.stringify([30, 20, 10, null]), desc);
+
+    // 多键排序：第一键相同时第二键的 null 也要跟随方向
+    table._rows = [
+      { _id: 1, g: 'a', score: null },
+      { _id: 2, g: 'a', score: 5 },
+      { _id: 3, g: 'a', score: 1 },
+    ];
+    const r = await srv._dispatch('aggregate', {
+      aggregate: 's',
+      pipeline: [{ $sort: { g: 1, score: -1 } }],
+      $db: 'test',
+    });
+    const multi = (r.cursor ? r.cursor.firstBatch : []).map(x => x.score);
+    ok('#47 多键降序 null 排最后', JSON.stringify(multi) === JSON.stringify([5, 1, null]), multi);
+  } catch (e) {
+    fail++;
+    console.log('[FAIL] unexpected exception:', e && e.stack || e);
+  }
+
+  console.log(`\n${fail === 0 ? 'ALL PASS' : 'FAILURES'} — ${pass} passed, ${fail} failed\n`);
+  if (fail > 0) process.exit(1);
+})();

package/test/issue-48.test.js

@@ -0,0 +1,39 @@
+/*
+ * Issue #48 — mysql_compat 把 FLOAT/DOUBLE 列的 result metadata 报成
+ * LONGLONG(8)，客户端按类型解码会误判。
+ *
+ * 修复：整数 → 8 (LONGLONG)，非整数 → 5 (DOUBLE)。
+ */
+const path = require('path');
+const { createConnection } = require(path.join(__dirname, '..', 'lib', 'mysql_compat.js'));
+
+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, 300) : ''); }
+}
+
+(async () => {
+  try {
+    const conn = createConnection();
+    await conn.connect();
+    await conn.query('CREATE TABLE m (id INTEGER PRIMARY KEY, i INTEGER, d DOUBLE, s TEXT)');
+    await conn.query("INSERT INTO m (id, i, d, s) VALUES (1, 42, 1.5, 'x')");
+
+    const [rows, fields] = await conn.query('SELECT i, d, s FROM m');
+    const typeOf = (name) => (fields.find(f => f.name === name) || {}).type;
+
+    ok('#48 INTEGER 列仍为 LONGLONG(8)', typeOf('i') === 8, { i: typeOf('i'), rows });
+    ok('#48 DOUBLE 列为 DOUBLE(5)', typeOf('d') === 5, { d: typeOf('d') });
+    ok('#48 TEXT 列为 VAR_STRING(253)', typeOf('s') === 253, { s: typeOf('s') });
+    ok('#48 行数据未受影响', rows.length === 1 && rows[0].i === 42 && rows[0].d === 1.5, rows);
+
+    await conn.end();
+  } catch (e) {
+    fail++;
+    console.log('[FAIL] unexpected exception:', e && e.stack || e);
+  }
+
+  console.log(`\n${fail === 0 ? 'ALL PASS' : 'FAILURES'} — ${pass} passed, ${fail} failed\n`);
+  if (fail > 0) process.exit(1);
+})();