@gaia-框架/配置

为 Node.js 应用程序同步配置:分层的 YAML 或 TOML 文件, 环境覆盖、可重复使用的文件碎片、可选 Zod 校验,以及 键入取取器。 用普通对象使用它,将文件加载到读取器中,或绑定 应用程序的 DI 容器中的配置服务 。 图书馆没有 运行时间依赖容器或装饰元数据.

• 顺序文件层和清晰 --config 选择.
• 深对象合并、阵列替换和清晰 null 数值.
• 环境占地者,倒置者,出逃者,和一键重置者.
• $env, (中文(简体) ), $file,以及 YAML/JSON/TOML 数据 $include 带有片段选择的指令.
• 必需的和可选的获取器、 字形密钥路径和密钥计数 .
• 可选的严格输入检查、孤立的环境、不可改变的快照和 安全错误.
• TypeScript申报和汇编无害环境管理出口.

图书馆持有麻省理工学院许可证. 软件包档案包括来源、已编译的导出、, 宣言、文件和实例.

私下报告脆弱性 警卫。 。 。 .

所需资源

节点.js 24个或较新,包含无害环境管理进口。 CI 验证 Windows 上的节点 24 和 莱纳克. 普通消费者运行编译的 JavaScript 不使用 tsx 或特别 节点条件. 没有提供普通JS和浏览器构建.

支助范围

自动发现默认为 .yaml; 选择 fileFormat: 'toml' 页:1 .toml 层。 包括支助 .yaml, (中文(简体) ), .yml, (中文(简体) ), .json 财务报告和审定财务报表 .toml,包括混合格式 锁链。 没有远程加载,监视器,也没有Aync API. 见 移动。 。 。 . 导入库不装入 .env 文档.

安装

在应用程序中安装软件包 :

npm install @gaia-framework/config

或与雅尔曰:

yarn add @gaia-framework/config

Zod是可选的。 单独安装 yarn add zod 如果您的申请 使用Zod schemas(英语:Zod schemas).

构建本地归档

如果 yarn 命令未安装, 将它安装到全球一次 :

npm install -g yarn

在这个仓库里, yarn 使用已检查的 Yarn 4.1.20. 运行时间 .yarnrc.yml现有由核心软件包管理 yarn 命令也会起作用.

要通过退票建立归档, 您可以访问 :

git clone https://github.com/gaia-framework/config.git
cd config
yarn install --immutable
yarn build
yarn pack --out artifacts/gaia-framework-config-0.3.1.tgz

将生成的归档复制到您的应用程序目录中, 然后安装 :

yarn add ./gaia-framework-config-0.3.1.tgz

档案包括已汇编的出口、申报、发展来源、文件、, 实例和许可证。 它的工作独立于这个检查.

快开始

另存为 app.ts 在应用程序中运行 node app.ts数字 :

import { createConfig } from '@gaia-framework/config';

const config = createConfig({
  http: { port: 4001 },
  feature: { enabled: true },
  providers: ['local']
});

console.log(config.getNumber('http.port')); // 4001
console.log(config.getBoolean('feature.enabled')); // true
console.log(config.getStringArray('providers')); // ['local']
console.log(config.getOptionalString('http.host') ?? 'localhost'); // localhost

装入 YAML 文件

创建 config.yaml 在应用程序的工作目录中 :

http:
  host: ${APP_HOST:-localhost}
  port: 4001
feature:
  enabled: ${APP_FEATURE_ENABLED:-false}

替换 app.ts 改为:

import { createConfigFromFiles } from '@gaia-framework/config';

const config = createConfigFromFiles({ argv: [] });

console.log(config.getNumber('http.port')); // 4001
console.log(config.getString('http.host')); // localhost when APP_HOST is unset
console.log(config.getBoolean('feature.enabled')); // false when unset

argv: [] 禁止检查应用程序的命令行参数. 让它接受重复 --config <file> 参数,例如 node app.ts --config base.yaml --config deployment.yaml替换选中的文件 自动发现并按参数顺序合并.

装入 TOML 文件

创建 config.toml数字 :

[http]
port = 4001
host = "${APP_HOST:-localhost}"

[feature]
enabled = "${APP_FEATURE_ENABLED:-false}"

明确选择 TOML 发现 :

const config = createConfigFromFiles({ fileFormat: 'toml', argv: [] });
console.log(config.getNumber('http.port')); // 4001

在解析后适用相同的环境、合并、指令和计划规则. 必须引用TOML日期,引用不安全的整数,以及 { "$null" = true } 清除继承的值。 见 TOML 指南 财务报告和审定财务报表 可运行的示例。 。 。 .

