jsql-neo 5.4.2 → 6.0.0-beta2

package/lib/database.js

@@ -11,6 +11,10 @@ const crypto = require('crypto');
 const Table = require('./table');
 const { createError } = require('./errors');
 const JSQLFormat = require('./jsql_format');
+const {
+  createHookRegistry, applyPlugin, buildPluginContext, registerHook,
+  runHooks, getPluginApis
+} = require('./plugin');
 
 /**
  * 解析字段简写类型字符串，如 'integer primary key'、'string unique'、
@@ -91,17 +95,7 @@ class Database {
         this._versions = {};       // tableName -> [{ rows, timestamp }]
         this._maxVersions = options.maxVersions || 50;
         this._plugins = [];
-        this._hooks = {
-            beforeInsert: [], afterInsert: [],
-            beforeUpdate: [], afterUpdate: [],
-            beforeDelete: [], afterDelete: [],
-            beforeFind: [], afterFind: [],
-            beforeCreateTable: [], afterCreateTable: [],
-            beforeDropTable: [], afterDropTable: [],
-            beforeFlush: [], afterFlush: [],
-            beforeCount: [], afterCount: [],
-            onStart: [], onStop: []
-        };
+        this._hooks = createHookRegistry();
         this._eventListeners = [];
         this._tableNames = new Set(Object.keys(this._tables));
         this._migrations = [];
@@ -1082,53 +1076,18 @@ class Database {
 
     /**
      * 注册插件
-     * @param {object|function} plugin - { name, install(db, ctx), hooks, onEvent } 或函数 (作为 install)
+     * @param {object|function} plugin - { name, version, install(db, ctx), hooks, api, onEvent } 或函数 (作为 install)
      */
     use(plugin) {
-        if (typeof plugin === 'function') {
-            plugin = { install: plugin };
-        }
-        if (plugin.hooks) {
-            for (const [event, fn] of Object.entries(plugin.hooks)) {
-                if (this._hooks[event]) {
-                    this._hooks[event].push(fn);
-                }
-            }
-        }
-        if (typeof plugin.install === 'function') {
-            plugin.install(this, this._buildCtx(plugin));
-        }
-        if (typeof plugin.onEvent === 'function') {
-            this._eventListeners.push(plugin.onEvent);
-        }
-        this._plugins.push(plugin);
-        return this;
+        return applyPlugin(this, plugin);
     }
 
     _buildCtx(plugin) {
-        const self = this;
-        return {
-            name: plugin.name || 'anonymous',
-            engine: this,
-            plugin,
-            on(hook, fn) { return self.on(hook, fn); },
-            onEvent(fn) { return self.onEvent(fn); },
-            emit(eventName, data) { self._emit(eventName, data); },
-            tables() { return Array.from(self._tableNames); },
-            hasTable(name) { return self._tableNames.has(name); },
-            getTableSchema(name) {
-                const t = self._tables[name];
-                return t ? t._schema : null;
-            },
-            table(name) { return self._tables[name] || null; }
-        };
+        return buildPluginContext(this, plugin);
     }
 
     on(event, fn) {
-        if (this._hooks[event]) {
-            this._hooks[event].push(fn);
-        }
-        return this;
+        return registerHook(this, event, fn);
     }
 
     onEvent(fn) {
@@ -1136,6 +1095,22 @@ class Database {
         return this;
     }
 
+    /** 广播事件（插件上下文 / 外部均可调用） */
+    emit(eventName, data) {
+        this._emit(eventName, data);
+        return this;
+    }
+
+    /** 主动触发一个钩子（含插件自定义钩子） */
+    runHook(hookName, ...args) {
+        return this._runHooks(hookName, args);
+    }
+
+    /** 取插件对外暴露的 API（由 plugin.api 声明） */
+    plugin(name) {
+        return getPluginApis(this).get(name) || null;
+    }
+
     _emit(eventName, data) {
         for (const fn of this._eventListeners) {
             try { fn(eventName, data); } catch (e) { /* ignore */ }
@@ -1143,16 +1118,7 @@ class Database {
     }
 
     _runHooks(hookName, args) {
-        const hooks = this._hooks[hookName];
-        if (!hooks || hooks.length === 0) return true;
-        for (const fn of hooks) {
-            const r = fn(...args);
-            if (r === false) return false;
-            if (r !== undefined && args.length > 0) {
-                args[0] = r;
-            }
-        }
-        return true;
+        return runHooks(this, hookName, args);
     }
 
     // ============================================================

package/lib/mongo_server.js

@@ -322,7 +322,7 @@ class MongoServer {
           localTime: new Date(), logicalSessionTimeoutMinutes: 30, connectionId: 1,
         };
       case 'ping': return { ok: 1 };
-      case 'buildInfo': return { ok: 1, version: '5.4.0-jsql-neo', gitVersion: 'jsql-neo', versionArray: [5, 4, 0, 0] };
+      case 'buildInfo': return { ok: 1, version: '5.6.0-jsql-neo', gitVersion: 'jsql-neo', versionArray: [5, 6, 0, 0] };
       case 'getParameter': return { ok: 1 };
       case 'endSessions': return { ok: 1 };
       case 'listDatabases':

package/lib/native_client.js

@@ -1,6 +1,10 @@
 const path = require('path');
 const os = require('os');
 const { executeSQL } = require('./sql');
+const {
+  createHookRegistry, applyPlugin, buildPluginContext, registerHook,
+  runHooks, getPluginApis
+} = require('./plugin');
 const native = require(path.join(__dirname, '..', 'native', 'jsql-neo-native.node'));
 const INT64_TAG = 1;
 const FLOAT_TAG = 2;
@@ -229,17 +233,9 @@ class JSQL {
     this._evictTimer = null;
 
     this._plugins = [];
-    this._hooks = {
-      beforeInsert: [], afterInsert: [],
-      beforeUpdate: [], afterUpdate: [],
-      beforeDelete: [], afterDelete: [],
-      beforeFind: [], afterFind: [],
-      beforeCreateTable: [], afterCreateTable: [],
-      beforeDropTable: [], afterDropTable: [],
-      beforeFlush: [], afterFlush: [],
-      beforeCount: [], afterCount: [],
-      onStart: [], onStop: []
-    };
+    this._hooks = createHookRegistry();
+    // native 引擎：钩子内再次调用引擎方法会触发 N-API 重入崩溃，需显式防护
+    this._forbidReentry = true;
     this._eventListeners = [];
     if (this._autoPlugins) {
       const { ModuleManager } = require('./mod');
@@ -247,47 +243,16 @@ class JSQL {
     }
   }
 
-  use(plugin) {
-    if (typeof plugin === 'function') {
-      plugin = { install: plugin };
-    }
-    if (plugin.hooks) {
-      for (const [event, fn] of Object.entries(plugin.hooks)) {
-        if (this._hooks[event]) {
-          this._hooks[event].push(fn);
-        }
-      }
-    }
-    if (typeof plugin.install === 'function') {
-      plugin.install(this, this._buildCtx(plugin));
-    }
-    if (typeof plugin.onEvent === 'function') {
-      this._eventListeners.push(plugin.onEvent);
-    }
-    this._plugins.push(plugin);
-    return this;
+  use(plugin, opts) {
+    return applyPlugin(this, plugin, opts);
   }
 
   _buildCtx(plugin) {
-    const self = this;
-    return {
-      name: plugin.name || 'anonymous',
-      engine: this,
-      plugin,
-      on(hook, fn) { return self.on(hook, fn); },
-      onEvent(fn) { return self.onEvent(fn); },
-      emit(eventName, data) { self._emit(eventName, data); },
-      tables() { return Array.from(self._tableNames); },
-      hasTable(name) { return self._tableNames.has(name); },
-      getTableSchema(name) { return self._schemas[name] || null; }
-    };
+    return buildPluginContext(this, plugin);
   }
 
   on(event, fn) {
-    if (this._hooks[event]) {
-      this._hooks[event].push(fn);
-    }
-    return this;
+    return registerHook(this, event, fn);
   }
 
   onEvent(fn) {
@@ -295,6 +260,22 @@ class JSQL {
     return this;
   }
 
+  /** 广播事件（插件上下文 / 外部均可调用） */
+  emit(eventName, data) {
+    this._emit(eventName, data);
+    return this;
+  }
+
+  /** 主动触发一个钩子（含插件自定义钩子） */
+  runHook(hookName, ...args) {
+    return this._runHooks(hookName, args);
+  }
+
+  /** 取插件对外暴露的 API（由 plugin.api 声明） */
+  plugin(name) {
+    return getPluginApis(this).get(name) || null;
+  }
+
   _emit(eventName, data) {
     for (const fn of this._eventListeners) {
       try { fn(eventName, data); } catch (e) { /* ignore */ }
@@ -302,25 +283,7 @@ class JSQL {
   }
 
   _runHooks(hookName, args) {
-    const hooks = this._hooks[hookName];
-    if (!hooks || hooks.length === 0) return true;
-    if (this._inHook) {
-      // 防止插件 hook 内重入 native 调用导致 N-API 崩溃（段错误）
-      throw new Error('ER_PLUGIN_REENTRY: plugin hook "' + hookName + '" re-entered native call; plugin must not call engine methods inside its own hook');
-    }
-    this._inHook = true;
-    try {
-      for (const fn of hooks) {
-        const r = fn(...args);
-        if (r === false) return false;
-        if (r !== undefined && args.length > 0) {
-          args[0] = r;
-        }
-      }
-      return true;
-    } finally {
-      this._inHook = false;
-    }
+    return runHooks(this, hookName, args);
   }
 
   async start() {
@@ -551,6 +514,17 @@ class JSQL {
     return r;
   }
 
+  async addColumn(table, name, def) {
+    await this._flush();
+    const mapped = mapNativeSchema({ [name]: def })[name];
+    const r = safeParse(native.jsqlAddColumn(table, name, JSON.stringify(mapped)));
+    if (r && r.ok === false) throw new Error(r.error || 'add column failed');
+    if (!this._schemas[table]) this._schemas[table] = {};
+    this._schemas[table][name] = mapped;
+    this._emit('addColumn', { table, name, def: mapped });
+    return r;
+  }
+
   async dropTable(name) {
     await this._flush();
     if (!this._runHooks('beforeDropTable', [name])) return null;
@@ -676,7 +650,10 @@ class JSQL {
    * await db.query("UPDATE users SET age = age + 1 WHERE name = 'A'");
    */
   async query(sql, paramsOrOpts, opts) {
-    return executeSQL(this, sql, paramsOrOpts, opts);
+    if (!this._runHooks('beforeQuery', [sql, paramsOrOpts, opts])) return null;
+    const result = await executeSQL(this, sql, paramsOrOpts, opts);
+    this._runHooks('afterQuery', [sql, paramsOrOpts, opts, result]);
+    return result;
   }
 
   async stop() {

package/lib/plugin.js

@@ -1,7 +1,59 @@
+/**
+ * JSQL-NEO 可编程插件系统
+ *
+ * 统一的插件运行时，被 native / wasm / js 三个引擎共用，开放四类扩展点：
+ *   1. 生命周期钩子（HOOKS）——在引擎操作前后触发，返回 false 可中止操作；
+ *   2. 事件监听（onEvent / emit）——操作完成后广播；
+ *   3. 上下文接口（ctx）——插件拿到引擎能力、schema、日志、配置与私有存储；
+ *   4. 插件 API（api / db.plugin(name)）——插件对外暴露可编程接口。
+ *
+ * 约定：钩子内不要调用会再次触发钩子的引擎方法（native 引擎会抛
+ * ER_PLUGIN_REENTRY 保护 N-API 不崩溃）；需要修改数据时直接原地修改传入的
+ * 数组 / 对象，返回 undefined；返回 false 表示中止本次操作。
+ */
+
+/** 内置生命周期钩子名（自定义钩子名也会被自动登记，无需在此声明） */
+const HOOKS = Object.freeze([
+  'beforeInsert', 'afterInsert',
+  'beforeUpdate', 'afterUpdate',
+  'beforeDelete', 'afterDelete',
+  'beforeFind', 'afterFind',
+  'beforeCreateTable', 'afterCreateTable',
+  'beforeDropTable', 'afterDropTable',
+  'beforeFlush', 'afterFlush',
+  'beforeCount', 'afterCount',
+  'beforeQuery', 'afterQuery',
+  'onStart', 'onStop'
+]);
+
+/** 创建一个预置了全部内置钩子的空注册表 */
+function createHookRegistry() {
+  const reg = {};
+  for (const h of HOOKS) reg[h] = [];
+  return reg;
+}
+
 class Plugin {
+  /**
+   * @param {string} name 插件名（用于 db.plugin(name) 取 API、私有存储隔离）
+   * @param {object} [opts]
+   * @param {string} [opts.version]
+   * @param {object} [opts.hooks] { hookName: fn | fn[] }
+   * @param {string[]} [opts.depends] 依赖的其它插件名
+   * @param {number} [opts.priority]
+   * @param {object} [opts.config] 传给插件的配置
+   * @param {object} [opts.api] 插件对外暴露的接口对象
+   * @param {function} [opts.onEvent]
+   * @param {function} [opts.install] install(engine, ctx)
+   */
   constructor(name, opts = {}) {
     this.name = name;
+    this.version = opts.version || null;
     this.hooks = opts.hooks || {};
+    this.depends = opts.depends || [];
+    this.priority = opts.priority || 0;
+    this.config = opts.config || {};
+    this.api = opts.api || null;
     this._onEvent = opts.onEvent || null;
     this._install = opts.install || null;
   }
@@ -11,8 +63,11 @@ class Plugin {
     return this;
   }
 
+  /** 注册钩子；同名钩子可多次注册，按注册顺序执行 */
   on(hook, fn) {
-    this.hooks[hook] = fn;
+    if (!this.hooks[hook]) this.hooks[hook] = [];
+    if (!Array.isArray(this.hooks[hook])) this.hooks[hook] = [this.hooks[hook]];
+    this.hooks[hook].push(fn);
     return this;
   }
 
@@ -21,15 +76,184 @@ class Plugin {
     return this;
   }
 
+  /** 声明插件对外暴露的接口 */
+  expose(api) {
+    this.api = api;
+    return this;
+  }
+
   build() {
     const inst = {
       name: this.name,
-      hooks: this.hooks
+      version: this.version,
+      hooks: this.hooks,
+      depends: this.depends,
+      priority: this.priority,
+      config: this.config
     };
+    if (this.api) inst.api = this.api;
     if (this._onEvent) inst.onEvent = this._onEvent;
     if (this._install) inst.install = this._install;
     return inst;
   }
 }
 
-module.exports = { Plugin };
+/** 以函数式风格定义插件：definePlugin('name', { hooks, api, install }) */
+function definePlugin(name, def = {}) {
+  return new Plugin(name, def).build();
+}
+
+/** 登记单个钩子；未知钩子名会自动创建，便于插件自定义扩展点 */
+function registerHook(engine, hook, fn) {
+  if (typeof fn !== 'function') return engine;
+  if (!engine._hooks) engine._hooks = createHookRegistry();
+  if (!engine._hooks[hook]) engine._hooks[hook] = [];
+  engine._hooks[hook].push(fn);
+  return engine;
+}
+
+/** 把一个插件声明的所有钩子登记到引擎上 */
+function registerHooks(engine, plugin) {
+  if (!plugin || !plugin.hooks) return engine;
+  for (const [hook, val] of Object.entries(plugin.hooks)) {
+    const fns = Array.isArray(val) ? val : [val];
+    for (const fn of fns) registerHook(engine, hook, fn);
+  }
+  return engine;
+}
+
+/** 引擎 → 插件 API 注册表 */
+function getPluginApis(engine) {
+  if (!engine._pluginApis) engine._pluginApis = new Map();
+  return engine._pluginApis;
+}
+
+/** 引擎 → 插件私有存储（按插件名隔离） */
+function getPluginStore(engine, name) {
+  if (!engine._pluginStores) engine._pluginStores = new Map();
+  if (!engine._pluginStores.has(name)) engine._pluginStores.set(name, new Map());
+  return engine._pluginStores.get(name);
+}
+
+/**
+ * 构建插件上下文。优先走引擎自身的公开方法，缺失时回退到约定的内部字段，
+ * 使三个引擎共享同一套插件 API。
+ */
+function buildPluginContext(engine, plugin) {
+  const name = plugin.name || 'anonymous';
+  const version = plugin.version || null;
+  const store = getPluginStore(engine, name);
+  const ctx = {
+    name,
+    version,
+    engine,
+    plugin,
+    config: plugin.config || {},
+    store,
+    /** 注册生命周期钩子 / 自定义钩子 */
+    on(hook, fn) { return engine.on(hook, fn); },
+    /** 注册事件监听 */
+    onEvent(fn) { return engine.onEvent(fn); },
+    /** 广播事件 */
+    emit(eventName, data) { return engine.emit(eventName, data); },
+    /** 主动触发一个钩子（含自定义钩子） */
+    hook(hookName, ...args) { return engine.runHook(hookName, ...args); },
+    /** 组合：加载另一个插件 */
+    use(other) { return engine.use(other); },
+    /** 表清单（同步） */
+    tables() {
+      if (engine._tableNames) return Array.from(engine._tableNames);
+      if (typeof engine.getTables === 'function') return engine.getTables();
+      return [];
+    },
+    /** 表是否存在 */
+    hasTable(t) {
+      if (typeof engine.hasTable === 'function') return engine.hasTable(t);
+      return !!(engine._tableNames && engine._tableNames.has(t));
+    },
+    /** 表 schema（同步，可能为 null） */
+    getTableSchema(t) {
+      if (engine._schemas && engine._schemas[t] !== undefined) return engine._schemas[t];
+      if (typeof engine.getTableSchema === 'function') return engine.getTableSchema(t);
+      return null;
+    },
+    /** 带插件名前缀的日志 */
+    log(...args) { console.log(`[jsql:${name}]`, ...args); },
+    /** 运行期声明插件 API */
+    expose(api) {
+      plugin.api = api;
+      getPluginApis(engine).set(name, api);
+      return api;
+    }
+  };
+  return ctx;
+}
+
+/**
+ * 把一个插件应用到引擎：登记钩子、调用 install、挂载事件与 API。
+ * 引擎的 `use()` 只需 `return applyPlugin(this, plugin)`。
+ * @returns {object} engine（便于链式调用）
+ */
+function applyPlugin(engine, plugin, opts) {
+  // 字符串 → 内置插件名（懒加载，避免与 plugins/index 形成加载期循环依赖）
+  if (typeof plugin === 'string') {
+    plugin = require('./plugins').resolve(plugin, opts);
+  }
+  if (typeof plugin === 'function') plugin = { install: plugin };
+  if (!plugin || typeof plugin !== 'object') {
+    throw new Error('use: plugin must be an object, a function, or a builtin plugin name');
+  }
+  if (!engine._plugins) engine._plugins = [];
+  if (!engine._eventListeners) engine._eventListeners = [];
+
+  registerHooks(engine, plugin);
+
+  const ctx = buildPluginContext(engine, plugin);
+  if (typeof plugin.install === 'function') plugin.install(engine, ctx);
+  if (typeof plugin.onEvent === 'function') engine._eventListeners.push(plugin.onEvent);
+
+  engine._plugins.push(plugin);
+  if (plugin.name && plugin.api) getPluginApis(engine).set(plugin.name, plugin.api);
+  return engine;
+}
+
+/**
+ * 运行某个钩子链。
+ * - 任一钩子返回 false → 中止（返回 false），引擎据此跳过本次操作；
+ * - native 引擎置 `_forbidReentry`，钩子内再次触发引擎操作会抛 ER_PLUGIN_REENTRY。
+ */
+function runHooks(engine, hookName, args) {
+  const hooks = engine._hooks && engine._hooks[hookName];
+  if (!hooks || hooks.length === 0) return true;
+
+  const guard = !!engine._forbidReentry;
+  if (guard) {
+    if (engine._inHook) {
+      throw new Error('ER_PLUGIN_REENTRY: plugin hook "' + hookName +
+        '" re-entered native call; plugin must not call engine methods inside its own hook');
+    }
+    engine._inHook = true;
+  }
+  try {
+    for (const fn of hooks) {
+      if (fn(...args) === false) return false;
+    }
+    return true;
+  } finally {
+    if (guard) engine._inHook = false;
+  }
+}
+
+module.exports = {
+  HOOKS,
+  Plugin,
+  definePlugin,
+  createHookRegistry,
+  registerHook,
+  registerHooks,
+  buildPluginContext,
+  applyPlugin,
+  runHooks,
+  getPluginApis,
+  getPluginStore
+};

package/lib/plugins/audit.js

@@ -0,0 +1,37 @@
+/**
+ * audit —— 记录数据变更审计日志（内存环形缓冲）。
+ *
+ * @example
+ * db.use(require('jsql-neo/lib/plugins').audit({ limit: 500 }));
+ * db.plugin('audit').entries();   // [{ at, op, table, count }]
+ */
+const { definePlugin } = require('../plugin');
+
+function createAudit(opts = {}) {
+  const limit = opts.limit || 1000;
+  const entries = [];
+
+  const push = e => {
+    entries.push({ at: Date.now(), ...e });
+    if (entries.length > limit) entries.splice(0, entries.length - limit);
+  };
+  const rowCount = rows => (Array.isArray(rows) ? rows.length : 1);
+
+  return definePlugin('audit', {
+    config: { limit },
+    api: {
+      entries: () => entries.map(e => ({ ...e })),
+      size: () => entries.length,
+      clear: () => { entries.length = 0; }
+    },
+    hooks: {
+      afterInsert(table, rows) { push({ op: 'insert', table, count: rowCount(rows) }); },
+      afterUpdate(table) { push({ op: 'update', table }); },
+      afterDelete(table) { push({ op: 'delete', table }); },
+      afterCreateTable(name) { push({ op: 'createTable', table: name }); },
+      afterDropTable(name) { push({ op: 'dropTable', table: name }); }
+    }
+  });
+}
+
+module.exports = { createAudit, audit: createAudit };

package/lib/plugins/index.js

@@ -0,0 +1,72 @@
+/**
+ * JSQL-NEO 内置插件集
+ *
+ * 每个插件都是「工厂函数」，调用后返回可交给 `db.use()` 的插件对象。
+ * 也可以直接用名字加载：`db.use('logger')` / `db.use('timestamps', { ... })`。
+ *
+ * @example
+ * const plugins = require('jsql-neo/lib/plugins');
+ * db.use(plugins.timestamps());
+ * db.use(plugins.logger({ logger: myLog }));
+ * db.use(plugins.metrics());
+ * const audit = db.plugin('audit');
+ */
+const { createTimestamps } = require('./timestamps');
+const { createLogger } = require('./logger');
+const { createMetrics } = require('./metrics');
+const { createAudit } = require('./audit');
+const { createValidation } = require('./validation');
+
+/** 名称 → 插件工厂 */
+const builtins = {
+  timestamps: createTimestamps,
+  logger: createLogger,
+  metrics: createMetrics,
+  audit: createAudit,
+  validation: createValidation
+};
+
+/** 内置插件名清单 */
+function list() {
+  return Object.keys(builtins);
+}
+
+/**
+ * 按名字构造内置插件。
+ * @param {string} name
+ * @param {object} [opts]
+ * @returns {object} 插件对象，可直接 db.use()
+ */
+function create(name, opts = {}) {
+  const factory = builtins[name];
+  if (!factory) {
+    throw new Error(`Unknown builtin plugin: ${name}. Available: ${list().join(', ')}`);
+  }
+  return factory(opts);
+}
+
+/**
+ * 名称或插件对象 → 插件对象。供引擎的 `use()` 解析字符串用。
+ * 插件对象原样返回；字符串走内置注册表。
+ */
+function resolve(nameOrPlugin, opts) {
+  if (typeof nameOrPlugin === 'string') return create(nameOrPlugin, opts);
+  return nameOrPlugin;
+}
+
+module.exports = {
+  createTimestamps,
+  createLogger,
+  createMetrics,
+  createAudit,
+  createValidation,
+  timestamps: createTimestamps,
+  logger: createLogger,
+  metrics: createMetrics,
+  audit: createAudit,
+  validation: createValidation,
+  builtins,
+  list,
+  create,
+  resolve
+};