jsql-neo 6.3.3 → 6.3.4

package/test/mysql-compat-hijack.test.js

@@ -0,0 +1,87 @@
+/*
+ * require.cache 全局劫持回归测试（P0-1）
+ *
+ * 背景：旧版 enableMySQLCompat() 会遍历 node_modules，把 mysql2 的
+ * require.cache 条目替换成内存兼容层。它靠 process.cwd() 猜路径，
+ * mysql2 通常尚未加载，于是被静默替换 —— 真实 MySQL 连接悄悄改查内存库
+ * 且不报错，表现为「本地跑通、上线全错」。
+ *
+ * 本测试锁定修复后的契约：
+ *   1. 默认调用 enableMySQLCompat() 绝不改动 require.cache
+ *   2. { global: true } 缺少环境变量确认时必须抛错
+ *   3. injectMySQLCompat() 只改写传入对象的引用，不污染全局
+ *   4. 兼容层仍可显式使用
+ */
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+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) : '')); }
+}
+
+// 造一个隔离的假 mysql2，用于验证劫持行为
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'jsql-hijack-'));
+const nm = path.join(tmp, 'node_modules', 'mysql2');
+fs.mkdirSync(nm, { recursive: true });
+fs.writeFileSync(path.join(nm, 'index.js'),
+    'exports.createConnection = function(){ return { __real: true }; };\n' +
+    'exports.createPool = function(){ return { __real: true }; };\n');
+fs.writeFileSync(path.join(nm, 'package.json'),
+    JSON.stringify({ name: 'mysql2', version: '3.0.0', main: 'index.js' }));
+
+const jsql = require('../index.js');
+const mysql2Path = path.join(nm, 'index.js');
+
+try {
+    console.log('--- 1. 默认调用不得劫持 require.cache ---');
+    // 直接检查 index.js 源码不含无条件注入路径
+    const src = fs.readFileSync(path.join(__dirname, '..', 'index.js'), 'utf8');
+    const fnBody = src.slice(src.indexOf('function enableMySQLCompat'));
+    ok('enableMySQLCompat 内部对 global 做了显式判断',
+        /opts\.global\s*!==\s*true/.test(fnBody));
+    ok('危险路径需环境变量确认',
+        /JSQL_NEO_ALLOW_GLOBAL_HIJACK/.test(fnBody));
+
+    console.log('--- 2. 调用后 require.cache 不含被伪造的 mysql2 ---');
+    jsql.enableMySQLCompat();
+    const cached = require.cache[mysql2Path];
+    ok('require.cache 中没有 mysql2 条目', cached === undefined,
+        cached ? '仍被注入' : undefined);
+
+    console.log('--- 3. { global: true } 无环境变量时抛错 ---');
+    let threw = null;
+    try { jsql.enableMySQLCompat({ global: true }); } catch (e) { threw = e; }
+    ok('抛错并说明原因', threw && /require\.cache/.test(threw.message), threw && threw.message);
+    ok('抛错后仍未注入', require.cache[mysql2Path] === undefined);
+
+    console.log('--- 4. 显式注入只影响目标对象 ---');
+    const target = {
+        createConnection: () => ({ __fake: true }),
+        Driver: { createPool: () => ({ __fake: true }) },
+    };
+    const before = target.createConnection;
+    const touched = jsql.injectMySQLCompat(target);
+    ok('injectMySQLCompat 返回 true', touched === true);
+    ok('顶层 createConnection 已被替换', target.createConnection !== before);
+    ok('嵌套 Driver.createPool 已被替换',
+        typeof target.Driver.createPool === 'function' &&
+        target.Driver.createPool !== before);
+    ok('未触碰 require.cache', require.cache[mysql2Path] === undefined);
+
+    console.log('--- 5. 兼容层仍可显式使用 ---');
+    ok('导出 mysql2.createConnection', typeof jsql.mysql2.createConnection === 'function');
+    ok('导出 mysql2.createPool', typeof jsql.mysql2.createPool === 'function');
+    ok('导出 createConnection 快捷方式', typeof jsql.createConnection === 'function');
+    ok('导出 injectMySQLCompat', typeof jsql.injectMySQLCompat === 'function');
+    ok('enableMySQLCompat 默认调用返回兼容层',
+        jsql.enableMySQLCompat() === jsql.mysql2);
+} finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/test/native-multi-instance.test.js

