jsql-neo 5.4.0 → 5.4.2

package/index.d.ts

@@ -106,6 +106,12 @@ declare namespace JSQLNeo {
     hasTable(name: string): Promise<boolean>;
     getTables(): Promise<string[]>;
     getTableSchema(name: string): Promise<Schema | null>;
+    /**
+     * 直接执行原生 SQL（本实例即充当 engine）。
+     * @example await db.query("SELECT * FROM users WHERE age > ?", [21])
+     * @returns 单条语句返回单个结果对象（含 columns/rows），多条返回数组。
+     */
+    query(sql: string, paramsOrOpts?: unknown[] | Record<string, unknown>, opts?: Record<string, unknown>): Promise<any>;
   }
 
   export class NativeJSQL extends JSQL {}

package/lib/mongo_server.js

@@ -148,7 +148,7 @@ function bsonReadValue(buf, pos, type, end) {
 class MongoServer {
   constructor(options = {}) {
     this.options = options;
-    this.port = options.port || 27017;
+    this.port = options.port ?? 27017;
     this.host = options.host || '127.0.0.1';
     this.dataDir = options.dataDir || null;
     this._engine = null;

package/lib/multiserver.js

@@ -38,7 +38,7 @@ function sniffProtocol(buf) {
 class MultiServer {
   constructor(options = {}) {
     this.options = options;
-    this.port = options.port || 5432;
+    this.port = options.port ?? 5432;
     this.host = options.host || '127.0.0.1';
     this.dataDir = options.dataDir || null;
     // 共享 SQL 引擎：三种 SQL 协议读写同一份数据

package/lib/mysql_server.js

@@ -898,7 +898,7 @@ class MysqlConnection {
 class MysqlServer {
   constructor(options = {}) {
     this.options = options;
-    this.port = options.port || 3306;
+    this.port = options.port ?? 3306;
     this.host = options.host || '127.0.0.1';
     this.user = options.user || null;
     this.password = options.password || null;
@@ -1182,6 +1182,18 @@ class MysqlServer {
         socket.on('close', () => this._sockets.delete(socket));
         new MysqlConnection(socket, this);
       });
+      this._server.once('error', err => {
+        if (err && err.code === 'EADDRINUSE') {
+          const friendly = new Error(
+            `MysqlServer 端口 ${this.port} 已被占用（EADDRINUSE）。` +
+            `请换一个空闲端口，或传 port: 0 让系统分配临时端口。`
+          );
+          friendly.code = 'EADDRINUSE';
+          friendly.cause = err;
+          if (cb) cb(friendly);
+          else throw friendly;
+        } else if (cb) cb(err);
+      });
       this._server.listen(this.port, this.host, cb || (() => {}));
     }).catch(err => {
       if (cb) cb(err);

package/lib/native_client.js

@@ -1,5 +1,6 @@
 const path = require('path');
 const os = require('os');
+const { executeSQL } = require('./sql');
 const native = require(path.join(__dirname, '..', 'native', 'jsql-neo-native.node'));
 const INT64_TAG = 1;
 const FLOAT_TAG = 2;
@@ -667,6 +668,17 @@ class JSQL {
     return this._schemas[name] || null;
   }
 
+  /**
+   * 直接执行原生 SQL 语句。本实例自身即充当 engine，
+   * 支持 SELECT / INSERT / UPDATE / DELETE / CREATE TABLE 等常用语句。
+   * @example
+   * const rows = await db.query("SELECT * FROM users WHERE age > ?", [21]);
+   * await db.query("UPDATE users SET age = age + 1 WHERE name = 'A'");
+   */
+  async query(sql, paramsOrOpts, opts) {
+    return executeSQL(this, sql, paramsOrOpts, opts);
+  }
+
   async stop() {
     this._flushOpsNow();
     await this._flush();

package/lib/pg_server.js

@@ -757,7 +757,7 @@ _pgErrorCode(e) {
 class PgServer {
   constructor(options = {}) {
     this.options = options;
-    this.port = options.port || 5432;
+    this.port = options.port ?? 5432;
     this.host = options.host || '127.0.0.1';
     this.auth = options.auth || null;           // { user: { password, databases: [...] } }
     this.noAuth = options.noAuth === true;

package/lib/redis_server.js

@@ -34,7 +34,7 @@ const TYPE_SIGNATURES = {
 
 class RedisServer {
   constructor(opts = {}) {
-    this.port = opts.port || 6379;
+    this.port = opts.port ?? 6379;
     this.host = opts.host || '127.0.0.1';
     this.password = opts.password || null;
     this.dataDir = opts.dataDir || null;

package/lib/sql.js

@@ -2870,6 +2870,25 @@ function applyParams(sql, values) {
 }
 
 async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
+  // 参数守卫：engine 必须是引擎对象，sql 必须是字符串。误用时报清晰错误，
+  // 而不是在后续像 `reading 'length'` 那样抛出令人费解的 TypeError。
+  if (typeof engine !== 'object' || engine === null) {
+    if (typeof engine === 'string') {
+      throw new Error(
+        `executeSQL(engine, sql, ...) 参数错误：第一个参数不能是 SQL 字符串，必须传 engine 引擎对象。\n` +
+        `正确用法：await executeSQL(db, '${engine.slice(0, 40)}…');  // db 是含 hasTable/find/getTableSchema 的对象`
+      );
+    }
+    throw new Error(
+      `executeSQL(engine, sql, ...) 参数错误：缺少第一个参数 engine。\n` +
+      `正确用法：await executeSQL(db, 'SELECT 1');  // db 需是含 hasTable/find/getTableSchema 的引擎对象`
+    );
+  }
+  if (typeof sql !== 'string' || sql.length === 0) {
+    throw new Error(
+      `executeSQL(engine, sql, ...) 参数错误：第二个参数 sql 必须是有效的 SQL 字符串`
+    );
+  }
   if (Array.isArray(paramsOrOpts)) {
     sql = applyParams(sql, paramsOrOpts);
   } else if (paramsOrOpts && typeof paramsOrOpts === 'object') {

package/lib/wasm_client.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const { executeSQL } = require('./sql');
 const wasmBindings = require(path.join(__dirname, '..', 'wasm', 'jsql_neo_wasm.js'));
 
 function safeJsonParse(str) {
@@ -697,6 +698,16 @@ class JSQL {
     return this._schemas[name] || null;
   }
 
+  /**
+   * 直接执行原生 SQL 语句。本实例自身即充当 engine，
+   * 支持 SELECT / INSERT / UPDATE / DELETE / CREATE TABLE 等常用语句。
+   * @example
+   * const rows = await db.query("SELECT * FROM users WHERE age > ?", [21]);
+   */
+  async query(sql, paramsOrOpts, opts) {
+    return executeSQL(this, sql, paramsOrOpts, opts);
+  }
+
   async stop() {
     await this._flush();
     this._runHooks('onStop', []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "5.4.0",
+  "version": "5.4.2",
   "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",

package/postinstall.js

@@ -1,38 +1,159 @@
 const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const http = require('http');
+const https = require('https');
 
+const ROOT = __dirname;
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+// Server CLI binary (bin/jsql-neo-server)
 const BIN_NAME = process.platform === 'win32' ? 'jsql-neo-server.exe' : 'jsql-neo-server';
-const BP = path.join(__dirname, 'bin', BIN_NAME);
+const BP = path.join(ROOT, 'bin', BIN_NAME);
 
-function main() {
-    if (fs.existsSync(BP)) {
-        fs.chmodSync(BP, 0o755);
-        console.log(`[jsql-neo] binary ready: ${BP}`);
+// Native N-API module (native/jsql-neo-native.node)
+const NATIVE_PATH = path.join(ROOT, 'native', 'jsql-neo-native.node');
+
+// GitHub 加速代理前缀；把原始 github 链接直接拼在后面即可
+const GHPROXY = 'https://gh-proxy.com/';
+const TAG = `v${pkg.version}`;
+
+// 从 repository 字段提取 owner/repo，例如 vexify-org/JSQL-neo
+const REPO = (pkg.repository && pkg.repository.url)
+  ? pkg.repository.url.replace(/\.git$/, '').replace(/^.*github\.com\//i, '')
+  : 'vexify-org/JSQL-neo';
+
+// 与 .github/workflows/build-native.yml 中发布的资产命名保持一致
+function nativeTargetSuffix(platform = process.platform, arch = process.arch) {
+  const p = platform === 'win32' ? 'win32' : platform === 'darwin' ? 'darwin' : 'linux';
+  const a = arch === 'x64' ? 'x64' : arch === 'arm64' ? 'arm64' : arch;
+  if (p === 'linux') return `${p}-${a}-gnu`;
+  if (p === 'darwin') return `${p}-${a}`;
+  return `${p}-${a}-msvc`;
+}
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith('https:') ? https : http;
+    const req = mod.get(url, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        download(res.headers.location, dest).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${res.statusCode} for ${url}`));
         return;
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const ws = fs.createWriteStream(dest);
+      ws.on('error', reject);
+      res.pipe(ws);
+      res.on('end', () => ws.end(() => resolve()));
+    });
+    req.on('error', reject);
+  });
+}
+
+function buildNativeFromSource() {
+  const crate = path.join(ROOT, 'nativesrc', 'jsql-neo-native');
+  if (!fs.existsSync(path.join(crate, 'Cargo.toml'))) return;
+  console.log('[jsql-neo] building native module from source...');
+  try {
+    execSync('cargo build --release', { cwd: crate, stdio: 'inherit' });
+    const rel = path.join(crate, 'target', 'release');
+    const src = process.platform === 'win32'
+      ? path.join(rel, 'jsql_neo_native.dll')
+      : process.platform === 'darwin'
+        ? path.join(rel, 'libjsql_neo_native.dylib')
+        : path.join(rel, 'libjsql_neo_native.so');
+    if (fs.existsSync(src)) {
+      fs.mkdirSync(path.dirname(NATIVE_PATH), { recursive: true });
+      fs.copyFileSync(src, NATIVE_PATH);
+      fs.chmodSync(NATIVE_PATH, 0o755);
+      console.log(`[jsql-neo] native module built: native/jsql-neo-native.node`);
     }
+  } catch (e) {
+    console.warn('[jsql-neo] native build failed:', e.message);
+  }
+}
 
-    // Build from source
-    const serverDir = path.join(__dirname, '..', 'jsql-neo-server');
-    if (fs.existsSync(path.join(serverDir, 'Cargo.toml'))) {
-        console.log('[jsql-neo] building Rust server from source...');
-        try {
-            execSync('cargo build --release', { cwd: serverDir, stdio: 'inherit' });
-            const src = path.join(serverDir, 'target', 'release', BIN_NAME);
-            if (fs.existsSync(src)) {
-                fs.mkdirSync(path.join(__dirname, 'bin'), { recursive: true });
-                fs.copyFileSync(src, BP);
-                fs.chmodSync(BP, 0o755);
-                console.log(`[jsql-neo] binary built: ${BP}`);
-                return;
-            }
-        } catch (e) {
-            console.warn('[jsql-neo] cargo build failed:', e.message);
-        }
+// 尝试加载 native 模块；能成功 require 才算「可用」，否则视为不可用
+function tryLoadNative() {
+  if (!fs.existsSync(NATIVE_PATH)) return false;
+  try {
+    require(NATIVE_PATH);
+    fs.chmodSync(NATIVE_PATH, 0o755);
+    return true;
+  } catch (e) {
+    console.warn(`[jsql-neo] existing native module cannot be loaded (${e.code || e.message}), will re-acquire.`);
+    try { fs.unlinkSync(NATIVE_PATH); } catch (_) { /* ignore */ }
+    return false;
+  }
+}
+
+async function downloadAndVerify() {
+  const asset = `jsql-neo-native.${nativeTargetSuffix()}.node`;
+  const url = `${GHPROXY}https://github.com/${REPO}/releases/download/${TAG}/${asset}`;
+  console.log(`[jsql-neo] downloading native module: ${url}`);
+  try {
+    await download(url, NATIVE_PATH);
+    if (!tryLoadNative()) {
+      console.warn('[jsql-neo] downloaded module also invalid, removed.');
+      return false;
     }
+    console.log('[jsql-neo] native module downloaded: native/jsql-neo-native.node');
+    return true;
+  } catch (e) {
+    console.warn('[jsql-neo] download failed, falling back to source build:', e.message);
+    return false;
+  }
+}
+
+async function ensureNativeNode() {
+  // 已存在且能加载 → 直接用；否则删掉并从 gh-proxy.com 下载，找不到才回退源码编译
+  if (tryLoadNative()) {
+    console.log('[jsql-neo] native module ready: native/jsql-neo-native.node');
+    return;
+  }
+  if (await downloadAndVerify()) return;
+  buildNativeFromSource();
+}
+
+function ensureServerBinary() {
+  if (fs.existsSync(BP)) {
+    fs.chmodSync(BP, 0o755);
+    console.log(`[jsql-neo] binary ready: ${BP}`);
+    return;
+  }
+
+  // Build from source
+  const serverDir = path.join(ROOT, '..', 'jsql-neo-server');
+  if (fs.existsSync(path.join(serverDir, 'Cargo.toml'))) {
+    console.log('[jsql-neo] building Rust server from source...');
+    try {
+      execSync('cargo build --release', { cwd: serverDir, stdio: 'inherit' });
+      const src = path.join(serverDir, 'target', 'release', BIN_NAME);
+      if (fs.existsSync(src)) {
+        fs.mkdirSync(path.join(ROOT, 'bin'), { recursive: true });
+        fs.copyFileSync(src, BP);
+        fs.chmodSync(BP, 0o755);
+        console.log(`[jsql-neo] binary built: ${BP}`);
+        return;
+      }
+    } catch (e) {
+      console.warn('[jsql-neo] cargo build failed:', e.message);
+    }
+  }
+
+  console.warn(`[jsql-neo] server binary not found at ${BP}`);
+  console.warn('[jsql-neo] install Rust from https://rustup.rs and run: npm run build');
+}
 
-    console.warn(`[jsql-neo] binary not found at ${BP}`);
-    console.warn('[jsql-neo] install Rust from https://rustup.rs and run: npm run build');
+async function main() {
+  await ensureNativeNode();
+  ensureServerBinary();
 }
 
-main();
+main();