jsql-neo 4.5.2 → 5.0.1

package/README.md

@@ -284,6 +284,6 @@ CI (`.github/workflows/ci.yml`): engine smoke tests on Node 18/20/22 + a full OR
 
 ## License
 
-MIT — use it, ship it, love it.
+[Apache-2.0](LICENSE) — free to use, modify, and distribute with attribution.
 
 *JSQL-NEO: Rust-powered. Protocol-native. One package.*

package/lib/sql.js

@@ -56,7 +56,7 @@ const KEYWORDS = new Set([
   'BETWEEN', 'USING', 'FULL', 'UNSIGNED', 'ZEROFILL', 'TRUNCATE', 'COLLATE', 'CHARACTER',
   'ALTER', 'ADD', 'COLUMN', 'MODIFY', 'CHANGE', 'INDEX', 'FOREIGN', 'REFERENCES',
   'CONSTRAINT', 'RENAME', 'TO', 'AFTER', 'FIRST', 'ENGINE', 'AUTO_INCREMENT', 'SPATIAL',
-  'REGEXP', 'TRUE', 'FALSE', 'RLIKE'
+  'REGEXP', 'TRUE', 'FALSE', 'RLIKE', 'PRAGMA', 'REPLACE', 'BLOB', 'RAISE', 'IGNORE'
 ]);
 
 function tokenize(sql) {
@@ -245,6 +245,7 @@ class Parser {
       case 'SET': return this.parseSet();
       case 'DESCRIBE': case 'DESC': return this.parseDescribe();
       case 'USE': return this.parseUse();
+      case 'PRAGMA': return this.parsePragma();
       default: throw new Error(`Unsupported statement: ${t.value}`);
     }
   }
