jsql-neo 5.4.1 → 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.1",
+  "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",