装入顺序和合并

自动发现合并了以下文件,以后的值优先 :

与 fileFormat: 'toml',同样的四个发现层 .toml 换句话说.

目录来自 basePath,则 CONFIG_DIR,则 process.cwd()。 。 。 . 环境来自 envName,则 CONFIG_ENV,则 NODE_ENV,则 development。这些名称和 config 文件名前缀可配置 .

对象递归合并;数组和平面取代更早的值. null 清除一个值,同时 undefined 无法推翻它。 缺少发现层 是可选的。 丢失的显性文件也默认被跳过; 启用 strictFiles: true 要求他们。 见 文件加载。 。 。 .

环境覆盖和占位符

一个明确的环境图使这个例子独立于 shell 语法:

import { loadConfigObjectFromFiles } from '@gaia-framework/config';

const config = loadConfigObjectFromFiles({
  argv: [],
  inheritProcessEnv: false,
  env: {
    CONFIG: '{"http":{"host":"example.test","port":4001}}',
    CONFIG_http_port: '5000'
  }
});

console.log(config.http.port); // 5000
console.log(config.http.host); // example.test

CONFIG 一定是JSON的对象 每键值尽可能被解析为JSON, 数字、布尔、数组、对象和 null 能够覆盖文件值. 名称对大小写敏感: CONFIG_http_port 目标 http.port, (中文(简体) ), __ 编码 字形下划线,以及 ___ 编码连字符.

在YAML内部, ${NAME} 需要非空变量; ${NAME:-fallback} 用品 倒计时 $${NAME} 保留文字 ${NAME}整个占位符 带有 true 或者说 false fallback 生成布尔并验证该词汇. 数字占位符仍然是字符串,直到一个得到的或计划转换它们.

默认提供 env 地图取代用于发现和 覆盖,但占位符和 $env 仍然可以回到单个进程 变量。 设定 inheritProcessEnv: false 完全隔离。 见 环境变量 用于逃跑,空值,编码, 和确切的优先权规则.

包括和提交指令

指令是完全有一个键和一个字符串参数的对象:

label: { $env: APP_LABEL }
message: { $file: ./message.txt }
service: { $include: ./parts/service.yaml }
firstItem: { $include: "./parts/items.json#items.0" }

$env 读取所需的字符串. $file 逐字读取 UTF-8 文本. $include 解析YAML、JSON或TOML,并解决嵌入式占位符和指令。 相对 路径从包含指令的文件开始; 片段选择嵌入 对象属性或数组元素。 循环被拒绝并重复 每个装入器被缓存。 使用信任的配置文件: 指令可以读取 用于节点进程的路径.

这个 指令指南 解释碎片、错误、相对 路径和缓存寿命. 实例05 包含 所有需要的固定文件和预期结果.

Schema 验证

验证是可选的。 如果您的应用程序使用Zod,请明确安装:

yarn add zod

提供同步 Zod 计划以验证、应用默认值并转换值:

import { z } from 'zod';
import { createConfig } from '@gaia-framework/config';

const schema = z.object({
  port: z.coerce.number().int().positive(),
  enabled: z.boolean().default(true)
});
const config = createConfig({ port: '4001' }, schema);

console.log(config.getNumber('port')); // 4001
console.log(config.getBoolean('enabled')); // true

Zod 是此寄存器的开发依赖, 而不是运行时间或同行依赖 图书馆。 应用程序选择自己的 Zod 版本; 自定义同步 策略可以执行导出 ConfigSchema<T> 界面。 对于文件, 通过 schema 到文件厂;在装入、解析、合并后运行,以及 环境覆盖. loadConfigLayersFromFiles(options) 返回生层 即使选项中存在一个.

没有提供的计划,就没有具体的计划验证或应用程序 默认 。 验证失败 。 Async schemas是不支持的. 见 鉴定和设计。 。 。 .

阅读器、服务和打入器

createConfig 财务报告和审定财务报表 createConfigFromFiles 返回 a ConfigReader。 。 。 . createConfigService 财务报告和审定财务报表 createConfigServiceFromFiles 返回 a ConfigService 具有相同的获取界面.

缺少需要的获取器投掷或 null 值和输入的获取器拒绝 无效的值 。 可选获取器返回 undefined 失踪/null 数值; 可选的已键获取器也返回 undefined 用于普通类型不匹配. 默认数字转换跟随 JavaScript Number;布尔获取器接受 true/false, (中文(简体) ), 1/0, (中文(简体) ), yes/no,以及 on/off 字符串不修剪白空间. 在需要更窄的转换时使用严格的获取器.

