schema-dsl 2.3.0

package/lib/core/PluginManager.js

@@ -0,0 +1,448 @@
+/**
+ * 插件管理器
+ * 
+ * @description SchemaIO 插件系统的核心类，负责插件的注册、加载和生命周期管理
+ * @module lib/core/PluginManager
+ * @version 2.2.0
+ */
+
+const EventEmitter = require('events');
+
+/**
+ * 插件生命周期钩子
+ * @typedef {Object} PluginHooks
+ * @property {Function} onBeforeRegister - 注册前钩子
+ * @property {Function} onAfterRegister - 注册后钩子
+ * @property {Function} onBeforeValidate - 验证前钩子
+ * @property {Function} onAfterValidate - 验证后钩子
+ * @property {Function} onError - 错误处理钩子
+ */
+
+/**
+ * 插件配置
+ * @typedef {Object} PluginConfig
+ * @property {string} name - 插件名称（必填）
+ * @property {string} version - 插件版本
+ * @property {string} description - 插件描述
+ * @property {Function} install - 插件安装函数（必填）
+ * @property {Function} [uninstall] - 插件卸载函数
+ * @property {PluginHooks} [hooks] - 生命周期钩子
+ * @property {Object} [options] - 插件选项
+ */
+
+class PluginManager extends EventEmitter {
+    constructor() {
+        super();
+
+        /**
+         * 已注册的插件
+         * @type {Map<string, PluginConfig>}
+         */
+        this.plugins = new Map();
+
+        /**
+         * 钩子函数集合
+         * @type {Map<string, Array<Function>>}
+         */
+        this.hooks = new Map();
+
+        /**
+         * 插件上下文
+         * @type {Object}
+         */
+        this.context = {
+            plugins: this.plugins,
+            hooks: this.hooks
+        };
+
+        // 初始化钩子
+        this._initializeHooks();
+    }
+
+    /**
+     * 初始化默认钩子
+     * @private
+     */
+    _initializeHooks() {
+        const defaultHooks = [
+            'onBeforeRegister',
+            'onAfterRegister',
+            'onBeforeValidate',
+            'onAfterValidate',
+            'onError',
+            'onBeforeExport',
+            'onAfterExport',
+            'onBeforeCompile',
+            'onAfterCompile'
+        ];
+
+        defaultHooks.forEach(hookName => {
+            this.hooks.set(hookName, []);
+        });
+    }
+
+    /**
+     * 注册插件
+     * 
+     * @param {PluginConfig} plugin - 插件配置
+     * @throws {Error} 插件配置无效时抛出错误
+     * 
+     * @example
+     * ```javascript
+     * const pluginManager = new PluginManager();
+     * 
+     * pluginManager.register({
+     *   name: 'custom-validator',
+     *   version: '1.0.0',
+     *   install(coreInstance, options) {
+     *     // 安装逻辑
+     *   }
+     * });
+     * ```
+     */
+    register(plugin) {
+        // 验证插件配置
+        this._validatePlugin(plugin);
+
+        const { name } = plugin;
+
+        // 检查插件是否已注册
+        if (this.plugins.has(name)) {
+            throw new Error(`Plugin "${name}" is already registered`);
+        }
+
+        // 触发注册前钩子
+        this._runHook('onBeforeRegister', plugin);
+
+        // 注册插件
+        this.plugins.set(name, plugin);
+
+        // 注册插件的钩子
+        if (plugin.hooks) {
+            Object.keys(plugin.hooks).forEach(hookName => {
+                this.hook(hookName, plugin.hooks[hookName]);
+            });
+        }
+
+        // 触发注册后钩子
+        this._runHook('onAfterRegister', plugin);
+
+        // 触发事件
+        this.emit('plugin:registered', plugin);
+
+        return this;
+    }
+
+    /**
+     * 验证插件配置
+     * @private
+     * @param {PluginConfig} plugin - 插件配置
+     * @throws {Error} 配置无效时抛出错误
+     */
+    _validatePlugin(plugin) {
+        if (!plugin || typeof plugin !== 'object') {
+            throw new Error('Plugin must be an object');
+        }
+
+        if (!plugin.name || typeof plugin.name !== 'string') {
+            throw new Error('Plugin must have a valid name');
+        }
+
+        if (!plugin.install || typeof plugin.install !== 'function') {
+            throw new Error('Plugin must have an install function');
+        }
+    }
+
+    /**
+     * 安装插件
+     * 
+     * @param {Object} coreInstance - SchemaIO 实例
+     * @param {string} [pluginName] - 插件名称（可选，如果不指定则安装所有插件）
+     * @param {Object} [options] - 安装选项
+     * 
+     * @example
+     * ```javascript
+     * // 安装单个插件
+     * pluginManager.install(coreInstance, 'custom-validator', { strict: true });
+     * 
+     * // 安装所有插件
+     * pluginManager.install(schema-dsl);
+     * ```
+     */
+    install(coreInstance, pluginName, options = {}) {
+        if (!pluginName) {
+            // 安装所有插件
+            this.plugins.forEach((plugin, name) => {
+                this._installPlugin(coreInstance, plugin, options);
+            });
+            return this;
+        }
+
+        const plugin = this.plugins.get(pluginName);
+        if (!plugin) {
+            throw new Error(`Plugin "${pluginName}" not found`);
+        }
+
+        this._installPlugin(coreInstance, plugin, options);
+        return this;
+    }
+
+    /**
+     * 安装单个插件
+     * @private
+     * @param {Object} coreInstance - SchemaIO 实例
+     * @param {PluginConfig} plugin - 插件配置
+     * @param {Object} options - 安装选项
+     */
+    _installPlugin(coreInstance, plugin, options = {}) {
+        try {
+            // 合并选项
+            const pluginOptions = { ...plugin.options, ...options };
+
+            // 执行安装函数
+            plugin.install(coreInstance, pluginOptions, this.context);
+
+            // 触发事件
+            this.emit('plugin:installed', plugin);
+        } catch (error) {
+            this.emit('plugin:error', { plugin, error });
+            throw new Error(`Failed to install plugin "${plugin.name}": ${error.message}`);
+        }
+    }
+
+    /**
+     * 卸载插件
+     * 
+     * @param {string} pluginName - 插件名称
+     * @param {Object} coreInstance - SchemaIO 实例
+     * 
+     * @example
+     * ```javascript
+     * pluginManager.uninstall('custom-validator', coreInstance);
+     * ```
+     */
+    uninstall(pluginName, coreInstance) {
+        const plugin = this.plugins.get(pluginName);
+        if (!plugin) {
+            throw new Error(`Plugin "${pluginName}" not found`);
+        }
+
+        // 执行卸载函数（如果有）
+        if (plugin.uninstall && typeof plugin.uninstall === 'function') {
+            try {
+                plugin.uninstall(coreInstance, this.context);
+            } catch (error) {
+                this.emit('plugin:error', { plugin, error });
+                throw new Error(`Failed to uninstall plugin "${pluginName}": ${error.message}`);
+            }
+        }
+
+        // 移除插件的钩子
+        if (plugin.hooks) {
+            Object.keys(plugin.hooks).forEach(hookName => {
+                this.unhook(hookName, plugin.hooks[hookName]);
+            });
+        }
+
+        // 从注册表中移除
+        this.plugins.delete(pluginName);
+
+        // 触发事件
+        this.emit('plugin:uninstalled', plugin);
+
+        return this;
+    }
+
+    /**
+     * 注册钩子函数
+     * 
+     * @param {string} hookName - 钩子名称
+     * @param {Function} handler - 钩子处理函数
+     * 
+     * @example
+     * ```javascript
+     * pluginManager.hook('onBeforeValidate', (schema, data) => {
+     *   console.log('Before validation:', schema, data);
+     * });
+     * ```
+     */
+    hook(hookName, handler) {
+        if (typeof handler !== 'function') {
+            throw new Error('Hook handler must be a function');
+        }
+
+        if (!this.hooks.has(hookName)) {
+            this.hooks.set(hookName, []);
+        }
+
+        this.hooks.get(hookName).push(handler);
+        return this;
+    }
+
+    /**
+     * 移除钩子函数
+     * 
+     * @param {string} hookName - 钩子名称
+     * @param {Function} handler - 钩子处理函数
+     */
+    unhook(hookName, handler) {
+        if (!this.hooks.has(hookName)) {
+            return this;
+        }
+
+        const handlers = this.hooks.get(hookName);
+        const index = handlers.indexOf(handler);
+        if (index !== -1) {
+            handlers.splice(index, 1);
+        }
+
+        return this;
+    }
+
+    /**
+     * 运行钩子
+     * 
+     * @param {string} hookName - 钩子名称
+     * @param {...any} args - 钩子参数
+     * @returns {Promise<any[]>} 钩子返回值数组
+     * 
+     * @example
+     * ```javascript
+     * const results = await pluginManager.runHook('onBeforeValidate', schema, data);
+     * ```
+     */
+    async runHook(hookName, ...args) {
+        if (!this.hooks.has(hookName)) {
+            return [];
+        }
+
+        const handlers = this.hooks.get(hookName);
+        const results = [];
+
+        for (const handler of handlers) {
+            try {
+                const result = await handler(...args);
+                results.push(result);
+            } catch (error) {
+                this.emit('hook:error', { hookName, handler, error });
+                // 运行错误钩子
+                this._runHook('onError', error, { hookName, handler });
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * 同步运行钩子（不等待异步）
+     * @private
+     * @param {string} hookName - 钩子名称
+     * @param {...any} args - 钩子参数
+     */
+    _runHook(hookName, ...args) {
+        if (!this.hooks.has(hookName)) {
+            return;
+        }
+
+        const handlers = this.hooks.get(hookName);
+        handlers.forEach(handler => {
+            try {
+                handler(...args);
+            } catch (error) {
+                this.emit('hook:error', { hookName, handler, error });
+            }
+        });
+    }
+
+    /**
+     * 获取已注册的插件
+     * 
+     * @param {string} [pluginName] - 插件名称（可选）
+     * @returns {PluginConfig|Map<string, PluginConfig>} 插件配置或插件集合
+     * 
+     * @example
+     * ```javascript
+     * // 获取单个插件
+     * const plugin = pluginManager.get('custom-validator');
+     * 
+     * // 获取所有插件
+     * const allPlugins = pluginManager.get();
+     * ```
+     */
+    get(pluginName) {
+        if (pluginName) {
+            return this.plugins.get(pluginName);
+        }
+        return this.plugins;
+    }
+
+    /**
+     * 检查插件是否已注册
+     * 
+     * @param {string} pluginName - 插件名称
+     * @returns {boolean} 是否已注册
+     */
+    has(pluginName) {
+        return this.plugins.has(pluginName);
+    }
+
+    /**
+     * 获取插件列表
+     * 
+     * @returns {Array<{name: string, version: string, description: string}>} 插件列表
+     * 
+     * @example
+     * ```javascript
+     * const pluginList = pluginManager.list();
+     * console.log(pluginList);
+     * // [
+     * //   { name: 'custom-validator', version: '1.0.0', description: '...' },
+     * //   { name: 'custom-format', version: '1.0.0', description: '...' }
+     * // ]
+     * ```
+     */
+    list() {
+        return Array.from(this.plugins.values()).map(plugin => ({
+            name: plugin.name,
+            version: plugin.version || 'unknown',
+            description: plugin.description || ''
+        }));
+    }
+
+    /**
+     * 清空所有插件
+     * 
+     * @param {Object} coreInstance - SchemaIO 实例
+     */
+    clear(coreInstance) {
+        // 卸载所有插件
+        Array.from(this.plugins.keys()).forEach(name => {
+            try {
+                this.uninstall(name, coreInstance);
+            } catch (error) {
+                // 忽略卸载错误
+            }
+        });
+
+        // 清空注册表
+        this.plugins.clear();
+
+        // 清空钩子
+        this.hooks.forEach(handlers => handlers.length = 0);
+
+        this.emit('plugins:cleared');
+        return this;
+    }
+
+    /**
+     * 获取插件数量
+     * 
+     * @returns {number} 插件数量
+     */
+    get size() {
+        return this.plugins.size;
+    }
+}
+
+module.exports = PluginManager;
+

package/lib/core/StringExtensions.js

@@ -0,0 +1,209 @@
+/**
+ * String.prototype 扩展
+ *
+ * 让字符串可以直接链式调用 DSL 方法
+ *
+ * @example
+ * 'email!'.pattern(/custom/).label('邮箱')
+ * 'string:3-32!'.messages({ ... }).label('用户名')
+ */
+
+/**
+ * 安装 String 扩展
+ * @param {Function} dslFunction - dsl() 函数
+ */
+function installStringExtensions(dslFunction) {
+  // 检查是否已安装
+  if (String.prototype._dslExtensionsInstalled) {
+    return;
+  }
+
+  /**
+   * 添加正则验证
+   * @param {RegExp} regex - 正则表达式
+   * @param {string} [message] - 错误消息
+   * @returns {DslBuilder}
+   */
+  String.prototype.pattern = function(regex, message) {
+    return dslFunction(String(this)).pattern(regex, message);
+  };
+
+  /**
+   * 设置字段标签
+   * @param {string} label - 标签文本
+   * @returns {DslBuilder}
+   */
+  String.prototype.label = function(label) {
+    return dslFunction(String(this)).label(label);
+  };
+
+  /**
+   * 自定义错误消息
+   * @param {Object} messages - 消息对象
+   * @returns {DslBuilder}
+   */
+  String.prototype.messages = function(messages) {
+    return dslFunction(String(this)).messages(messages);
+  };
+
+  /**
+   * 设置描述
+   * @param {string} text - 描述文本
+   * @returns {DslBuilder}
+   */
+  String.prototype.description = function(text) {
+    return dslFunction(String(this)).description(text);
+  };
+
+  /**
+   * 设置格式
+   * @param {string} format - 格式名称
+   * @returns {DslBuilder}
+   */
+  String.prototype.format = function(format) {
+    return dslFunction(String(this)).format(format);
+  };
+
+  /**
+   * 添加自定义验证器
+   * @param {Function} validator - 验证函数
+   * @returns {DslBuilder}
+   */
+  String.prototype.custom = function(validator) {
+    return dslFunction(String(this)).custom(validator);
+  };
+
+
+  /**
+   * 设置默认值
+   * @param {*} value - 默认值
+   * @returns {DslBuilder}
+   */
+  String.prototype.default = function(value) {
+    return dslFunction(String(this)).default(value);
+  };
+
+  /**
+   * 转为 Schema
+   * @returns {Object}
+   */
+  String.prototype.toSchema = function() {
+    return dslFunction(String(this)).toSchema();
+  };
+
+  /**
+   * 用户名验证
+   * @param {Object} options - 选项
+   * @returns {DslBuilder}
+   */
+  String.prototype.username = function(options) {
+    return dslFunction(String(this)).username(options);
+  };
+
+  /**
+   * 密码强度验证
+   * @param {string} strength - 强度级别
+   * @returns {DslBuilder}
+   */
+  String.prototype.password = function(strength) {
+    return dslFunction(String(this)).password(strength);
+  };
+
+  /**
+   * 手机号验证
+   * @param {string} country - 国家代码
+   * @returns {DslBuilder}
+   */
+  String.prototype.phone = function(country) {
+    return dslFunction(String(this)).phone(country);
+  };
+
+  /**
+   * 手机号验证（别名）
+   * @param {string} country - 国家代码
+   * @returns {DslBuilder}
+   */
+  String.prototype.phoneNumber = function(country) {
+    return dslFunction(String(this)).phone(country);
+  };
+
+  /**
+   * 身份证验证
+   * @param {string} country - 国家代码
+   * @returns {DslBuilder}
+   */
+  String.prototype.idCard = function(country) {
+    return dslFunction(String(this)).idCard(country);
+  };
+
+  /**
+   * 信用卡验证
+   * @param {string} type - 卡类型
+   * @returns {DslBuilder}
+   */
+  String.prototype.creditCard = function(type) {
+    return dslFunction(String(this)).creditCard(type);
+  };
+
+  /**
+   * 车牌号验证
+   * @param {string} country - 国家代码
+   * @returns {DslBuilder}
+   */
+  String.prototype.licensePlate = function(country) {
+    return dslFunction(String(this)).licensePlate(country);
+  };
+
+  /**
+   * 邮政编码验证
+   * @param {string} country - 国家代码
+   * @returns {DslBuilder}
+   */
+  String.prototype.postalCode = function(country) {
+    return dslFunction(String(this)).postalCode(country);
+  };
+
+  /**
+   * 护照号码验证
+   * @param {string} country - 国家代码
+   * @returns {DslBuilder}
+   */
+  String.prototype.passport = function(country) {
+    return dslFunction(String(this)).passport(country);
+  };
+
+  // 标记已安装
+  String.prototype._dslExtensionsInstalled = true;
+}
+
+/**
+ * 卸载 String 扩展（测试或清理用）
+ */
+function uninstallStringExtensions() {
+  if (!String.prototype._dslExtensionsInstalled) {
+    return;
+  }
+
+  delete String.prototype.pattern;
+  delete String.prototype.label;
+  delete String.prototype.messages;
+  delete String.prototype.description;
+  delete String.prototype.custom;
+  delete String.prototype.when;
+  delete String.prototype.default;
+  delete String.prototype.toSchema;
+  delete String.prototype.username;
+  delete String.prototype.password;
+  delete String.prototype.phone;
+  delete String.prototype.idCard;
+  delete String.prototype.creditCard;
+  delete String.prototype.licensePlate;
+  delete String.prototype.postalCode;
+  delete String.prototype.passport;
+  delete String.prototype._dslExtensionsInstalled;
+}
+
+module.exports = {
+  installStringExtensions,
+  uninstallStringExtensions
+};