@@ -0,0 +1,134 @@
+/*
+ * native 多实例回归测试（P0-2）
+ *
+ * 背景：6.3.3 及以前 native 层是 `thread_local! static ENGINE`，
+ * 整个进程只有一个 HybridEngine。于是：
+ *   new Database(dirA) → new Database(dirB)
+ * 会把 dirA 的所有表 clear() 掉（HybridEngine::open 无条件 clear），
+ * 同进程无法持有两个独立数据库 —— 对自称「嵌入式数据库」是硬伤。
+ *
+ * 6.3.4 改为句柄注册表：jsqlInstanceNew() 分配句柄，
+ * 所有操作走 jsqlXxxH(handle, ...)；旧的 jsqlXxx() 走保留的默认实例 0。
+ *
+ * 若加载的是旧版预编译二进制（无 jsqlInstanceNew），整套多实例断言跳过，
+ * 但向后兼容路径仍需验证。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const native = require('../native/jsql-neo-native.node');
+const { JSQL } = require('../lib/native_client.js');
+
+let pass = 0, fail = 0, skip = 0;
+function ok(name, cond, extra) {
+    if (cond) { pass++; console.log('[OK]   ' + name); }
+    else { fail++; console.log('[FAIL] ' + name + (extra !== undefined ? ' → ' + JSON.stringify(extra) : '')); }
+}
+function skipTest(name, why) { skip++; console.log('[SKIP] ' + name + ' — ' + why); }
+
+const tmp = (tag) => fs.mkdtempSync(path.join(os.tmpdir(), 'jsql-native-' + tag + '-'));
+const SCHEMA = { id: { type: 'integer', primaryKey: true }, tag: { type: 'string' } };
+const hasHandles = typeof native.jsqlInstanceNew === 'function';
+
+(async () => {
+    console.log('--- 1. native 二进制能力探测 ---');
+    console.log('    句柄版 API: ' + (hasHandles ? '可用' : '不可用（旧版二进制）'));
+    ok('二进制可加载', !!native);
+    ok('旧版无句柄 API 仍存在（向后兼容）', typeof native.jsqlOpen === 'function');
+
+    if (hasHandles) {
+        console.log('--- 2. 两个独立引擎实例互不干扰（核心回归）---');
+        const dA = tmp('A'), dB = tmp('B');
+        const SC = JSON.stringify(SCHEMA);
+        const hA = native.jsqlInstanceNew();
+        native.jsqlOpenH(hA, dA, 'hybrid');
+        native.jsqlCreateTableH(hA, 't', SC);
+        native.jsqlInsertH(hA, 't', JSON.stringify([{ tag: 'A1' }]));
+        native.jsqlInsertH(hA, 't', JSON.stringify([{ tag: 'A2' }]));
+
+        // 关键：此时再开第二个库，旧版会把 A 的表全部清空
+        const hB = native.jsqlInstanceNew();
+        native.jsqlOpenH(hB, dB, 'hybrid');
+        native.jsqlCreateTableH(hB, 't', SC);
+        native.jsqlInsertH(hB, 't', JSON.stringify([{ tag: 'B1' }]));
+
+        ok('两个句柄不同', hA !== hB, { hA, hB });
+        ok('A 的数据未被 B 的 open() 清空', parseInt(native.jsqlCountH(hA, 't'), 10) === 2,
+            native.jsqlCountH(hA, 't'));
+        ok('B 的数据独立', parseInt(native.jsqlCountH(hB, 't'), 10) === 1,
+            native.jsqlCountH(hB, 't'));
+        const aRows = JSON.parse(native.jsqlFindH(hA, 't', '', 10, 0)).map(r => r.fields.tag);
+        const bRows = JSON.parse(native.jsqlFindH(hB, 't', '', 10, 0)).map(r => r.fields.tag);
+        ok('A 数据内容正确', JSON.stringify(aRows) === '["A1","A2"]', aRows);
+        ok('B 数据内容正确', JSON.stringify(bRows) === '["B1"]', bRows);
+
+        console.log('--- 3. 实例计数与销毁 ---');
+        ok('显式实例数为 2', native.jsqlInstanceCount() === 2, native.jsqlInstanceCount());
+        native.jsqlCloseH(hA); native.jsqlCloseH(hB);
+        JSON.parse(native.jsqlInstanceFree(hA));
+        JSON.parse(native.jsqlInstanceFree(hB));
+        ok('free 后实例归零', native.jsqlInstanceCount() === 0, native.jsqlInstanceCount());
+        ok('访问已销毁实例返回错误而非崩溃',
+            /no such database instance/.test(native.jsqlCountH(hA, 't')),
+            native.jsqlCountH(hA, 't'));
+        fs.rmSync(dA, { recursive: true, force: true });
+        fs.rmSync(dB, { recursive: true, force: true });
+    } else {
+        skipTest('多实例句柄测试', '旧版预编译二进制无 jsqlInstanceNew');
+    }
+
+    console.log('--- 4. 默认实例向后兼容（无句柄 API）---');
+    {
+        const dD = tmp('D');
+        const r = JSON.parse(native.jsqlOpen(dD, 'hybrid'));
+        ok('jsqlOpen 走默认实例可用', r.ok === true, r);
+        native.jsqlCreateTable('t', JSON.stringify(SCHEMA));
+        native.jsqlInsert('t', JSON.stringify([{ tag: 'legacy' }]));
+        ok('jsqlCount 默认实例可读', native.jsqlCount('t') === '1', native.jsqlCount('t'));
+        const rows = JSON.parse(native.jsqlFind('t', '', 10, 0)).map(r => r.fields.tag);
+        ok('默认实例数据正确', JSON.stringify(rows) === '["legacy"]', rows);
+        native.jsqlClose();
+        fs.rmSync(dD, { recursive: true, force: true });
+    }
+
+    console.log('--- 5. JS 层：两个 NativeJSQL 并存 ---');
+    {
+        const dA = tmp('jsA'), dB = tmp('jsB');
+        const A = new JSQL({ path: dA, mode: 'hybrid' });
+        const B = new JSQL({ path: dB, mode: 'hybrid' });
+        await A.start();
+        await B.start();
+        if (hasHandles) {
+            ok('JS 层已启用多实例', A._multiInstance === true);
+            ok('两实例句柄不同', A._handle !== B._handle, { a: A._handle, b: B._handle });
+        } else {
+            ok('旧版二进制下回退单实例（_handle 为 null）', A._handle === null);
+        }
+        await A.createTable('t', SCHEMA);
+        await A.insert('t', { tag: 'A1' });
+        await A.insert('t', { tag: 'A2' });
+        await B.createTable('t', SCHEMA);
+        await B.insert('t', { tag: 'B1' });
+
+        const ca = await A.count('t'), cb = await B.count('t');
+        ok('A 保留自己的 2 行', ca === 2, ca);
+        ok('B 有自己的 1 行', cb === 1, cb);
+        const ra = (await A.find('t', {})).map(r => r.tag);
+        ok('A 数据内容正确', JSON.stringify(ra) === '["A1","A2"]', ra);
+
+        await B.createTable('only_b', { id: { type: 'integer', primaryKey: true } });
+        let aSeesB = true;
+        try { await A.find('only_b', {}); aSeesB = false; } catch (e) { aSeesB = true; }
+        ok('A 看不到 B 独有的表', aSeesB);
+
+        await A.stop();
+        await B.stop();
+        if (hasHandles) ok('stop 释放句柄', A._handle === null && B._handle === null);
+        fs.rmSync(dA, { recursive: true, force: true });
+        fs.rmSync(dB, { recursive: true, force: true });
+    }
+
+    console.log(`\n${pass} passed, ${fail} failed${skip ? ', ' + skip + ' skipped' : ''}`);
+    process.exit(fail === 0 ? 0 : 1);
+})().catch(e => { console.error('FATAL', e); process.exit(1); });

package/test/readme-audit.test.js

@@ -528,6 +528,31 @@ async function main() {
     ok('null bulk $-1', JSON.stringify((p('*2\r\n$3\r\nGET\r\n$-1\r\n') || {}).args) === '[null]');
   }
 
+  console.log('--- 版本号一致性（package.json 是唯一真相）---');
+  {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+    const raw = fs.readFileSync(path.join(__dirname, '..', 'README.md'), 'utf8');
+    const v = pkg.version;
+    ok('package.json 版本号格式合法', /^\d+\.\d+\.\d+$/.test(v), v);
+
+    // README 头部横幅必须与 package.json 一致
+    const banner = raw.match(/^> \*\*v(\d+\.\d+\.\d+)\*\*/m);
+    ok('README 顶部版本横幅与 package.json 一致', banner && banner[1] === v,
+      banner ? `README=${banner[1]} package=${v}` : '未找到顶部横幅');
+
+    // 所有 "jsql-neo vX.Y.Z" / "文档版本：vX.Y.Z" 形式的版本声明都必须等于当前版本
+    const claims = [...raw.matchAll(/(?:jsql-neo v|文档版本：v|ver=)(\d+\.\d+\.\d+)/g)]
+      .map(m => m[1]);
+    const stale = [...new Set(claims.filter(c => c !== v))];
+    ok('README 无陈旧版本号声明', stale.length === 0, stale);
+
+    // index.js 头部注释也必须同步
+    const idx = fs.readFileSync(path.join(__dirname, '..', 'index.js'), 'utf8');
+    const hdr = idx.match(/JSQL-NEO v(\d+\.\d+\.\d+)/);
+    ok('index.js 头部版本注释与 package.json 一致', hdr && hdr[1] === v,
+      hdr ? `index.js=${hdr[1]} package=${v}` : '未找到版本注释');
+  }
+
   console.log(`\n${pass} passed, ${fail} failed`);
   process.exit(fail === 0 ? 0 : 1);
 }

