如何在保留数组类型支持的同时从约束数组提取枚举类型？

问题描述 #

简化示例场景 #

我需要从数组中提取属性值作为枚举类型，同时严格保留数组的类型约束。但目前遇到的问题是：一旦给数组加上类型注解（比如:ElemProp[]），TypeScript就只能推导出宽泛的number类型，无法得到具体的字面量联合类型。示例代码如下：

type ElemProp = {id: number, name: string, quickFormat?: boolean }

const formatList:ElemProp[] = [
    {id:1, name: 'ABC'},
    {id: 3, name: 'XYZ'},
    {id: 98, name: 'GOGOGO', quickFormat: true}
] as const

type IdEnum = (typeof formatList)[number]['id'] // 类型为number，而非预期的1|3|98

如果移除:ElemProp[]注解，虽然能得到正确的1|3|98联合类型，但数组会失去ElemProp的类型校验，不符合需求。试过改用只读数组、保留as const等操作，只要存在类型约束，就无法推导出具体字面量。

实际业务场景（docx库生成文档） #

在Node.js中使用docx库生成文档时，需要限制段落可使用的样式ID类型。当前已有初步实现，但需要优化。相关代码如下：

import dx from 'docx';
import { IPropertiesOptions } from 'docx/build/file/core-properties';

type StylesAndNumberings = Required<Pick<IPropertiesOptions, 'styles' | 'numbering'>>; // 仅作参考

export type ExtractParagraphIds<U extends Partial<IPropertiesOptions>> = U extends {
    readonly styles: { readonly paragraphStyles: infer U extends readonly { id: string }[] };
}
    ? U[number]['id']
    : never;

const docProps = {
  styles: {
    paragraphStyles: [
      {
        id: 'normal',
        name: 'Normal',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: {
          font: 'Arial',
          size: 22,
        },
      }]
  }
} as const satisfies Partial<IPropertiesOptions>;

type IdEnum = ExtractParagraphIds<typeof docProps>;

export const textToParagraph = <T extends Partial<IPropertiesOptions>>(
    t: string,
    runFormat: dx.IRunOptions = {},
    paragraphOptions: dx.IParagraphOptions & { style?: ExtractParagraphIds<T> } = {},
    paragraphFreeChildren: dx.IParagraphOptions['children'] = []
) => {
    const text = t.split('\n');
    if (text.length === 1) {
        return new dx.Paragraph({
            wordWrap: true,
            children: [
                new dx.TextRun({
                    text: t,
                    ...runFormat,
                }),
                ...paragraphFreeChildren,
            ],
            ...paragraphOptions,
        });
    }
    return new dx.Paragraph({
        children: [
            ...text.map((line, i) => {
                return new dx.TextRun({
                    text: line,
                    ...runFormat,
                    break: i ? 1 : 0,
                });
            }),
            ...paragraphFreeChildren,
        ],
        ...paragraphOptions,
    });
};

解决方案 #

针对简化示例的解决方法 #

核心是避免直接用类型注解覆盖字面量推导，改用「泛型约束」或satisfies关键字（TypeScript 4.9+支持），兼顾类型校验和具体值推导：

方法1：泛型工具函数

通过泛型函数约束数组类型，同时捕获具体的字面量结构：

type ElemProp = {id: number, name: string, quickFormat?: boolean }

// 工具函数：约束数组必须符合ElemProp[]，同时保留字面量推导
const createTypedList = <T extends readonly ElemProp[]>(list: T) => list;

const formatList = createTypedList([
    {id:1, name: 'ABC'},
    {id: 3, name: 'XYZ'},
    {id: 98, name: 'GOGOGO', quickFormat: true}
] as const);

type IdEnum = (typeof formatList)[number]['id'] // 类型为1 | 3 | 98，且数组满足ElemProp[]约束

方法2：使用satisfies关键字

直接用satisfies做类型校验，不破坏字面量推导：

const formatList = [
    {id:1, name: 'ABC'},
    {id: 3, name: 'XYZ'},
    {id: 98, name: 'GOGOGO', quickFormat: true}
] as const satisfies readonly ElemProp[];

type IdEnum = (typeof formatList)[number]['id'] // 同样得到1 | 3 | 98

针对docx业务场景的优化 #

你的代码已经用到了satisfies，可以进一步优化类型提取逻辑和函数泛型，让样式ID的推导更严谨：

import dx from 'docx';
import { IPropertiesOptions } from 'docx/build/file/core-properties';

// 优化提取类型：确保paragraphStyles是带id的只读数组
export type ExtractParagraphIds<U extends Partial<IPropertiesOptions>> = 
  U extends {
    styles: {
      paragraphStyles: readonly (infer P extends { id: string })[];
    };
  } ? P['id'] : never;

// 保留类型校验和字面量推导，支持多样式ID
const docProps = {
  styles: {
    paragraphStyles: [
      {
        id: 'normal',
        name: 'Normal',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: {
          font: 'Arial',
          size: 22,
        },
      },
      {
        id: 'heading1',
        name: 'Heading 1',
        basedOn: 'Normal',
        next: 'Normal',
        run: {
          font: 'Arial',
          size: 32,
          bold: true,
        },
      }
    ] as const
  }
} as const satisfies Partial<IPropertiesOptions>;

type ParagraphStyleIds = ExtractParagraphIds<typeof docProps>; // 类型为'normal' | 'heading1'

// 函数泛型保持不变，调用时会自动推导合法的样式ID
export const textToParagraph = <T extends Partial<IPropertiesOptions>>(
    t: string,
    runFormat: dx.IRunOptions = {},
    paragraphOptions: dx.IParagraphOptions & { style?: ExtractParagraphIds<T> } = {},
    paragraphFreeChildren: dx.IParagraphOptions['children'] = []
) => {
    const text = t.split('\n');
    if (text.length === 1) {
        return new dx.Paragraph({
            wordWrap: true,
            children: [
                new dx.TextRun({
                    text: t,
                    ...runFormat,
                }),
                ...paragraphFreeChildren,
            ],
            ...paragraphOptions,
        });
    }
    return new dx.Paragraph({
        children: [
            ...text.map((line, i) => {
                return new dx.TextRun({
                    text: line,
                    ...runFormat,
                    break: i ? 1 : 0,
                });
            }),
            ...paragraphFreeChildren,
        ],
        ...paragraphOptions,
    });
};

// 使用示例：style只能传'normal'或'heading1'，否则报错
textToParagraph('Hello', {}, { style: 'normal' }); // 合法
textToParagraph('Hello', {}, { style: 'invalid' }); // 类型错误

关键原理 #

直接的类型注解（如:ElemProp[]）会强制TypeScript将数组类型窄化为宽泛的集合类型，丢失字面量细节；而泛型约束或satisfies关键字能在不破坏字面量推导的前提下完成类型校验，同时保留提取具体属性值联合类型的能力。

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