如何基于给定Schema实现Nconf输出的TypeScript类型安全？

nconf是一款能将环境变量转换为对象的配置库，现有执行命令与代码示例如下：

MYFOO_BAR_BAZ=true MYFOO_BAR_COUNT=34 MYFOO_REALLY_KABOOM=9000 tsx ./main.ts

// main.ts
import { options } from './options.ts';

console.log(options);

// options.ts
import * as nconf from 'nconf';
import home from 'user-home';

const KEY = 'MYFOO';
const ENV_SEPARATOR = `_`;
const ENV_PATTERN = new RegExp(`/^${KEY.toUpperCase()}${ENV_SEPARATOR}/`);
const RC_NAME = `.${KEY}rc.json`;

nconf.env({
  separator: ENV_SEPARATOR,
  match: ENV_PATTERN,
  lowerCase: true,
  parseValues: true,
  transform(obj: Record<string, string>) {
    obj.key.replace(ENV_PATTERN, '').toLowerCase();
    return obj;
  },
});

export const options = nconf.get()

执行后得到的对象结构：

{
  bar: {
    baz: true,
    count: 34,
  },
  really: {
    kaboom: 9000
  }
}

现有描述环境变量的Schema：

type Config = {
  BAR_BAZ: boolean;
  BAR_COUNT: number;
  REALLY_KABOOM: number;
}

需求 #

让nconf的输出具备类型安全性：比如在以下代码中，将options.bar.count（数字类型）传给要求布尔类型的somethingElseUseful时，TypeScript能主动抛出类型错误。

import { options } from './options.ts';

function somethingElseUseful(yesno: boolean) {
  // ... 业务逻辑
}

export function usefulFunction() {
  return somethingElseUseful(options.bar.count)  // 此处应触发TypeScript类型错误
}

解决方案：利用TypeScript模板字面量类型 #

通过模板字面量类型，我们可以把扁平的Config类型转换为和nconf输出一致的嵌套结构，同时保留原始字段的类型信息，为options添加准确的类型注解。

步骤1：定义类型转换工具 #

创建递归类型，将下划线分隔的键转换为嵌套对象结构：

type NestedConfig<T extends Record<string, any>> = {
  [K in keyof T as K extends `${infer P}_${infer Rest}` 
    ? Lowercase<P> 
    : Lowercase<K>]: K extends `${infer P}_${infer Rest}`
      ? NestedConfig<{ [R in Rest]: T[K] }>
      : T[K]
};

这个类型会：

• 自动拆分下划线分隔的键为前缀和剩余部分
• 将前缀转为小写，作为嵌套对象的键
• 递归处理剩余部分，支持任意深度的嵌套
• 完整保留原始字段的类型

步骤2：为options添加类型注解 #

修改options.ts，添加类型转换并修正原代码中的两处问题（正则表达式冗余斜杠、transform函数未赋值修改结果）：

// options.ts
import * as nconf from 'nconf';
import home from 'user-home';

const KEY = 'MYFOO';
const ENV_SEPARATOR = `_`;
const ENV_PATTERN = new RegExp(`^${KEY.toUpperCase()}${ENV_SEPARATOR}`);
const RC_NAME = `.${KEY}rc.json`;

// 环境变量Schema
type Config = {
  BAR_BAZ: boolean;
  BAR_COUNT: number;
  REALLY_KABOOM: number;
}

// 转换为嵌套类型
type NestedConfig<T extends Record<string, any>> = {
  [K in keyof T as K extends `${infer P}_${infer Rest}` 
    ? Lowercase<P> 
    : Lowercase<K>]: K extends `${infer P}_${infer Rest}`
      ? NestedConfig<{ [R in Rest]: T[K] }>
      : T[K]
};

nconf.env({
  separator: ENV_SEPARATOR,
  match: ENV_PATTERN,
  lowerCase: true,
  parseValues: true,
  transform(obj: Record<string, string>) {
    obj.key = obj.key.replace(ENV_PATTERN, '').toLowerCase();
    return obj;
  },
});

// 为options指定准确的嵌套类型
export const options = nconf.get() as NestedConfig<Config>;

步骤3：验证类型安全 #

现在在业务代码中，只要出现类型不匹配的情况，TypeScript会立即抛出错误：

import { options } from './options.ts';

function somethingElseUseful(yesno: boolean) {
  // ... 业务逻辑
}

export function usefulFunction() {
  return somethingElseUseful(options.bar.count) 
  // TypeScript错误提示：类型“number”的参数不能赋给类型“boolean”的参数
}

额外说明 #

• 类型转换完全在编译时完成，不会影响运行时性能
• 支持任意深度的下划线嵌套键结构
• 修正了原代码中导致逻辑异常的两处问题

内容的提问来源于stack exchange，提问作者airtonix