每一个得到和 has(path) 接受点字符串或字段数组. 譬如说, getString(['literal.name']) 读取单个点化属性,同时 getString('literal.name') 穿行有二个属性. 数字段访问数组 要素. keys() 列出捕获到的点形密钥; keyPaths() 返回防御状态 复制清晰的线段数组。 花序为盘点时的叶片.

普通的获取类型是断言,而不是计划引出路径或运行时间 审定。 见 API 参考 每个导出、 选项、 默认, 和错误合同.

缓存和选择性更严格的行为

createConfigServiceFromFiles 用于同等装载选项的再利用服务, 环境快照 和计划特征. 仅更改文件内容 不使缓存无效. 过 cache: false 每次读取新文件. createConfigFromFiles 而对象加载功能不重复使用服务. 重新使用 a ConfigLoader 也包括缓存; 构造新的加载器 包括新鲜的.

读者缓存查找并获取其在构建时的关键索引. 照顾他们 数据在构建后保持稳定。 默认值可以共享可变对象/阵列 参考资料; immutable: true 反而制造出一个脱开的 深冻的快照 经计划处理后支持的纯数据.

严格检查、安全错误和不可改变的快照默认被禁用; 启用环境继承和文件服务缓存。 档案厂拿 这些选项直接。 记忆工厂把读者选择作为第三个 参数,在可选方案之后。 见 API 参考 选择位置, 严格的获取器, (中文(简体) ), 安全错误,以及 快照。 。 。 . 这个 装入指南 覆盖解析深度和缓存寿命 .

使融合无效

安装 inversify 财务报告和审定财务报表 reflect-metadata 在应用程序中绑定读取器 明确构建普通服务:

import 'reflect-metadata';
import { Container } from 'inversify';
import { ConfigReader, ConfigService } from '@gaia-framework/config';

const container = new Container();
container.bind(ConfigReader).toConstantValue(new ConfigReader({ port: 4001 }));
container.bind(ConfigService).toDynamicValue((context) =>
  new ConfigService(context.get(ConfigReader))
);

console.log(container.get(ConfigService).getNumber('port')); // 4001

声明 inversify 财务报告和审定财务报表 reflect-metadata 在导入它们的应用程序中. 在装饰类前初始化元数据; 使用 TypeScript 应用程序 装饰者应当保留相应的编译器设置. 见 鉴定和设计 编辑 可运行的 DI 实例。 。 。 .

文件和实例

对于完整的应用程序示例,请从 分层服务 或者说 模块化加工管道。每个都有一个匹配 TOML 版本具有相同的解析值并拥有库拥有的合成子图.

使用 基准 生成您自己的计时表 工作量。 结果属于被忽略的文物或CI文物;不是 (c) 实施每台机器的快照或普遍履约保证.

发展和核查

使用节点 24 从寄存器根运行下面的命令 。 跟着 安装步骤 将制作 yarn ,然后确认 yarn --version 报告 4.12.0 在退票内.

维护实例、工具、测试和配置使用 .ts 来源. 运行示例 直接与节点 24 (node index.ts (从他们的文献目录中)。 类型检查 覆盖实例和工具; 独立的软件包检查也验证实例 对照已安装的申报并执行编译的 JavaScript 消费者固定装置.

CI 运行 Windows 和 Linux 上的全部验证和基准烟雾 推动和拉取请求,包括没有PR的特征分支. 特性推 当 PRCI 已经覆盖同一承诺时, 跳过重复验证 。 主推车 运行共享检查通过 publish.yml即使没有版本起伏. 新更新取消已取代的功能分支或 PR 运行; 主承诺保留其 自行审定和发放批准. 包接收比较 npm/ Yarn 存档内容, 验证许可证, 检查 汇编进口和申报,进行发展出口和开发,以及 运行出账外的示例。 测试使用合成数据和一次性数据 文档。 覆盖范围写给 coverage/; 向 artifacts/。 。 。 . 见 捐款 编辑 更改日志。 。 。 .

释放

合并高点 package.json 版本为 main 于 Linux/ Windows 验证并需要维护者批准. 工作流程发布 到 npm, 验证已安装的软件包, 然后创建匹配的 GitHub 释放 带有生成的注释和已验证的归档。 其他合并只运行验证 . 手动干燥和回收仍然可用。 叉可以验证但不能 继承出版权限。 见 发布指南。 。 。 .

许可证

麻省理工学院 (原始内容存档于2026 Gaia-框架). 属地保留自己的许可证.