@@ -380,9 +381,14 @@ class Parser {
       if (t.type === 'keyword') {
         switch (t.value) {
           case 'PRIMARY':
-            this.next(); this.expectKeyword('KEY'); def.primaryKey = true; def.unique = true; break;
+            this.next(); this.expectKeyword('KEY'); def.primaryKey = true; def.unique = true;
+            // SQLite 语义: INTEGER PRIMARY KEY 是 rowid 别名, 自动生成
+            if (mapped === 'integer') def.autoIncrement = true;
+            break;
           case 'KEY':
-            this.next(); def.primaryKey = true; def.unique = true; break;
+            this.next(); def.primaryKey = true; def.unique = true;
+            if (mapped === 'integer') def.autoIncrement = true;
+            break;
           case 'AUTO_INCREMENT':
           case 'AUTOINCREMENT':
             this.next(); def.autoIncrement = true; break;
@@ -952,6 +958,37 @@ class Parser {
     return { type: 'use', database: db };
   }
 
+  parsePragma() {
+    this.expectKeyword('PRAGMA');
+    let name = '';
+    const first = this.next();
+    if (first.type !== 'ident' && first.type !== 'keyword') throw new Error(`Expected pragma name, got '${first.value}'`);
+    name = first.value;
+    // pragma 名可能带 db. 前缀: PRAGMA main.table_info(users)
+    if (this.peek().type === 'op' && this.peek().value === '.') {
+      this.next();
+      const second = this.next();
+      if (second.type !== 'ident' && second.type !== 'keyword') throw new Error(`Expected pragma name after '.', got '${second.value}'`);
+      name = first.value + '.' + second.value;
+    }
+    let arg = null;
+    if (this.peek().type === 'op' && this.peek().value === '(') {
+      this.next();
+      const a = this.next();
+      if (a.type !== 'op' && a.type !== 'eof') arg = a.value;
+      if (this.peek().type === 'op' && this.peek().value === ')') this.next();
+    } else if (this.peek().type === 'op' && this.peek().value === '=') {
+      this.next();
+      const v = this.next();
+      if (v.type === 'number' || v.type === 'ident' || v.type === 'keyword' || v.type === 'string') arg = v.value;
+    } else if (this.peek().type !== 'eof' && !(this.peek().type === 'op' && this.peek().value === ';')) {
+      const v = this.next();
+      if (v.type === 'number' || v.type === 'ident' || v.type === 'keyword') arg = v.value;
+    }
+    this.optionalTailSemicolon();
+    return { type: 'pragma', name, arg };
+  }
+
   optionalTailSemicolon() {
     if (this.peek().type === 'op' && this.peek().value === ';') this.next();
   }
@@ -1012,7 +1049,8 @@ class Parser {
         const args = [];
         if (!(this.peek().type === 'op' && this.peek().value === ')')) {
           for (;;) {
-            args.push(this.parseOperand());
+            if (this.peek().type === 'op' && this.peek().value === '*') { this.next(); args.push({ type: 'star' }); }
+            else args.push(this.parseOperand());
             if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
             break;
           }
@@ -1032,7 +1070,8 @@ class Parser {
       const args = [];
       if (!(this.peek().type === 'op' && this.peek().value === ')')) {
         for (;;) {
-          args.push(this.parseOperand());
+          if (this.peek().type === 'op' && this.peek().value === '*') { this.next(); args.push({ type: 'star' }); }
+          else args.push(this.parseOperand());
           if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
           break;
         }
@@ -1319,9 +1358,13 @@ function applyScalarFunction(fnNode, row, ctx) {
   const name = (fnNode.name || '').toUpperCase();
   const args = (fnNode.args || []).map(a => resolveOperand(a, row, ctx));
   const session = ctx && ctx.session;
+  if (ctx && ctx.functions && Object.prototype.hasOwnProperty.call(ctx.functions, name)) {
+    return ctx.functions[name].apply(null, args);
+  }
   switch (name) {
     case 'VERSION': return '8.0.0-jsql-neo';
-    case 'LAST_INSERT_ID': {
+    case 'LAST_INSERT_ID':
+    case 'LAST_INSERT_ROWID': {
       if (args.length > 0) {
         if (session) session.lastInsertId = args[0];
         return args[0];
@@ -1564,7 +1607,15 @@ function scalarColumnName(c) {
 }
 
 function scalarColumnValue(c, r, ctx) {
-  if (c.scalar) return resolveOperand(c.scalar, r, ctx);
+  if (c.scalar) {
+    const s = c.scalar;
+    if (s && s.type === 'func' && ctx && ctx.ctxAggregates && Object.prototype.hasOwnProperty.call(ctx.ctxAggregates, String(s.name).toUpperCase())) {
+      const fn = String(s.name).toUpperCase();
+      const col = s.args && s.args[0];
+      return ctx._aggValue(ctx.group, fn, col);
+    }
+    return resolveOperand(c.scalar, r, ctx);
+  }
   if (c.aggregate) return ctx._aggValue(ctx.group, c.aggregate || 'COUNT', c.column);
   if (c.literal !== undefined) return c.literal;
   if (c.caseExpr) return evaluateCaseVal(c.caseExpr, r, ctx);
@@ -1979,6 +2030,16 @@ class SQLExecutor {
           await this.engine.useDatabase(statement.database);
         }
         return { ok: true, type: 'use', database: statement.database };
+      case 'pragma': {
+        const rows = this._runPragma(statement.name, statement.arg);
+        const isSelect = ['table_info', 'table_list', 'index_list', 'index_info', 'collation_list', 'database_list', 'module_list', 'function_list', 'pragma_list'].includes(statement.name.toLowerCase());
+        if (isSelect) {
+          const cols = rows.length > 0 ? Object.keys(rows[0]) : [];
+          return { ok: true, type: 'select', columns: cols, rows: rows.map(r => cols.map(c => r[c])), raw: rows };
+        }
+        const simple = rows.length > 0 && Object.keys(rows[0]).length === 1 ? rows[0][Object.keys(rows[0])[0]] : rows;
+        return { ok: true, type: 'pragma', name: statement.name, value: simple };
+      }
       case 'describe': {
         const schema = this.engine.getTableSchema ? await this.engine.getTableSchema(statement.table) : null;
         if (!schema) throw new Error(`Table '${statement.table}' does not exist`);
@@ -1990,6 +2051,110 @@ class SQLExecutor {
     }
   }
 
+  _runPragma(name, arg) {
+    const engine = this.engine;
+    const lname = String(name).toLowerCase().replace(/^.*\./, '');
+    const rows = [];
+    switch (lname) {
+      case 'table_info': {
+        const schema = engine.getTableSchema ? engine.getTableSchema(arg) : (engine._schemas ? engine._schemas[arg] : null);
+        if (!schema) throw new Error(`table ${arg} may not be queried: no such table`);
+        let cid = 0;
+        for (const [col, def] of Object.entries(schema)) {
+          let typeName = String(def.type || 'text').toUpperCase();
+          if (typeName === 'NUMBER') typeName = 'REAL';
+          if (typeName === 'OBJECT' || typeName === 'ARRAY') typeName = 'TEXT';
+          rows.push({
+            cid,
+            name: col,
+            type: typeName,
+            notnull: def.required ? 1 : 0,
+            dflt_value: def.default !== undefined ? def.default : null,
+            pk: def.primaryKey ? 1 : 0,
+          });
+          cid++;
+        }
+        break;
+      }
+      case 'table_list': {
+        const tables = engine.listTables ? engine.listTables() : Array.from(engine._tableNames || []);
+        for (const t of tables) {
+          rows.push({ schema: 'main', name: t, type: 'table', ncol: 0, wr: 1, strict: 0 });
+        }
+        break;
+      }
+      case 'index_list': {
+        const schema = engine.getTableSchema ? engine.getTableSchema(arg) : (engine._schemas ? engine._schemas[arg] : null);
+        if (!schema) throw new Error(`table ${arg} may not be queried: no such table`);
+        let seq = 0;
+        for (const [col, def] of Object.entries(schema)) {
+          if (def.primaryKey || def.unique) {
+            rows.push({ seq, name: 'sqlite_autoindex_' + arg + '_' + (seq + 1), unique: def.unique ? 1 : 0, origin: def.primaryKey ? 'pk' : 'u', partial: 0 });
+            seq++;
+          }
+        }
+        break;
+      }
+      case 'index_info': {
+        const schema = engine.getTableSchema ? engine.getTableSchema(arg) : (engine._schemas ? engine._schemas[arg] : null);
+        if (!schema) throw new Error(`no such index: ${arg}`);
+        let seqno = 0;
+        for (const [col, def] of Object.entries(schema)) {
+          if (def.primaryKey || def.unique) {
+            rows.push({ seqno, cid: seqno, name: col });
+            seqno++;
+          }
+        }
+        break;
+      }
+      case 'database_list': {
+        rows.push({ seq: 0, name: 'main', file: '' });
+        break;
+      }
+      case 'user_version': {
+        const val = arg !== undefined && arg !== null ? arg : ((engine._pragmaValues && engine._pragmaValues.user_version) || 0);
+        if (arg !== undefined && arg !== null) {
+          engine._pragmaValues = engine._pragmaValues || {};
+          engine._pragmaValues.user_version = Number(arg);
+        }
+        rows.push({ user_version: val });
+        break;
+      }
+      case 'journal_mode': {
+        rows.push({ journal_mode: arg !== undefined && arg !== null ? arg : 'memory' });
+        break;
+      }
+      case 'foreign_keys': {
+        rows.push({ foreign_keys: arg !== undefined && arg !== null ? arg : 0 });
+        break;
+      }
+      case 'synchronous': {
+        rows.push({ synchronous: arg !== undefined && arg !== null ? arg : 0 });
+        break;
+      }
+      case 'cache_size': {
+        rows.push({ cache_size: arg !== undefined && arg !== null ? arg : 0 });
+        break;
+      }
+      case 'page_size':
+      case 'encoding':
+      case 'auto_vacuum':
+      case 'temp_store':
+      case 'locking_mode':
+      case 'application_id':
+      case 'integrity_check':
+      case 'quick_check': {
+        rows.push({ [lname]: lname === 'encoding' ? 'UTF-8' : (arg !== undefined && arg !== null ? arg : 0) });
+        break;
+      }
+      default: {
+        rows.push({ [lname]: arg !== undefined && arg !== null ? arg : 0 });
+        break;
+      }
+    }
+    return rows;
+  }
+
   async _getSchema(name) {
     if (this.engine.hasTable && !this.engine.hasTable(name)) {
       throw new Error(`Table '${name}' does not exist`);
@@ -2204,7 +2369,20 @@ class SQLExecutor {
   _aggValue(rows, fn, column) {
     if (fn === 'COUNT') return rows.length;
     const op = typeof column === 'string' ? { type: 'column', name: column } : column;
-    const values = rows.map(r => resolveOperand(op, r, this.ctx)).filter(v => v !== null && v !== undefined);
+    const values = op && op.type === 'star'
+      ? rows.map(r => 1)
+      : rows.map(r => resolveOperand(op, r, this.ctx)).filter(v => v !== null && v !== undefined);
+    if (this.ctx && this.ctx.aggregates && Object.prototype.hasOwnProperty.call(this.ctx.aggregates, fn)) {
+      const agg = this.ctx.aggregates[fn];
+      if (typeof agg === 'function') {
+        return agg(values);
+      }
+      if (agg && typeof agg.step === 'function') {
+        let state = typeof agg.start === 'function' ? agg.start() : undefined;
+        for (const v of values) state = agg.step(state, v);
+        return typeof agg.result === 'function' ? agg.result(state) : state;
+      }
+    }
     if (fn === 'SUM') return values.reduce((s, v) => s + (typeof v === 'number' ? v : Number(v) || 0), 0);
     if (fn === 'AVG') return values.length ? values.reduce((s, v) => s + (typeof v === 'number' ? v : Number(v) || 0), 0) / values.length : null;
     if (fn === 'MIN') return values.length ? Math.min(...values.map(v => Number(v))) : null;
@@ -2396,10 +2574,17 @@ class SQLExecutor {
     }
 
     // 聚合输出（无 GROUP BY 时）
-    if (!statement.groupBy && statement.columns.some(c => c.aggregate)) {
+    const hasCustomAgg = this.ctx && this.ctx.aggregates && statement.columns.some(c => c.scalar && c.scalar.type === 'func' && Object.prototype.hasOwnProperty.call(this.ctx.aggregates, String(c.scalar.name).toUpperCase()));
+    if (!statement.groupBy && (statement.columns.some(c => c.aggregate) || hasCustomAgg)) {
       const cols = statement.columns.map(c => scalarColumnName(c));
       const valueOf = (c) => {
         if (c.aggregate) return this._aggValue(rows, c.aggregate || 'COUNT', c.column);
+        if (c.scalar && c.scalar.type === 'func' && hasCustomAgg) {
+          const fn = String(c.scalar.name).toUpperCase();
+          if (Object.prototype.hasOwnProperty.call(this.ctx.aggregates, fn)) {
+            return this._aggValue(rows, fn, c.scalar.args && c.scalar.args[0]);
+          }
+        }
         if (c.scalar) return resolveOperand(c.scalar, rows[0] || {}, this.ctx);
         if (c.caseExpr) return resolveOperand(c.caseExpr, rows[0] || {}, this.ctx);
         if (c.expr !== null && c.expr !== '*') return rows[0] ? resolveOperand({ type: 'column', name: c.expr }, rows[0]) : null;
@@ -2413,7 +2598,7 @@ class SQLExecutor {
       const cols = statement.columns.map(c => scalarColumnName(c));
       const mapped = rows.map(r => {
         const group = r._group || [r];
-        return statement.columns.map(c => scalarColumnValue(c, r, { _aggValue: this._aggValue.bind(this), group }));
+        return statement.columns.map(c => scalarColumnValue(c, r, { _aggValue: this._aggValue.bind(this), group, ctxAggregates: this.ctx ? this.ctx.aggregates : null }));
       });
       return { ok: true, type: 'select', table: statement.from ? (statement.from.tables[0].table || null) : null, columns: cols, rows: mapped, raw: rows };
     }
@@ -2578,6 +2763,11 @@ function applyParams(sql, values) {
   let idx = 0;
   let inStr = null;
   let i = 0;
+  const named = {};
+  let hasNamed = false;
+  if (args && typeof args === 'object' && !Array.isArray(args)) {
+    hasNamed = true;
+  }
   while (i < sql.length) {
     const c = sql[i];
     if (inStr) {
@@ -2589,23 +2779,53 @@ function applyParams(sql, values) {
     }
     if (c === "'" || c === '"' || c === '`') { inStr = c; out += c; i++; continue; }
     if (c === '?' && sql[i + 1] === '?') {
-      if (idx >= args.length) throw new Error('Not enough parameters for SQL: expected ' + (count + 1));
-      out += escapeId(args[idx++]);
+      if (!hasNamed && idx >= args.length) throw new Error('Not enough parameters for SQL: expected ' + (count + 1));
+      out += escapeId(hasNamed ? args['@@'] : args[idx++]);
       count++;
       i += 2;
       continue;
     }
     if (c === '?') {
-      if (idx >= args.length) throw new Error('Not enough parameters for SQL: expected ' + (count + 1));
-      out += escapeValue(args[idx++]);
+      if (sql[i + 1] >= '0' && sql[i + 1] <= '9') {
+        // ?N 编号占位符
+        let num = '';
+        let j = i + 1;
+        while (j < sql.length && sql[j] >= '0' && sql[j] <= '9') { num += sql[j]; j++; }
+        const n = parseInt(num, 10);
+        if (hasNamed) {
+          if (!(n in args)) throw new Error(`No value for parameter ?${n}`);
+          out += escapeValue(args[n]);
+        } else {
+          if (n - 1 >= args.length) throw new Error(`Not enough parameters for SQL: expected ?${n}`);
+          out += escapeValue(args[n - 1]);
+          if (n > idx) idx = n;
+        }
+        count++;
+        i = j;
+        continue;
+      }
+      if (!hasNamed && idx >= args.length) throw new Error('Not enough parameters for SQL: expected ' + (count + 1));
+      out += escapeValue(hasNamed ? args['?'] : args[idx++]);
       count++;
       i++;
       continue;
     }
+    if ((c === ':' || c === '@' || c === '$') && i + 1 < sql.length && /[A-Za-z_]/.test(sql[i + 1])) {
+      // 命名占位符 :name @name $name
+      let name = '';
+      let j = i + 1;
+      while (j < sql.length && /[A-Za-z0-9_]/.test(sql[j])) { name += sql[j]; j++; }
+      if (!hasNamed) throw new Error(`Named parameter ${c}${name} requires an object of parameters`);
+      if (!(name in args)) throw new Error(`No value for parameter ${c}${name}`);
+      out += escapeValue(args[name]);
+      count++;
+      i = j;
+      continue;
+    }
     out += c;
     i++;
   }
-  if (idx !== args.length) {
+  if (!hasNamed && idx !== args.length) {
     throw new Error(`Too many parameters for SQL: got ${args.length}, expected ${count}`);
   }
   return out;
@@ -2632,7 +2852,11 @@ async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
       if (dangerous) throw new Error(`SQL statement blocked by security policy: ${dangerous}`);
     }
   }
-  const executor = new SQLExecutor(engine, opts.session ? { session: opts.session } : null);
+  const ctx = {};
+  if (opts.session) ctx.session = opts.session;
+  if (opts.functions && typeof opts.functions === 'object') ctx.functions = opts.functions;
+  if (opts.aggregates && typeof opts.aggregates === 'object') ctx.aggregates = opts.aggregates;
+  const executor = new SQLExecutor(engine, Object.keys(ctx).length > 0 ? ctx : null);
   const results = [];
   for (const stmtSql of statements) {
     const stmt = parseSQL(stmtSql);

package/lib/sqlite_compat.js

@@ -0,0 +1,323 @@
+// © Vexify 2026 All Rights Reserved.
+/**
+ * better-sqlite3 兼容层 — 主线程
+ *
+ * 提供与 better-sqlite3 完全一致的同步 API：
+ *   const Database = require('jsql-neo/sqlite');
+ *   const db = new Database('file.db');
+ *   const row = db.prepare('SELECT * FROM users WHERE id = ?').get(1);
+ *
+ * 底层通过 worker_threads + SharedArrayBuffer(Atomics) 同步桥调用 JSQL 引擎。
+ * 每个操作：主线程 postMessage 请求 → Atomics.wait 阻塞 → worker 完成后
+ * postMessage 结果 + Atomics.notify → 主线程 receiveMessageOnPort 同步取回。
+ */
+
+const { Worker, MessageChannel, receiveMessageOnPort } = require('worker_threads');
+const path = require('path');
+
+const WORKER_PATH = path.join(__dirname, 'sqlite_worker.js');
+
+class SqliteError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'SqliteError';
+    this.code = code || 'SQLITE_ERROR';
+  }
+}
+
+class Database {
+  constructor(filename = ':memory:', options = {}) {
+    if (filename !== null && filename !== undefined && typeof filename !== 'string') {
+      throw new TypeError('The first argument must be a string or undefined');
+    }
+    this.name = filename || ':memory:';
+    this.memory = this.name === ':memory:';
+    this.readonly = !!options.readonly;
+    this.open = true;
+    this._options = options;
+    this._sab = new SharedArrayBuffer(4);
+    this._ctrl = new Int32Array(this._sab);
+    this._seq = 0;
+    const channel = new MessageChannel();
+    this._port = channel.port2;
+    this._worker = new Worker(WORKER_PATH, {
+      workerData: { filename: this.name, options, port: channel.port1 },
+      transferList: [channel.port1],
+    });
+    this._sync('start', [this.name, this._options]);
+  }
+
+  _sync(op, args) {
+    if (!this.open && op !== 'close') throw new SqliteError('The database connection is not open', 'SQLITE_MISUSE');
+    const id = ++this._seq;
+    // 预先清空控制槽，避免读到旧值
+    Atomics.store(this._ctrl, 0, 0);
+    this._worker.postMessage({ id, op, args, sab: this._sab });
+    // 阻塞直到 worker 完成（ctrl[0] === id）
+    const wait = Atomics.wait(this._ctrl, 0, 0);
+    if (wait === 'not-equal') {
+      // 已经完成，直接取
+    } else if (wait === 'timed-out' || wait === 'not-equal') {
+      // 重新等待
+    }
+    // 取结果（同步从端口队列读取）
+    let result;
+    let guard = 0;
+    while (true) {
+      const msg = receiveMessageOnPort(this._port);
+      if (msg && msg.message && msg.message.id === id) {
+        result = msg.message;
+        break;
+      }
+      // 消息可能尚未到达（竞态），再等一次
+      const w2 = Atomics.wait(this._ctrl, 0, id - 1);
+      if (w2 !== 'ok' && ++guard > 1000) break;
+    }
+    if (!result) throw new SqliteError('Worker did not respond', 'SQLITE_INTERNAL');
+    if (!result.ok) throw new SqliteError(result.error.message, result.error.code);
+    return result.result;
+  }
+
+  close() {
+    if (!this.open) return;
+    try {
+      this._sync('close', []);
+    } finally {
+      this.open = false;
+      this._worker.terminate();
+    }
+  }
+
+  prepare(sql) {
+    if (typeof sql !== 'string') throw new TypeError('The "sql" argument must be a string');
+    return new Statement(this, sql);
+  }
+
+  exec(sql) {
+    if (typeof sql !== 'string') throw new TypeError('The "sql" argument must be a string');
+    this._sync('exec', [sql, null]);
+    return this;
+  }
+
+  pragma(pragma, options = {}) {
+    if (typeof pragma !== 'string') throw new TypeError('The "pragma" argument must be a string');
+    const { simple } = options;
+    const sql = /^\s*pragma\b/i.test(pragma) ? pragma : 'PRAGMA ' + pragma;
+    const name = (pragma.replace(/^\s*pragma\b\s*/i, '').split(/[=(]/)[0] || '').trim();
+    const r = this._sync('all', [sql, null]);
+    if (simple) {
+      if (Array.isArray(r)) {
+        const first = r.length > 0 ? r[0] : null;
+        if (first && typeof first === 'object') {
+          const keys = Object.keys(first);
+          return keys.length === 1 ? first[keys[0]] : first;
+        }
+        return first;
+      }
+      return r;
+    }
+    if (!Array.isArray(r)) return [{ [name || 'value']: r }];
+    if (r.length > 0 && (typeof r[0] !== 'object' || r[0] === null)) {
+      return r.map(v => ({ [name || 'value']: v }));
+    }
+    return r;
+  }
+
+  transaction(fn) {
+    if (typeof fn !== 'function') throw new TypeError('Expected a function');
+    const wrapped = (...params) => {
+      if (!this.open) throw new SqliteError('The database connection is not open', 'SQLITE_MISUSE');
+      this.exec('BEGIN');
+      try {
+        const result = fn.apply(this, params);
+        if (result && typeof result.then === 'function') {
+          this.exec('ROLLBACK');
+          throw new SqliteError('Transaction functions cannot be asynchronous', 'SQLITE_MISUSE');
+        }
+        this.exec('COMMIT');
+        return result;
+      } catch (err) {
+        try { this.exec('ROLLBACK'); } catch (e) {}
+        throw err;
+      }
+    };
+    wrapped.deferred = () => wrapped;
+    wrapped.immediate = () => wrapped;
+    wrapped.exclusive = () => wrapped;
+    wrapped.default = wrapped;
+    return wrapped;
+  }
+
+  function(name, options, fn) {
+    if (typeof options === 'function') { fn = options; options = {}; }
+    if (typeof fn !== 'function') throw new TypeError('Expected a function');
+    const fnStr = fn.toString();
+    if (/\[native code\]/.test(fnStr)) {
+      throw new SqliteError(`Cannot register native function '${name}'. Only source-available functions work over the worker bridge.`, 'SQLITE_FEATURE_NOT_SUPPORTED');
+    }
+    this._sync('registerFunction', [name, fnStr, !!(options && options.deterministic)]);
+    return this;
+  }
+
+  aggregate(name, options, factory) {
+    if (typeof options === 'function') { factory = options; options = {}; }
+    if (typeof options === 'object' && options !== null && factory === undefined) { factory = options; options = {}; }
+    if (typeof factory !== 'function' && (typeof factory !== 'object' || factory === null)) {
+      throw new TypeError('Expected a function or aggregate object');
+    }
+    // 单函数形式: (values) => result；对象形式: { start, step, result }
+    let specStr;
+    if (typeof factory === 'function') {
+      specStr = factory.toString();
+      if (/\[native code\]/.test(specStr)) {
+        throw new SqliteError(`Cannot register native aggregate '${name}'`, 'SQLITE_FEATURE_NOT_SUPPORTED');
+      }
+    } else {
+      const parts = [];
+      for (const key of ['start', 'step', 'result']) {
+        const f = factory[key];
+        if (typeof f === 'function') parts.push(`${key}: ${f.toString()}`);
+      }
+      specStr = '{ ' + parts.join(', ') + ' }';
+    }
+    this._sync('registerAggregate', [name, specStr, !!(options && options.deterministic)]);
+    return this;
+  }
+
+  table(name, options, fn) {
+    throw new SqliteError('db.table() is not supported by the worker bridge', 'SQLITE_FEATURE_NOT_SUPPORTED');
+  }
+  serialize() {
+    return Buffer.from(this._sync('serialize', []));
+  }
+
+  deserialize(buffer) {
+    const buf = Buffer.from(buffer);
+    this._sync('deserialize', [buf]);
+    return this;
+  }
+
+  loadExtension() {
+    throw new SqliteError('db.loadExtension() is not supported: JSQL-NEO does not support loading native SQLite extensions', 'SQLITE_FEATURE_NOT_SUPPORTED');
+  }
+
+  backup(destination, options) {
+    const dump = this._sync('backup', []);
+    const target = new Database(destination, {});
+    try {
+      target.deserialize(dump);
+      return Promise.resolve({ totalPages: 1, remainingPages: 0, idle: true });
+    } catch (e) {
+      target.close();
+      throw e;
+    }
+  }
+
+  unsafeMode() {
+    this._unsafeMode = true;
+    return this;
+  }
+
+  get defaultSafeIntegers() { return false; }
+  set defaultSafeIntegers(v) {}
+
+  get db() { return this; }
+
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    return `Database { name: '${this.name}', open: ${this.open} }`;
+  }
+}
+
+class Statement {
+  constructor(database, sql) {
+    this.database = database;
+    this._src = sql;
+    this._params = [];
+    this._rawMode = false;
+    this._pluck = false;
+    this._safeIntegers = false;
+    const trimmed = sql.trim().toLowerCase();
+    this._type = trimmed.startsWith('select') || trimmed.startsWith('pragma') || trimmed.startsWith('with') ? 'select'
+      : trimmed.startsWith('insert') ? 'insert'
+      : trimmed.startsWith('update') ? 'update'
+      : trimmed.startsWith('delete') ? 'delete'
+      : trimmed.startsWith('create') || trimmed.startsWith('drop') || trimmed.startsWith('alter') ? 'ddl'
+      : 'other';
+    this._reader = this._type === 'select' || /^\s*(select|pragma|with)\b/i.test(sql);
+    this._tableName = null;
+  }
+
+  get reader() { return this._reader; }
+  get safeIntegers() { return this._safeIntegers; }
+  set safeIntegers(v) { this._safeIntegers = !!v; }
+  get source() { return this._src; }
+
+  bind(...params) {
+    if (params.length === 1 && Array.isArray(params[0])) params = params[0];
+    this._params = params;
+    return this;
+  }
+
+  raw(enabled = true) {
+    this._rawMode = !!enabled;
+    return this;
+  }
+
+  pluck(enabled = true) {
+    this._pluck = !!enabled;
+    return this;
+  }
+
+  expand() { return this; }
+  returning() { return this; }
+
+  _call(mode, params) {
+    let p = params;
+    if (p === undefined || p === null) p = this._params;
+    if (Array.isArray(p) && p.length === 1 && typeof p[0] === 'object' && p[0] !== null && !Array.isArray(p[0]) && !(p[0] instanceof Date) && !Buffer.isBuffer(p[0])) {
+      const hasNamed = /[@:$][A-Za-z_][A-Za-z0-9_]*/.test(this.source);
+      p = hasNamed ? p[0] : p;
+    } else if (!Array.isArray(p) && (typeof p !== 'object' || p === null)) {
+      p = [p];
+    }
+    return this.database._sync(mode, [this.source, p]);
+  }
+
+  run(...params) {
+    const r = this._call('run', params.length > 0 ? params : undefined);
+    return r;
+  }
+
+  get(...params) {
+    return this._call('get', params.length > 0 ? params : undefined);
+  }
+
+  all(...params) {
+    const r = this._call('all', params.length > 0 ? params : undefined);
+    if (this._rawMode) return this._call('raw', params.length > 0 ? params : undefined);
+    if (this._pluck) {
+      const cols = r && r.length > 0 ? Object.keys(r[0]) : [];
+      return cols.length > 0 ? r.map(row => row[cols[0]]) : [];
+    }
+    return r;
+  }
+
+  iterate(...params) {
+    const rows = this.all(...params);
+    let i = 0;
+    const it = {
+      next: () => i < rows.length ? { value: rows[i++], done: false } : { value: undefined, done: true },
+      [Symbol.iterator]: () => it,
+    };
+    return it;
+  }
+
+  columns() {
+    return this._call('columns', []);
+  }
+}
+
+module.exports = Database;
+module.exports.default = Database;
+module.exports.Database = Database;
+module.exports.SqliteError = SqliteError;

package/lib/sqlite_worker.js

@@ -0,0 +1,260 @@
+// © Vexify 2026 All Rights Reserved.
+/**
+ * better-sqlite3 兼容层 — worker 线程
+ * 在 worker 中持有一个持久 Database，主线程通过 postMessage + Atomics 同步桥调用。
+ */
+
+const { workerData } = require('worker_threads');
+const Database = require('./database');
+const { executeSQL, parseSQL, applyParams } = require('./sql');
+
+const PARENT = require('worker_threads').parentPort;
+const PORT = workerData.port || PARENT;
+let db = null;
+let sab = null;
+let ctrl = null;
+const userFunctions = {};
+const userAggregates = {};
+
+function startEngine(filename, options) {
+  const opts = options || {};
+  const isMemory = filename === ':memory:' || !filename;
+  if (opts.engine === 'native') {
+    const { NativeJSQL } = require('./native_client');
+    const engine = new NativeJSQL({ mode: 'memory' });
+    db = {
+      start: async () => { await engine.start(); },
+      stop: async () => { await engine.stop(); },
+      hasTable: name => engine._tableNames.has(name),
+      createTable: (n, s) => engine.createTable(n, s),
+      dropTable: n => engine.dropTable(n),
+      insert: (n, rows) => engine.insert(n, rows),
+      find: (n, f, o) => engine.find(n, f, o),
+      updateByIds: (n, e) => engine.updateByIds(n, e),
+      removeByIds: (n, ids) => engine.removeByIds(n, ids),
+      count: (n, f) => engine.count ? engine.count(n, f) : engine.find(n, f || {}, {}).then(rs => rs.length),
+      getTableSchema: n => engine._schemas[n] || null,
+      truncate: async () => { throw new Error('truncate not supported on native engine'); },
+      flush: async () => { if (engine.flush) await engine.flush(); },
+      listTables: () => Array.from(engine._tableNames || []),
+      _schemas: engine._schemas,
+    };
+    return db;
+  }
+  // 纯 JS 引擎
+  db = new Database(isMemory ? ':memory:' : filename, opts.mode === 'hybrid' ? { mode: 'hybrid' } : {});
+  return db;
+}
+
+function toRows(result) {
+  // 把 executeSQL 的 select 结果转成 better-sqlite3 风格的对象行数组
+  if (result && result.type === 'select' && Array.isArray(result.rows)) {
+    const cols = Array.isArray(result.columns) ? result.columns : [];
+    return result.rows.map(r => {
+      const o = {};
+      for (let i = 0; i < cols.length; i++) o[cols[i]] = r[i];
+      return o;
+    });
+  }
+  if (result && result.type === 'pragma' && result.value !== undefined) {
+    return result.value;
+  }
+  return undefined;
+}
+
+let _lastInsertId = 0;
+
+async function executeStatement(sql, params) {
+  if (params && typeof params === 'object' && !Array.isArray(params)) {
+    sql = applyParams(sql, params);
+    params = null;
+  }
+  const result = await executeSQL(db, sql, params, {
+    session: {
+      get lastInsertId() { return _lastInsertId; },
+      set lastInsertId(v) { _lastInsertId = Number(v); },
+    },
+    functions: userFunctions,
+    aggregates: userAggregates,
+  });
+  if (result && result.type === 'insert' && result.insertId !== null && result.insertId !== undefined) {
+    _lastInsertId = Number(result.insertId);
+  }
+  return result;
+}
+
+function cleanResult(r) {
+  if (!r || typeof r !== 'object') return r;
+  if (Array.isArray(r)) return r.map(cleanResult);
+  if (Buffer.isBuffer(r) || r instanceof Uint8Array || r instanceof ArrayBuffer || ArrayBuffer.isView(r)) return r;
+  const out = {};
+  for (const [k, v] of Object.entries(r)) {
+    if (k === 'result' || k === 'engine') continue;
+    if (v instanceof Date) out[k] = v.toISOString();
+    else if (v === undefined) out[k] = null;
+    else if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
+      // 仅保留可 JSON 化的值（防止 Table/内部对象循环引用）
+      try { JSON.stringify(v); out[k] = v; } catch (e) { out[k] = null; }
+    } else out[k] = v;
+  }
+  return out;
+}
+
+async function handleOp(op, args) {
+  let result;
+  switch (op) {
+    case 'start': {
+      await startEngine(args[0], args[1]).start();
+      result = { ok: true };
+      break;
+    }
+    case 'close': {
+      if (db && typeof db.stop === 'function') await db.stop();
+      result = { ok: true };
+      break;
+    }
+    case 'exec': {
+      result = await executeStatement(args[0], args[1]);
+      break;
+    }
+    case 'run': {
+      const r = await executeStatement(args[0], args[1]);
+      result = {
+        changes: r ? (r.affectedRows || 0) : 0,
+        lastInsertRowid: r && r.type === 'insert' ? Number(r.insertId || 0) : _lastInsertId,
+      };
+      break;
+    }
+    case 'get': {
+      const r = await executeStatement(args[0], args[1]);
+      const rows = toRows(r);
+      result = Array.isArray(rows) ? (rows.length > 0 ? rows[0] : undefined) : rows;
+      break;
+    }
+    case 'all': {
+      const r = await executeStatement(args[0], args[1]);
+      const rows = toRows(r);
+      result = rows === undefined || rows === null ? [] : rows;
+      break;
+    }
+    case 'raw': {
+      const r = await executeStatement(args[0], args[1]);
+      let rows = r && r.type === 'select' ? (r.rows || []) : (toRows(r) || []);
+      const cols = r && Array.isArray(r.columns) ? r.columns : (rows.length > 0 ? Object.keys(rows[0]) : []);
+      if (Array.isArray(rows) && rows.length > 0 && typeof rows[0] === 'object' && !Array.isArray(rows[0])) {
+        rows = rows.map(row => cols.map(c => row[c]));
+      }
+      result = rows;
+      break;
+    }
+    case 'columns': {
+      const r = await executeStatement(args[0], args[1]);
+      const cols = r && r.type === 'select' && Array.isArray(r.columns) ? r.columns : [];
+      result = cols.map((name, i) => ({
+        name,
+        type: 'TEXT',
+        column: name,
+        table: r && r.table ? r.table : null,
+        database: null,
+      }));
+      break;
+    }
+    case 'parse': {
+      const stmt = parseSQL(args[0]);
+      result = { type: stmt.type, name: stmt.name || stmt.table || null };
+      break;
+    }
+    case 'hasTable': {
+      result = typeof db.hasTable === 'function' ? db.hasTable(args[0]) : false;
+      break;
+    }
+    case 'registerFunction': {
+      const [name, fnStr, deterministic] = args;
+      // 用函数源码在 worker 中重建（无闭包依赖的纯函数）
+      try {
+        // eslint-disable-next-line no-new-func
+        const fn = new Function('return (' + fnStr + ')')();
+        userFunctions[String(name).toUpperCase()] = fn;
+        result = { ok: true };
+      } catch (e) {
+        throw new Error('Failed to register function ' + name + ': ' + e.message);
+      }
+      break;
+    }
+    case 'clearFunctions': {
+      for (const k of Object.keys(userFunctions)) delete userFunctions[k];
+      result = { ok: true };
+      break;
+    }
+    case 'registerAggregate': {
+      const [name, specStr, deterministic] = args;
+      try {
+        // eslint-disable-next-line no-new-func
+        const spec = new Function('return (' + specStr + ')')();
+        userAggregates[String(name).toUpperCase()] = spec;
+        result = { ok: true };
+      } catch (e) {
+        throw new Error('Failed to register aggregate ' + name + ': ' + e.message);
+      }
+      break;
+    }
+    case 'serialize': {
+      const { exportAllToJSON } = require('./migrate');
+      const tables = db.listTables ? db.listTables() : Array.from(db._tableNames || []);
+      const dump = await exportAllToJSON(db, tables);
+      result = Buffer.from(JSON.stringify(dump), 'utf8');
+      break;
+    }
+    case 'deserialize': {
+      const { importFromJSON } = require('./migrate');
+      const dump = JSON.parse(Buffer.from(args[0]).toString('utf8'));
+      await importFromJSON(db, dump);
+      if (typeof db.save === 'function') db.save();
+      result = { ok: true };
+      break;
+    }
+    case 'backup': {
+      // 复制到另一个 sqlite 兼容库
+      const { exportAllToJSON } = require('./migrate');
+      const target = args[0];
+      const tables = db.listTables ? db.listTables() : Array.from(db._tableNames || []);
+      const dump = await exportAllToJSON(db, tables);
+      // 目标由主线程用另一个 Database 加载，此处返回 dump
+      result = Buffer.from(JSON.stringify(dump), 'utf8');
+      break;
+    }
+    case 'clearAggregates': {
+      for (const k of Object.keys(userAggregates)) delete userAggregates[k];
+      result = { ok: true };
+      break;
+    }
+    default:
+      throw new Error(`Unknown op: ${op}`);
+  }
+  return result;
+}
+
+PARENT.on('message', async (msg) => {
+  const { id, op, args, sab: sabArr } = msg;
+  if (sabArr) {
+    sab = sabArr;
+    ctrl = new Int32Array(sab);
+  }
+  let payload;
+  try {
+    payload = { ok: true, result: cleanResult(await handleOp(op, args)) };
+  } catch (e) {
+    payload = { ok: false, error: { message: e.message, code: e.code || 'SQLITE_ERROR' } };
+  }
+  PORT.postMessage({ id, ...payload });
+  if (ctrl) {
+    Atomics.store(ctrl, 0, id);
+    Atomics.notify(ctrl, 0);
+  }
+});
+
+PARENT.on('close', async () => {
+  try {
+    if (db && typeof db.stop === 'function') await db.stop();
+  } catch (e) { /* ignore */ }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "4.5.2",
+  "version": "5.0.1",
   "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",
@@ -24,7 +24,8 @@
     "./wasm/*": "./wasm/*",
     "./lib/*.js": "./lib/*.js",
     "./lib/*": "./lib/*.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./sqlite": "./lib/sqlite_compat.js"
   },
   "bin": {
     "jsql": "./bin/jsql"