@nimbus2d/core 0.0.1

package/src/core/ConfigSystem/ConfigSystem.js

@@ -0,0 +1,378 @@
+// ============================================================================
+// Nimbus2D - ConfigSystem 配置系统
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 运行时可变 + 监听 + 分层覆盖
+//   2. 4 层配置：DEFAULT → MODULE → USER → RUNTIME（优先级递增）
+//   3. 完整 API：set/get/has/delete/watch/unwatch/loadJSON/loadModule
+//   4. 类型校验（可选，setTypeValidation 启用）
+//   5. 路径缓存（Map<string, string[]>）
+//   6. 静默模式（options.silent）
+//
+// 继承关系：
+//   EventEmitter → ConfigSystem（基础设施，不被 Lifecycle 调度）
+// ============================================================================
+
+import { EventEmitter } from '../../base/EventEmitter.js'
+import { ConfigLayer } from './ConfigLayer.js'
+import { ConfigLayerType, LAYER_FREEZABLE_DEFAULTS } from './ConfigLayerType.js'
+import { ConfigPath } from './ConfigPath.js'
+import { ConfigWatcher } from './ConfigWatcher.js'
+import { deepMerge } from './ConfigMerger.js'
+import { getType, SUPPORTED_TYPES } from './ConfigTypes.js'
+import { ConfigError, ConfigPathError } from '../../errors/ConfigError.js'
+
+class ConfigSystem extends EventEmitter {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    super()
+
+    /**
+     * 配置层映射（按优先级从低到高）
+     * @type {Map<string, ConfigLayer>}
+     */
+    this._layers = new Map()
+
+    /** @type {ConfigPath} 路径解析工具 */
+    this._pathTool = new ConfigPath()
+
+    /** @type {ConfigWatcher} 监听器管理 */
+    this._watcher = new ConfigWatcher()
+
+    /**
+     * 类型校验 schema
+     * @type {Object<string, string>|null}
+     */
+    this._schema = null
+
+    /** @type {boolean} 是否已初始化 */
+    this._isInitialized = false
+  }
+
+  // --------------------------------------------------------------------------
+  // 读写方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 设置运行时配置（写入 RUNTIME 层）
+   * @param {string} path - 配置路径（如 'modules.logger.level'）
+   * @param {any} value - 配置值
+   * @param {Object} [options={}] - 选项
+   * @param {boolean} [options.silent=false] - 静默模式（路径父级不存在时不抛错，返回 false）
+   * @returns {boolean} 是否设置成功
+   */
+  set(path, value, options = {}) {
+    if (this._destroyed) return false
+
+    // 类型校验
+    if (this._schema && !this._validateType(path, value, options)) {
+      return false
+    }
+
+    // 获取旧值（用于监听器通知）
+    const oldValue = this._getRaw(path)
+
+    // 设置到 RUNTIME 层
+    const runtimeLayer = this._layers.get(ConfigLayerType.RUNTIME)
+    if (!runtimeLayer) {
+      if (options.silent) return false
+      throw new ConfigError('RUNTIME 配置层未初始化', 'CONFIG_LAYER_MISSING')
+    }
+
+    const result = runtimeLayer.set(path, value)
+    if (!result && !options.silent) {
+      return false
+    }
+
+    // 通知监听器
+    if (result) {
+      this._watcher.notify(path, value, oldValue)
+      this.emit('change', { path, oldValue, newValue: value })
+    }
+
+    return result
+  }
+
+  /**
+   * 获取配置（按优先级查询：RUNTIME → USER → MODULE → DEFAULT）
+   * @param {string} path - 配置路径
+   * @param {any} [defaultValue=undefined] - 默认值
+   * @param {Object} [options={}] - 选项
+   * @param {boolean} [options.silent=false] - 静默模式（路径不存在时不抛错，返回 defaultValue）
+   * @returns {any} 配置值
+   */
+  get(path, defaultValue = undefined, options = {}) {
+    if (this._destroyed) return defaultValue
+
+    // 按优先级从高到低查询
+    const layerOrder = [
+      ConfigLayerType.RUNTIME,
+      ConfigLayerType.USER,
+      ConfigLayerType.MODULE,
+      ConfigLayerType.DEFAULT
+    ]
+
+    for (const layerType of layerOrder) {
+      const layer = this._layers.get(layerType)
+      if (!layer) continue
+
+      const result = layer.get(path)
+      if (result.found) {
+        return result.value
+      }
+    }
+
+    // 未找到
+    if (options.silent) {
+      return defaultValue
+    }
+
+    // 非静默模式不抛错，返回默认值（配置路径可能确实不存在）
+    return defaultValue
+  }
+
+  /**
+   * 检查配置是否存在
+   * @param {string} path - 配置路径
+   * @returns {boolean}
+   */
+  has(path) {
+    if (this._destroyed) return false
+
+    for (const layer of this._layers.values()) {
+      if (layer.has(path)) return true
+    }
+    return false
+  }
+
+  /**
+   * 删除运行时配置
+   * @param {string} path - 配置路径
+   * @returns {boolean} 是否删除成功
+   */
+  delete(path) {
+    if (this._destroyed) return false
+
+    const runtimeLayer = this._layers.get(ConfigLayerType.RUNTIME)
+    if (!runtimeLayer) return false
+
+    const oldValue = this._getRaw(path)
+    const result = runtimeLayer.delete(path)
+
+    if (result) {
+      const newValue = this._getRaw(path)
+      this._watcher.notify(path, newValue, oldValue)
+      this.emit('change', { path, oldValue, newValue })
+    }
+
+    return result
+  }
+
+  /**
+   * 注册类型校验 schema
+   * @param {Object} schema - schema 对象（path => type 字符串）
+   * @returns {ConfigSystem} this（链式）
+   */
+  setTypeValidation(schema) {
+    // 验证 schema 中的类型是否合法
+    for (const [path, type] of Object.entries(schema)) {
+      if (!SUPPORTED_TYPES.includes(type)) {
+        throw new ConfigError(
+          `类型校验 schema 中路径 "${path}" 的类型 "${type}" 不合法，支持：${SUPPORTED_TYPES.join(', ')}`,
+          'CONFIG_INVALID_TYPE'
+        )
+      }
+    }
+    this._schema = schema
+    return this
+  }
+
+  // --------------------------------------------------------------------------
+  // 监听器
+  // --------------------------------------------------------------------------
+
+  /**
+   * 监听配置变化
+   * @param {string} pathPattern - 路径模式（支持通配符 'modules.*.level'）
+   * @param {Function} callback - 回调 (newValue, oldValue, path) => void
+   * @returns {Function} 取消监听函数
+   */
+  watch(pathPattern, callback) {
+    return this._watcher.watch(pathPattern, callback)
+  }
+
+  /**
+   * 取消监听
+   * @param {string} pathPattern - 路径模式
+   * @param {Function} callback - 回调
+   * @returns {boolean}
+   */
+  unwatch(pathPattern, callback) {
+    return this._watcher.unwatch(pathPattern, callback)
+  }
+
+  // --------------------------------------------------------------------------
+  // 批量加载
+  // --------------------------------------------------------------------------
+
+  /**
+   * 批量加载 JSON 配置
+   * @param {Object} json - 配置对象
+   * @param {string} [layerType=ConfigLayerType.USER] - 层类型
+   */
+  loadJSON(json, layerType = ConfigLayerType.USER) {
+    if (this._destroyed) return
+
+    const layer = this._layers.get(layerType)
+    if (!layer) {
+      throw new ConfigError(`配置层 "${layerType}" 未初始化`, 'CONFIG_LAYER_MISSING')
+    }
+    layer.loadJSON(json)
+  }
+
+  /**
+   * 加载模块默认配置（写入 MODULE 层）
+   * @param {string} moduleName - 模块名称
+   * @param {Object} config - 模块默认配置
+   */
+  loadModule(moduleName, config) {
+    if (this._destroyed) return
+
+    const moduleLayer = this._layers.get(ConfigLayerType.MODULE)
+    if (!moduleLayer) {
+      throw new ConfigError('MODULE 配置层未初始化', 'CONFIG_LAYER_MISSING')
+    }
+
+    // 以模块名为前缀合并到 MODULE 层
+    const moduleConfig = { [moduleName]: config }
+    moduleLayer.loadJSON(moduleConfig)
+  }
+
+  // --------------------------------------------------------------------------
+  // 层管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取配置层
+   * @param {string} layerType - ConfigLayerType 枚举值
+   * @returns {ConfigLayer|undefined}
+   */
+  getLayer(layerType) {
+    return this._layers.get(layerType)
+  }
+
+  /**
+   * 获取所有层
+   * @returns {ConfigLayer[]}
+   */
+  getAllLayers() {
+    return Array.from(this._layers.values())
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期方法（基础设施，不继承 Subsystem）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化 4 层配置
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this._isInitialized) return
+
+    // 创建 4 层配置
+    for (const [type, freezable] of Object.entries(LAYER_FREEZABLE_DEFAULTS)) {
+      this._layers.set(type, new ConfigLayer(type, {}, freezable))
+    }
+
+    this._isInitialized = true
+  }
+
+  /**
+   * 销毁配置系统，清理监听器和配置
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this._destroyed) return
+
+    // 清理监听器
+    this._watcher.clear()
+
+    // 清理路径缓存
+    this._pathTool.clearCache()
+
+    // 清理配置层
+    for (const layer of this._layers.values()) {
+      layer.clear()
+    }
+    this._layers.clear()
+
+    // 清理 schema
+    this._schema = null
+
+    this.emit('destroyed')
+    super.destroy()
+  }
+
+  // --------------------------------------------------------------------------
+  // 内部方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取原始值（不经过默认值处理）
+   * @param {string} path - 配置路径
+   * @returns {any} 配置值（未找到返回 undefined）
+   * @private
+   */
+  _getRaw(path) {
+    const layerOrder = [
+      ConfigLayerType.RUNTIME,
+      ConfigLayerType.USER,
+      ConfigLayerType.MODULE,
+      ConfigLayerType.DEFAULT
+    ]
+
+    for (const layerType of layerOrder) {
+      const layer = this._layers.get(layerType)
+      if (!layer) continue
+
+      const result = layer.get(path)
+      if (result.found) {
+        return result.value
+      }
+    }
+
+    return undefined
+  }
+
+  /**
+   * 类型校验
+   * @param {string} path - 配置路径
+   * @param {any} value - 配置值
+   * @param {Object} options - 选项
+   * @returns {boolean} 是否通过校验
+   * @private
+   */
+  _validateType(path, value, options = {}) {
+    if (!this._schema) return true
+
+    // 查找匹配的 schema 规则
+    const expectedType = this._schema[path]
+    if (!expectedType) return true // 没有对应的校验规则，通过
+
+    const actualType = getType(value)
+    if (actualType !== expectedType) {
+      const errorMsg = `配置类型不匹配：路径 "${path}" 期望 ${expectedType}，实际 ${actualType}`
+      if (options.silent) {
+        return false
+      }
+      throw new ConfigError(errorMsg, 'CONFIG_TYPE_MISMATCH')
+    }
+
+    return true
+  }
+}
+
+export { ConfigSystem }

