TypeScript如何强制仅赋值真实Node实例而非形状匹配对象？

一、让TypeScript仅接受真实Node实例（拒绝形状匹配的普通对象） #

TypeScript默认采用结构类型系统，只要对象的属性/方法匹配就会被认为符合类型，这导致普通对象能伪装成Node类型。要解决这个问题，需要创建标称类型（Nominal Type），给真实Node实例添加唯一的类型标记，同时配合运行时验证：

1. 定义标称类型 #

// 给Node添加唯一的品牌属性，区分普通对象和真实实例
type RealNode = Node & { __brand: 'RealNode' };

2. 实现类型守卫函数（运行时验证） #

// 验证值是否为真实DOM Node实例
function isRealNode(value: unknown): value is RealNode {
  return typeof value === 'object' && value !== null && value instanceof Node;
}

3. 使用标称类型替代原有Node类型 #

// 正确赋值：真实Node实例，通过类型断言转换为RealNode
let nodeInstance: RealNode = document.createTextNode('Hello World!') as RealNode;

// 错误赋值：普通对象无法匹配RealNode类型，TypeScript直接报错
nodeInstance = {
  addEventListener(type, callback, options) {}
};

原理：标称类型通过__brand属性让普通对象无法在类型层面匹配，运行时的instanceof Node检查则确保值是真实的DOM实例。

二、修复elementFactory中的Node与配置对象类型混淆 #

原有代码中ElementConfig | Node的联合类型导致类型模糊，通过函数重载和类型守卫可以明确区分参数类型，避免混用：

1. 明确配置对象类型 #

先完善HTMLElementConfig类型，确保和createElement的配置逻辑对齐：

type HTMLElementConfig<T extends keyof HTMLElementTagNameMap> = Partial<
  Pick<HTMLElementTagNameMap[T], 'className' | 'id' | 'style'> & {
    attributes?: Record<string, string>;
    html?: string;
    text?: string;
    fallbackSrc?: string;
  }
>;

2. 修改elementFactory，使用函数重载 #

通过重载明确三种参数场景，让TypeScript严格检查输入类型：

function elementFactory<TagName extends keyof HTMLElementTagNameMap>(tagName: TagName) {
  // 函数重载：明确不同参数组合的类型
  return function(
    config: HTMLElementConfig<TagName>,
    ...additionalNodes: RealNode[]
  ): HTMLElementTagNameMap[TagName];
  return function(
    selector: `.${string}` | `#${string}` | `[${string}`,
    ...additionalNodes: RealNode[]
  ): HTMLElementTagNameMap[TagName];
  return function(
    node: RealNode,
    ...additionalNodes: RealNode[]
  ): HTMLElementTagNameMap[TagName];
  
  // 实际实现函数
  return function(
    configOrNode?: HTMLElementConfig<TagName> | `.${string}` | `#${string}` | `[${string}` | RealNode,
    ...additionalNodes: RealNode[]
  ): HTMLElementTagNameMap[TagName] {
    let cssSelector = '';
    let config: HTMLElementConfig<TagName> | undefined;
    let initialNode: RealNode | undefined;

    // 通过类型守卫和类型判断区分参数类型
    if (typeof configOrNode === 'string') {
      cssSelector = configOrNode;
    } else if (isRealNode(configOrNode)) {
      initialNode = configOrNode;
    } else if (typeof configOrNode === 'object' && configOrNode !== null) {
      config = configOrNode;
    }

    const element = createElement(`${tagName}${cssSelector}`, config);
    const childNodes = [...(initialNode ? [initialNode] : []), ...additionalNodes];
    element.append(...childNodes);

    return element;
  };
}

3. 优化createElement的类型定义 #

让createElement的类型和HTMLElementConfig对齐，避免any类型：

function createElement<TagName extends keyof HTMLElementTagNameMap>(
  descriptor: TagName | string,
  config?: HTMLElementConfig<TagName>
): HTMLElementTagNameMap[TagName];
function createElement(descriptor: string, config?: any): HTMLElement {
  // 原函数实现保持不变
}

这样修改后，elementFactory会严格区分：

• 配置对象（仅接受定义好的属性）
• CSS选择器字符串（仅匹配.class/#id/[attr]格式）
• RealNode实例（仅接受真实DOM节点）

总结 #

• 用标称类型+类型守卫实现真实Node实例的类型约束，拒绝形状匹配的普通对象
• 用函数重载明确elementFactory的参数类型，彻底解决Node与配置对象的类型混淆问题
• 运行时验证确保类型安全，同时保留TypeScript的静态类型检查能力

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