@composy/config-core

审计增强摘要

• 配置值统一执行 JSON-safe 校验与深拷贝隔离；undefined 仅保留为兼容性的删除占位值。Date、RegExp、Map、Set、函数、类实例、循环引用、非有限数字和原型污染键会被拒绝。
• Schema 校验器支持 separator，与 ConfigManager.separator 一致，并对规则与全局/粘性正则状态进行隔离。
• 远程加载支持取消、超时、ETag/版本元数据；带外部 AbortSignal 的调用不会共享可被单方取消的请求 Promise，销毁后的迟到响应不会提交配置或历史。
• 持久化支持命名空间、注入式 storage、状态/错误诊断，并保证读写异常和反抖定时器不泄漏；损坏 JSON 会保留 error 状态，同时继续加载其它有效记录。
• batch() 只合并通知，不提供回滚语义；Engine 绑定支持命名空间，安装失败会回滚 state 与监听器。

框架无关的 LDesign 配置核心包。所有配置领域能力都优先在这里实现，Vue 等适配包只消费这里暴露的 API。

能力

• 路径读写：支持 api.timeout 与 ['api', 'timeout'] 两种路径写法。
• 原子更新：update() 基于当前值派生新值，并复用 set() 的校验、历史和通知流程。
• 批量变更：batch() 合并多次变更通知，适合初始化或复杂表单提交。
• 历史与版本：可通过 maxHistorySize 控制历史容量，通过 getVersion() 追踪变更版本。
• 命名空间：getNamespace() 提供前缀作用域，避免上层重复拼接 key。
• 远程加载：支持自定义 fetcher、轮询、替换或合并远程配置。
• 持久化：支持 localStorage/sessionStorage，并可配置 include/exclude。
• Schema 校验：提供字段级规则校验，并可转成 ConfigOptions.validator。
• Engine 绑定：通过最小 Engine-like 接口同步 manager、状态与事件。

快速使用

import { ConfigManager } from '@composy/config-core'

const manager = new ConfigManager({
  initial: {
    api: { timeout: 5000 },
    ui: { theme: 'light' },
  },
  maxHistorySize: 50,
})

const timeout = manager.get<number>('api.timeout', 3000)

manager.set('api.timeout', timeout + 1000)

const nextTimeout = manager.update<number>('api.timeout', value => (value ?? 0) + 1000)

const stop = manager.onChange((event) => {
  console.info(event.key, event.oldValue, event.newValue)
})

stop()

命名空间

const api = manager.getNamespace('api')

api.set('timeout', 10000)
api.update<number>('retry', value => (value ?? 0) + 1)

Schema 校验

import { ConfigManager, createSchemaValidator } from '@composy/config-core'

const schema = createSchemaValidator({
  'api.timeout': { type: 'number', min: 0, max: 60000, label: '请求超时' },
  'ui.theme': { type: 'string', enum: ['light', 'dark'] },
})

const manager = new ConfigManager({
  validator: schema.asConfigValidator(),
})

持久化

import { ConfigManager, createPersistenceAdapter } from '@composy/config-core'

const manager = new ConfigManager({
  initial: { ui: { theme: 'light' } },
})

const persistence = createPersistenceAdapter(manager, {
  storage: 'localStorage',
  prefix: 'my-app',
  include: ['ui.theme'],
})

persistence.load()
persistence.save()
persistence.destroy()

持久化按叶子路径读写：include: ['ui'] 会保存 ui 下的所有叶子项，include: ['ui.theme'] 仅保存主题字段；exclude 始终优先于 include。加载多个持久化项时只产生一次合并变更通知。

安全约束

配置路径和记录键不能使用 __proto__、constructor 或 prototype。这些键会抛出 TypeError，防止路径写入、远程配置或持久化数据污染对象原型链。

维护约定

• core 不依赖 Vue、React、DOM UI 生命周期或任何框架运行时。
• 新增公共 API 必须补充 test/type/*.test-d.ts 和最小运行时 smoke。
• 变更配置提交路径时必须复用 commit()，确保校验、历史、版本和通知语义一致。
• 错误类型尽量准确，类型不匹配使用 TypeError。

构建与验证

本包固定使用 @composy/builder 的 rolldown bundler。build 会生成 dist/（UMD 与真实压缩的 index.min.js）、es/（ESM 与声明）、esm/（保留模块结构的 ESM）和 lib/（CommonJS 与声明）；随后归一化声明文件和 lib/package.json。

pnpm --dir packages/config/packages/core run typecheck
pnpm --dir packages/config/packages/core run lint:check
pnpm --dir packages/config/packages/core run test:run
pnpm --dir packages/config/packages/core run build

# 检查 package.json 全部入口是否有对应产物
node --experimental-strip-types scripts/index.ts workspace:check-package-outputs --cwd packages/config --target core

本包 ESLint 与 TypeScript 的权威配置位于 .ldesign/；包根配置文件仅作为兼容 shim。