package/src/core/ConfigSystem/ConfigTypes.js

@@ -0,0 +1,29 @@
+// ============================================================================
+// Nimbus2D - 配置类型定义
+// ----------------------------------------------------------------------------
+// ConfigSchema 类型校验定义
+// ============================================================================
+
+/**
+ * 配置类型校验 schema
+ * key 为配置路径，value 为类型字符串
+ * 支持的类型：'number'、'string'、'boolean'、'object'、'array'、'function'
+ * @typedef {Object<string, string>} ConfigSchema
+ */
+
+/**
+ * 支持的类型校验列表
+ * @type {string[]}
+ */
+export const SUPPORTED_TYPES = ['number', 'string', 'boolean', 'object', 'array', 'function']
+
+/**
+ * 获取值的实际类型
+ * @param {any} value - 要检查的值
+ * @returns {string} 类型字符串
+ */
+export function getType(value) {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}

package/src/core/ConfigSystem/ConfigWatcher.js

@@ -0,0 +1,84 @@
+// ============================================================================
+// Nimbus2D - 配置监听器管理
+// ----------------------------------------------------------------------------
+// 管理配置变化监听器，支持通配符路径模式
+// ============================================================================
+
+import { ConfigPath } from './ConfigPath.js'
+
+/**
+ * 配置监听器管理类
+ * 管理 watch/unwatch 和变化通知
+ */
+class ConfigWatcher {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /**
+     * 监听器列表
+     * @type {Array<{pattern: string, callback: Function, pathTool: ConfigPath}>}
+     */
+    this._watchers = []
+
+    /** @type {ConfigPath} 路径工具 */
+    this._pathTool = new ConfigPath()
+  }
+
+  /**
+   * 注册监听器
+   * @param {string} pathPattern - 路径模式（支持通配符 'modules.*.level'）
+   * @param {Function} callback - 回调 (newValue, oldValue, path) => void
+   * @returns {Function} 取消监听函数
+   */
+  watch(pathPattern, callback) {
+    const entry = { pattern: pathPattern, callback, pathTool: this._pathTool }
+    this._watchers.push(entry)
+
+    return () => this.unwatch(pathPattern, callback)
+  }
+
+  /**
+   * 取消监听
+   * @param {string} pathPattern - 路径模式
+   * @param {Function} callback - 回调函数
+   * @returns {boolean} 是否取消成功
+   */
+  unwatch(pathPattern, callback) {
+    const idx = this._watchers.findIndex(
+      (w) => w.pattern === pathPattern && w.callback === callback
+    )
+    if (idx !== -1) {
+      this._watchers.splice(idx, 1)
+      return true
+    }
+    return false
+  }
+
+  /**
+   * 通知配置变化
+   * @param {string} path - 变化的配置路径
+   * @param {any} newValue - 新值
+   * @param {any} oldValue - 旧值
+   */
+  notify(path, newValue, oldValue) {
+    for (const watcher of this._watchers) {
+      if (this._pathTool.match(watcher.pattern, path)) {
+        try {
+          watcher.callback(newValue, oldValue, path)
+        } catch (e) {
+          console.error(`[ConfigWatcher] 监听器执行出错 (${watcher.pattern}):`, e)
+        }
+      }
+    }
+  }
+
+  /**
+   * 清空所有监听器
+   */
+  clear() {
+    this._watchers = []
+  }
+}
+
+export { ConfigWatcher }

package/src/core/ConfigSystem/index.js

@@ -0,0 +1,19 @@
+// ============================================================================
+// Nimbus2D - ConfigSystem 模块统一导出
+// ============================================================================
+
+export { ConfigSystem } from './ConfigSystem.js'
+export { ConfigLayer } from './ConfigLayer.js'
+export { ConfigLayerType, LAYER_FREEZABLE_DEFAULTS } from './ConfigLayerType.js'
+export { ConfigPath } from './ConfigPath.js'
+export { ConfigWatcher } from './ConfigWatcher.js'
+export { deepMerge, deepFreeze } from './ConfigMerger.js'
+
+/** 深度合并与冻结工具（命名导出别名，供主入口 ConfigMerger 使用） */
+export { deepMerge as ConfigMerger } from './ConfigMerger.js'
+
+/** 配置类型校验工具 */
+export { SUPPORTED_TYPES, getType } from './ConfigTypes.js'
+
+/** 配置类型校验命名空间（供主入口 ConfigTypes 使用） */
+export * as ConfigTypes from './ConfigTypes.js'