TypeScript 中利用泛型实现对象属性的动态匹配与类型安全

// 初始的类型定义
export type OrderGrid = Array<string | [string, string]>;

export type OrderedProperties = {
  props: string[];
  order: OrderGrid;
};

// 示例用法
const a: OrderedProperties = {
  props: ['title', 'firstName', 'lastName', 'nickName'],
  order: [
    'title',
    ['firstName', 'lastName'],
    'nickName'
  ]
};

const invalidExample: OrderedProperties = {
  props: ['title', 'firstName'],
  order: [
    'title',
    'nonExistentProperty' // TypeScript 不会报错，因为 'nonExistentProperty' 仍然是 string 类型
  ]
};

/**
 * 定义 OrderGrid 类型，其中 S 约束了数组中允许的字符串字面量。
 * S 必须是 extends string，表示 S 是一个或多个字符串字面量的联合类型。
 */
type OrderGrid<S extends string> = Array<S | [S, S]>;

/**
 * 定义 OrderedProperties 类型，使用泛型 P 和 O。
 * P: 表示 props 数组中允许的所有属性名（字符串字面量联合类型）。
 * O: 表示 order 数组中允许的属性名，它必须是 P 的子集或相同类型。
 *    默认值 O = P 使得在不显式指定 O 时，order 元素与 props 元素完全匹配。
 */
type OrderedProperties<P extends string, O extends P = P> = {
  props: P[];
  order: OrderGrid<O>;
};

// 正确示例：所有 order 中的属性都在泛型 P 中声明
const a: OrderedProperties<"firstName" | "lastName" | "nickName" | "title"> = {
  props: ["title", "firstName", "lastName", "nickName"],
  order: [
    "title",
    ["firstName", "lastName"],
    "nickName",
  ],
}; // TypeScript 编译通过

// 错误示例：order 中包含未在泛型 P 中声明的属性
const a2: OrderedProperties<"firstName" | "lastName" | "nickName"> = {
  props: ["title", "firstName", "lastName", "nickName"], /* 错误:
          ~~~~~~~
  类型 '"title"' 不可分配给类型 '"firstName" | "lastName" | "nickName"'。(2322)
  */
  order: [
    "title", /* 错误:
    ~~~~~~~
    类型 '"title"' 不可分配给类型 '"firstName" | "lastName" | "nickName" | ["firstName" | "lastName" | "nickName", "firstName" | "lastName" | "nickName"]'。(2322)
    */
    ["firstName", "lastName"],
    "nickName",
  ],
};

/**
 * 处理 OrderedProperties 对象的函数。
 * P 和 O 的泛型约束使得 TypeScript 能够自动推断出 props 和 order 中允许的属性。
 */
declare function handleOrderedProps<P extends string, O extends P = P>(
  props: OrderedProperties<P, O>,
): void;

// 示例：正确的使用方式，TypeScript 自动推断 P 和 O
handleOrderedProps({
  props: ["title", "firstName", "lastName", "nickName"],
  order: [
    "title",
    ["firstName", "lastName"],
    "nickName",
  ],
}); // 编译通过

// 示例：order 中缺少 props 中的属性是允许的
handleOrderedProps({
  props: ["title", "firstName", "lastName", "nickName"],
  order: [
    "title",
    ["firstName", "lastName"],
  ],
}); // 编译通过，因为 'nickName' 未在 order 中出现是合法的，但 order 中的元素必须在 props 中

// 示例：order 中包含未在 props 中声明的属性，TypeScript 报错
handleOrderedProps({
  props: ["title", "firstName", "lastName"],
  order: [
    "title",
    ["firstName", "lastName"],
    "nickName", /* 错误:
    ~~~~~~~~~~
    类型 '"nickName"' 不可分配给类型 '"firstName" | "lastName" | "title" | ["firstName" | "lastName" | "title", "firstName" | "lastName" | "title"]'。(2322)
    */
  ],
});

/**
 * 从 OrderGrid 中提取所有唯一的属性名。
 * @param order 遵循 OrderGrid 类型的属性排列数组。
 * @returns 包含所有唯一属性名的数组。
 */
function getPropsFromOrder<S extends string>(order: OrderGrid<S>): S[] {
  // 使用 flat() 扁平化数组，然后通过 Set 过滤出唯一的属性名
  return Array.from(new Set(order.flat())) as S[];
}

// 示例用法
const myOrder: OrderGrid<"propA" | "propB"> = [
  "propA",
  ["propA", "propB"]
];
const derivedProps = getPropsFromOrder(myOrder);
console.log(derivedProps); // 输出: ["propA", "propB"]