TypeScript中遍历带品牌化Key的Record时如何保留键类型信息？

问题背景 #

给定一个Record<Key, Value>类型，其中Key是品牌化字符串类型，遍历该对象时键的品牌类型信息会丢失，如何在不使用类型断言（避免失去品牌化类型意义）的前提下解决这个问题？

我有如下JSON结构：

{
  "elements": {
    "key1": "value1",
    "key2": "value2"
  }
}

希望通过JSON.parse()将其反序列化为以下类型：

type Key = string & { _brand: 'Key' }

interface Config {
  elements: Record<Key, string>
}

这么做是因为JSON结构复杂，包含大量不同键，需要通过品牌化类型区分它们。但使用Object.entries遍历时，键的类型会退化为普通string：

Object.entries(config.elements).forEach(([key, value]) => { 
  // key仅为string类型，而非Key品牌化类型
})

解决方案 #

问题根源在于TypeScript内置的Object.entries类型定义会将对象键统一转为string，忽略原始的品牌化类型。以下是两种无需在业务代码中做类型断言的解决方式：

1. 自定义品牌化键的entries函数

封装一个泛型函数，专门处理Record<K, V>类型，确保返回的键保留原始品牌化类型：

type Key = string & { _brand: 'Key' };

interface Config {
  elements: Record<Key, string>;
}

// 自定义entries函数，保留品牌化键类型
function brandedEntries<K extends string & {}, V>(obj: Record<K, V>): [K, V][] {
  // 内部仅做一次类型断言，封装后外部无需重复操作
  return Object.entries(obj) as [K, V][];
}

// 解析JSON（此处类型断言用于告知TS解析结果符合Config类型，属于必要的类型声明）
const config: Config = JSON.parse(`{
  "elements": {
    "key1": "value1",
    "key2": "value2"
  }
}`) as Config;

// 使用自定义函数遍历，key自动保留Key类型
brandedEntries(config.elements).forEach(([key, value]) => {
  console.log(key, value); // key类型为Key（string & { _brand: 'Key' }）
});

这种方式将类型断言封装在工具函数内部，业务代码中无需再做断言，同时保证了类型安全——因为我们明确知道传入的是Record<K, V>，所以Object.entries的结果可以安全转换为[K, V][]。

2. 使用类型守卫配合Object.keys

如果需要对键做运行时合法性校验，可以结合类型守卫函数：

type Key = string & { _brand: 'Key' };

interface Config {
  elements: Record<Key, string>;
}

// 类型守卫函数：校验字符串是否符合Key规则（可根据实际需求添加逻辑）
function isKey(str: string): str is Key {
  // 示例：假设所有以"key"开头的字符串都是合法Key
  return str.startsWith('key');
}

const config: Config = JSON.parse(`{
  "elements": {
    "key1": "value1",
    "key2": "value2"
  }
}`) as Config;

// 遍历前通过类型守卫断言键的类型
Object.keys(config.elements).forEach((rawKey) => {
  if (isKey(rawKey)) {
    // 此处rawKey的类型自动转为Key
    const value = config.elements[rawKey];
    console.log(rawKey, value);
  }
});

这种方式适合需要在运行时验证键合法性的场景，同时保留品牌化类型信息。

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