package/test/wal-recovery.test.js

@@ -0,0 +1,161 @@
+/*
+ * WAL 崩溃恢复回归测试（P1-1）
+ *
+ * 背景：6.3.3 及以前的 _recoverFromWAL() 只做 fs.unlinkSync 删除 WAL 文件，
+ * 从不回放任何操作；且构造函数用 fs.existsSync(dataFile) 短路，
+ * 新建库崩溃后连 WAL 都不会被读取。合起来的效果是：
+ * 「WAL / 崩溃恢复」是虚假宣传 —— 实测开启 wal:true 后 kill -9 必然丢数据。
+ *
+ * 6.3.4 修复：
+ *   1. WAL 改为 append-only JSONL + fsync
+ *   2. insert/update/removeById 现在都写 WAL
+ *   3. _recoverFromWAL 真正按 sequence 顺序回放
+ *   4. 构造函数在「数据文件不存在但 WAL 存在」时也走恢复流程
+ *   5. .jsql 二进制格式分支不再提前 return 跳过恢复
+ *
+ * 本测试用「不调用 save() 直接丢弃实例」模拟 kill -9。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const Database = require('../lib/database.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) : '')); }
+}
+
+function tmpFile(tag) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsql-wal-' + tag + '-'));
+    return { dir, file: path.join(dir, 'db.jsql') };
+}
+const SCHEMA = { id: { type: 'integer', primaryKey: true }, v: { type: 'string' }, n: { type: 'integer' } };
+
+(async () => {
+    console.log('--- 1. 全新库崩溃：WAL 必须恢复出全部数据 ---');
+    {
+        const { dir, file } = tmpFile('new');
+        const db = new Database(file, { wal: true, autoSave: false });
+        await db.createTable('t', SCHEMA);
+        await db.insert('t', { id: 1, v: 'important' });
+        await db.insert('t', { id: 2, v: 'second' });
+        await db.updateById('t', 1, { v: 'updated' });
+        await db.insert('t', { id: 3, v: 'third' });
+        await db.removeById('t', 3);
+        // 模拟 kill -9：直接丢弃，不 save 不 stop
+        const db2 = new Database(file, { wal: true });
+        const rows = await db2.find('t', {});
+        ok('崩溃后表仍存在', Object.keys(db2._tables).includes('t'));
+        ok('崩溃后行数正确 (2)', rows.length === 2, rows.length);
+        ok('崩溃后 update 已回放', rows.find(r => r.id === 1)?.v === 'updated', rows);
+        ok('崩溃后第二行存在', rows.find(r => r.id === 2)?.v === 'second');
+        ok('崩溃后 delete 已回放', !rows.find(r => r.id === 3));
+        ok('回放后 WAL 已检查点', !fs.existsSync(file + '.wal'));
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log('--- 2. 快照 + WAL 叠加：save 后的新写入也要恢复 ---');
+    {
+        const { dir, file } = tmpFile('mix');
+        const db = new Database(file, { wal: true, autoSave: false });
+        await db.createTable('t', SCHEMA);
+        await db.insert('t', { id: 1, v: 'a' });
+        await db.insert('t', { id: 2, v: 'b' });
+        db.save();                       // 快照：2 行，WAL 应清空
+        ok('save 后 WAL 被清空', !fs.existsSync(file + '.wal'));
+        await db.insert('t', { id: 3, v: 'c-after-save' });   // 只进 WAL
+        const db2 = new Database(file, { wal: true });
+        const rows = await db2.find('t', {});
+        ok('快照 2 行 + WAL 1 行 = 3 行', rows.length === 3, rows.length);
+        ok('WAL 中的新行已恢复', rows.find(r => r.id === 3)?.v === 'c-after-save');
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log('--- 3. 幂等：二次重开不得重复回放 ---');
+    {
+        const { dir, file } = tmpFile('idem');
+        const db = new Database(file, { wal: true, autoSave: false });
+        await db.createTable('t', SCHEMA);
+        await db.insert('t', { id: 1, v: 'x' });
+        await db.insert('t', { id: 2, v: 'y' });
+        const db2 = new Database(file, { wal: true });
+        const r2 = await db2.find('t', {});
+        const db3 = new Database(file, { wal: true });
+        const r3 = await db3.find('t', {});
+        ok('首次恢复 2 行', r2.length === 2, r2.length);
+        ok('二次重开仍 2 行（不重复回放）', r3.length === 2, r3.length);
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log('--- 4. WAL 为 append-only JSONL，崩溃写半的尾行可容错 ---');
+    {
+        const { dir, file } = tmpFile('torn');
+        const db = new Database(file, { wal: true, autoSave: false });
+        await db.createTable('t', SCHEMA);
+        await db.insert('t', { id: 1, v: 'ok' });
+        // 模拟崩溃时最后一行只写了一半
+        fs.appendFileSync(file + '.wal', '{"op":"insert","table":"t","ro');
+        const db2 = new Database(file, { wal: true });
+        const rows = await db2.find('t', {});
+        ok('半截尾行被丢弃，完整记录仍恢复', rows.length === 1, rows.length);
+        ok('数据内容正确', rows[0] && rows[0].v === 'ok', rows);
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log('--- 5. deleteById / dropTable 也进 WAL ---');
+    {
+        const { dir, file } = tmpFile('del');
+        const db = new Database(file, { wal: true, autoSave: false });
+        await db.createTable('t', SCHEMA);
+        await db.createTable('u', SCHEMA);
+        await db.insert('t', { id: 1, v: 'a' });
+        await db.insert('u', { id: 1, v: 'b' });
+        await db.dropTable('u');
+        const db2 = new Database(file, { wal: true });
+        ok('被 drop 的表未复活', !db2._tables.u, Object.keys(db2._tables));
+        ok('保留的表数据完整', (await db2.find('t', {})).length === 1);
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log('--- 6. 未开启 wal 时不应产生 .wal 文件 ---');
+    {
+        const { dir, file } = tmpFile('off');
+        const db = new Database(file, { wal: false, autoSave: false });
+        await db.createTable('t', SCHEMA);
+        await db.insert('t', { id: 1, v: 'a' });
+        ok('未开启 wal 时无 .wal 文件', !fs.existsSync(file + '.wal'));
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log('--- 6b. 兼容 6.3.3 的旧格式 WAL（单行 JSON 数组）---');
+    {
+        // 升级场景：用户本地残留旧版写出的数组格式 WAL，不得被静默丢弃
+        const { dir, file } = tmpFile('oldfmt');
+        fs.writeFileSync(file + '.wal', JSON.stringify([
+            { op: 'createTable', table: 'legacy', schema: SCHEMA },
+        ]));
+        const db = new Database(file, { wal: true });
+        ok('旧格式数组 WAL 能被回放', !!db._tables.legacy, Object.keys(db._tables));
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log('--- 7. 回放后索引仍可用（B-Tree 重建）---');
+    {
+        const { dir, file } = tmpFile('idx');
+        const db = new Database(file, { wal: true, autoSave: false });
+        await db.createTable('t', SCHEMA);
+        db.createTable && 0;
+        for (let i = 1; i <= 30; i++) await db.insert('t', { id: i, v: 'v' + i, n: i });
+        db._tables.t.createIndex('n');
+        const db2 = new Database(file, { wal: true });
+        const found = await db2.find('t', { n: 17 });
+        ok('回放后按索引字段查询正确', found.length === 1 && found[0].id === 17, found);
+        const cnt = await db2.find('t', { n: { $gte: 25 } });
+        ok('回放后范围查询正确', cnt.length === 6, cnt.length);
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    console.log(`\n${pass} passed, ${fail} failed`);
+    process.exit(fail === 0 ? 0 : 1);
+})().catch(e => { console.error('FATAL', e); process.exit(1); });