@ cluvercloud/ reglage (英语)

Schema 驱动配置库 佐德语Name。定义您的选项一次,然后从任何来源获得验证、类型安全配置.

使用量

import { createConfigBuilder } from '@clevercloud/reglage';
import { z } from 'zod';

const builder = createConfigBuilder({
  API_URL: {
    schema: z.url().default('https://api.example.com'),
    documentation: 'The API base URL',
  },
  PORT: {
    schema: z.number().default(8080),
    tags: ['server'],
    documentation: 'Port to listen on',
  },
  SECRET: {
    schema: z.string().min(1),
    secret: true,
    documentation: 'A required secret',
  },
});

builder.addSource('defaults', { PORT: '3000' });
builder.addSource('env', process.env);

const config = builder.buildConfig(); // throws InvalidConfigError on validation failure

config.get('API_URL'); // string
config.get('PORT'); // number
config.getAll('server'); // { PORT: number }

API 密码

createConfigBuilder(schema)

创建一个 ConfigBuilder 从一个计划记录。 每个关键地图到一个 OptionDef数字 :

ConfigBuilder

addSource(name, values)

注册一个已命名的密钥/值源(例如:. "env", (中文(简体) ), "file") (中文(简体) ). 源被按顺序合并——后源为同一密钥而凌驾于前源. 计划中没有的密钥被默默地忽略了.

buildConfig()

将所有源合并,并验证每个值与计划相对应。 回返a Config 实例或扔出 InvalidConfigError。 。 。 .

refine(key, fn)

为给定的密钥添加跨字段验证规则。 回调接收了原Zod schema和所有已解析的配置值,必须返回一个Zod schema以验证字段对齐. 多重改进可以注册(即使是在同一键上). 在所有栏目被单独验证后运行.

// Make SECRET required when FEATURE_X is enabled
builder.refine('SECRET', (schema, resolved) => {
  if (resolved.FEATURE_X) return z.string().min(1);
  return schema;
});

// Restrict PORT in production
builder.refine('PORT', (schema, resolved) => {
  if (resolved.MODE === 'production') {
    return schema.refine((v) => v >= 1024, { message: 'Must be >= 1024 in production' });
  }
  return schema;
});

Config

get(key)

返回单个密钥的解析值.

getAll(tag?)

返回所有已解析的值。 何时 tag 中仅包含标有该值的选项.

getSource(key)

返回为密钥提供中值的来源名称(例如:. "env", (中文(简体) ), "file"),或 "default" 如果值来自 Zod 计划默认值.

getSourceHistory(key)

返回单个密钥的全部覆盖历史, 命令从最早( schema 默认值) 到最近( 赢取源) 。 每个条目都是 SourceHistoryEntry数字 :

interface SourceHistoryEntry {
  source: string;
  rawValue: unknown;
  resolvedValue?: unknown; // only set on the last (winning) entry
}

builder.addSource('file', { PORT: 3000 });
builder.addSource('env', { PORT: '8080' });
const config = builder.buildConfig();

config.getSourceHistory('PORT');
// [
//   { source: 'default', rawValue: 80 },
//   { source: 'file', rawValue: 3000 },
//   { source: 'env', rawValue: '8080', resolvedValue: 8080 }
// ]

getAllSourceHistory()

返回所有密钥的全部历史, 作为绘制每个密钥的对象 SourceHistoryEntry[]。 。 。 .

toString(format?)

返回所有配置值的可读字符串。 隐藏秘密值 ******键按字母顺序排列.

• "simple" (默认)——每键一行有中选来源:

  API_URL="https://api.example.com" (env)
  PORT=8080 (env)
  SECRET=****** (env)
  

• "chain" – 每个键有完整源链的一行:

  API_URL="https://api.example.com" (default -> env)
  PORT=8080 (default -> file -> env)
  SECRET=****** (env)
  

• "verbose" —— 多行输出, 显示每个源的原始值 <-- active 在中标条目上标记 :

  API_URL="https://api.example.com" (env)
    default -> "https://default.example.com"
    env     -> "https://api.example.com"  <-- active
  PORT=8080 (env)
    default -> 80
    file    -> 3000
    env     -> "8080"  <-- active
  SECRET=****** (env)
    default -> ******
    env     -> ******  <-- active
  

InvalidConfigError

验证失败时抛出 。 显示 a issues 数组 ConfigIssue 对象 :

interface ConfigIssue {
  key: string;
  source: string | undefined;
  message: string;
}