@nimbus2d/core 0.0.1

package/src/core/ConfigSystem/ConfigLayer.js

@@ -0,0 +1,230 @@
+// ============================================================================
+// Nimbus2D - 配置层
+// ----------------------------------------------------------------------------
+// 封装单层配置的读写操作
+// ============================================================================
+
+import { deepFreeze } from './ConfigMerger.js'
+
+/**
+ * 配置层类
+ * 封装单层配置的读写操作，支持深度路径访问
+ */
+class ConfigLayer {
+  /**
+   * 构造函数
+   * @param {string} type - ConfigLayerType 枚举值
+   * @param {Object} [data={}] - 初始数据
+   * @param {boolean} [freezable=true] - 是否可深度冻结
+   */
+  constructor(type, data = {}, freezable = true) {
+    /** @type {string} 层类型 */
+    this._type = type
+
+    /** @type {Object} 配置数据 */
+    this._data = { ...data }
+
+    /** @type {boolean} 是否可深度冻结 */
+    this._freezable = freezable
+
+    // 如果 freezable 为 true，立即冻结
+    if (this._freezable && Object.keys(this._data).length > 0) {
+      deepFreeze(this._data)
+    }
+  }
+
+  /** @type {string} 层类型 */
+  get type() {
+    return this._type
+  }
+
+  /** @type {Object} 配置数据（只读快照） */
+  get data() {
+    return this._data
+  }
+
+  /**
+   * 读取配置（支持深度路径）
+   * @param {string} path - 配置路径（如 'pixi.width'）
+   * @returns {{ found: boolean, value: any }} 查找结果
+   */
+  get(path) {
+    const segments = path.split('.')
+    let current = this._data
+
+    for (const segment of segments) {
+      if (current === null || current === undefined || typeof current !== 'object') {
+        return { found: false, value: undefined }
+      }
+      if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+        return { found: false, value: undefined }
+      }
+      current = current[segment]
+    }
+
+    return { found: true, value: current }
+  }
+
+  /**
+   * 写入配置（支持深度路径）
+   * 对于 freezable=true 的层，写入前会先解冻再冻结
+   * @param {string} path - 配置路径
+   * @param {any} value - 配置值
+   * @returns {boolean} 是否设置成功
+   */
+  set(path, value) {
+    const segments = path.split('.')
+
+    // 如果 freezable，需要先解冻
+    if (this._freezable && Object.isFrozen(this._data)) {
+      this._data = _deepClone(this._data)
+    }
+
+    let current = this._data
+
+    // 遍历到倒数第二层
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i]
+      if (current[segment] === undefined || typeof current[segment] !== 'object') {
+        // 中间节点不存在或不是对象，创建中间对象
+        current[segment] = {}
+      } else if (Object.isFrozen(current[segment])) {
+        // 中间节点被冻结，需要解冻
+        current[segment] = _deepClone(current[segment])
+      }
+      current = current[segment]
+    }
+
+    // 设置最后一层的值
+    const lastKey = segments[segments.length - 1]
+    current[lastKey] = value
+
+    // 如果 freezable，重新冻结
+    if (this._freezable) {
+      deepFreeze(this._data)
+    }
+
+    return true
+  }
+
+  /**
+   * 检查配置是否存在
+   * @param {string} path - 配置路径
+   * @returns {boolean}
+   */
+  has(path) {
+    return this.get(path).found
+  }
+
+  /**
+   * 删除配置
+   * @param {string} path - 配置路径
+   * @returns {boolean} 是否删除成功
+   */
+  delete(path) {
+    const segments = path.split('.')
+
+    // 如果 freezable，需要先解冻
+    if (this._freezable && Object.isFrozen(this._data)) {
+      this._data = _deepClone(this._data)
+    }
+
+    let current = this._data
+
+    // 遍历到倒数第二层
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i]
+      if (current[segment] === undefined || typeof current[segment] !== 'object') {
+        return false
+      }
+      if (Object.isFrozen(current[segment])) {
+        current[segment] = _deepClone(current[segment])
+      }
+      current = current[segment]
+    }
+
+    const lastKey = segments[segments.length - 1]
+    if (!Object.prototype.hasOwnProperty.call(current, lastKey)) {
+      return false
+    }
+
+    delete current[lastKey]
+
+    if (this._freezable) {
+      deepFreeze(this._data)
+    }
+
+    return true
+  }
+
+  /**
+   * 批量加载配置（深度合并）
+   * @param {Object} json - 配置对象
+   */
+  loadJSON(json) {
+    // 如果 freezable，先解冻
+    if (this._freezable && Object.isFrozen(this._data)) {
+      this._data = _deepClone(this._data)
+    }
+
+    this._data = _deepMergeSimple(this._data, json)
+
+    if (this._freezable) {
+      deepFreeze(this._data)
+    }
+  }
+
+  /**
+   * 清空配置
+   */
+  clear() {
+    this._data = {}
+  }
+}
+
+/**
+ * 深度克隆对象（解除冻结，递归克隆所有子对象）
+ * @param {Object} obj - 要克隆的对象
+ * @returns {Object} 克隆后的对象
+ * @private
+ */
+function _deepClone(obj) {
+  const clone = {}
+  for (const key of Object.keys(obj)) {
+    const value = obj[key]
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      clone[key] = _deepClone(value)
+    } else {
+      clone[key] = value
+    }
+  }
+  return clone
+}
+
+/**
+ * 简单深度合并（ConfigLayer 内部用）
+ * @param {Object} target - 目标
+ * @param {Object} source - 源
+ * @returns {Object}
+ * @private
+ */
+function _deepMergeSimple(target, source) {
+  const result = { ...target }
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = _deepMergeSimple(target[key], source[key])
+    } else {
+      result[key] = source[key]
+    }
+  }
+  return result
+}
+
+export { ConfigLayer }

package/src/core/ConfigSystem/ConfigLayerType.js

@@ -0,0 +1,31 @@
+// ============================================================================
+// Nimbus2D - 配置层类型枚举
+// ----------------------------------------------------------------------------
+// 4 层配置：DEFAULT → MODULE → USER → RUNTIME（优先级递增）
+// ============================================================================
+
+/**
+ * 配置层类型枚举
+ * @enum {string}
+ */
+export const ConfigLayerType = {
+  /** 默认配置层（代码内置，freezable=true） */
+  DEFAULT: 'default',
+  /** 模块配置层（各模块自带，freezable=false） */
+  MODULE: 'module',
+  /** 用户配置层（构造参数传入，freezable=false） */
+  USER: 'user',
+  /** 运行时配置层（set() 修改，freezable=false） */
+  RUNTIME: 'runtime'
+}
+
+/**
+ * 各层的 freezable 默认值
+ * 只有 DEFAULT 层默认冻结
+ */
+export const LAYER_FREEZABLE_DEFAULTS = {
+  [ConfigLayerType.DEFAULT]: true,
+  [ConfigLayerType.MODULE]: false,
+  [ConfigLayerType.USER]: false,
+  [ConfigLayerType.RUNTIME]: false
+}

package/src/core/ConfigSystem/ConfigMerger.js

@@ -0,0 +1,50 @@
+// ============================================================================
+// Nimbus2D - 深度合并 + 深度冻结工具
+// ----------------------------------------------------------------------------
+// 提供 deepMerge 和 deepFreeze 工具函数
+// ============================================================================
+
+/**
+ * 深度合并两个对象（source 覆盖 target）
+ * 数组直接替换，不递归合并
+ * @param {Object} target - 目标对象
+ * @param {Object} source - 源对象
+ * @returns {Object} 合并后的新对象
+ */
+export function deepMerge(target, source) {
+  const result = { ...target }
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key])
+    } else {
+      result[key] = source[key]
+    }
+  }
+  return result
+}
+
+/**
+ * 深度冻结对象（递归冻结所有属性）
+ * @param {Object} obj - 要冻结的对象
+ * @returns {Object} 冻结后的对象
+ */
+export function deepFreeze(obj) {
+  if (obj === null || typeof obj !== 'object') return obj
+
+  // 先冻结所有子属性
+  for (const key of Object.keys(obj)) {
+    const value = obj[key]
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+      deepFreeze(value)
+    }
+  }
+
+  return Object.freeze(obj)
+}

package/src/core/ConfigSystem/ConfigPath.js

@@ -0,0 +1,96 @@
+// ============================================================================
+// Nimbus2D - 配置路径解析工具
+// ----------------------------------------------------------------------------
+// 提供路径解析和通配符匹配功能，含路径缓存
+// ============================================================================
+
+/**
+ * 路径解析工具
+ * 提供路径段解析和通配符匹配功能
+ */
+class ConfigPath {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /**
+     * 路径缓存：path(string) => segments(string[])
+     * @type {Map<string, string[]>}
+     */
+    this._cache = new Map()
+  }
+
+  /**
+   * 解析路径为段数组（带缓存）
+   * @param {string} path - 配置路径（如 'modules.logger.level'）
+   * @returns {string[]} 路径段数组（如 ['modules', 'logger', 'level']）
+   */
+  resolve(path) {
+    if (this._cache.has(path)) {
+      return this._cache.get(path)
+    }
+    const segments = path.split('.')
+    this._cache.set(path, segments)
+    return segments
+  }
+
+  /**
+   * 检查路径是否匹配通配符模式
+   * 支持 'modules.*.level'（单层通配）和 'modules.**'（多层通配）
+   * @param {string} pattern - 通配符模式
+   * @param {string} path - 实际路径
+   * @returns {boolean} 是否匹配
+   */
+  match(pattern, path) {
+    const patternParts = pattern.split('.')
+    const pathParts = path.split('.')
+    return this._matchParts(patternParts, 0, pathParts, 0)
+  }
+
+  /**
+   * 递归匹配路径段
+   * @param {string[]} patternParts - 模式段
+   * @param {number} pi - 模式索引
+   * @param {string[]} pathParts - 路径段
+   * @param {number} pathi - 路径索引
+   * @returns {boolean}
+   * @private
+   */
+  _matchParts(patternParts, pi, pathParts, pathi) {
+    // 模式和路径都遍历完毕 → 匹配
+    if (pi === patternParts.length && pathi === pathParts.length) return true
+    // 模式遍历完但路径未完 → 不匹配
+    if (pi === patternParts.length) return false
+
+    const part = patternParts[pi]
+
+    if (part === '**') {
+      // ** 匹配零个或多个段
+      // 跳过 **，尝试从路径的每个位置匹配剩余模式
+      for (let i = pathi; i <= pathParts.length; i++) {
+        if (this._matchParts(patternParts, pi + 1, pathParts, i)) return true
+      }
+      return false
+    }
+
+    if (part === '*') {
+      // * 匹配一个段
+      if (pathi >= pathParts.length) return false
+      return this._matchParts(patternParts, pi + 1, pathParts, pathi + 1)
+    }
+
+    // 精确匹配
+    if (pathi >= pathParts.length) return false
+    if (part !== pathParts[pathi]) return false
+    return this._matchParts(patternParts, pi + 1, pathParts, pathi + 1)
+  }
+
+  /**
+   * 清理缓存
+   */
+  clearCache() {
+    this._cache.clear()
+  }
+}
+
+export { ConfigPath }