首页　>　文章列表　>　使用不可构造类型的 TypeScript 中的丰富编译时异常

使用不可构造类型的 TypeScript 中的丰富编译时异常

353 2025-02-19

typescript 的类型系统很强大，但它的错误消息有时可能很神秘且难以理解。在本文中，我们将探索一种使用不可构造类型来创建清晰的、描述性的编译时异常的模式。这种方法通过使无效状态无法用有用的错误消息来表示来帮助防止运行时错误。

模式：具有自定义消息的不可构造类型

首先，我们来分解一下核心模式：

// create a unique symbol for our type exception
declare const typeexception: unique symbol;

// basic type definitions
type struct = record<string, any>;
type funct<t, r> = (arg: t) => r;
type types<t> = keyof t & string;
type sanitize<t> = t extends string ? t : never;

// the core pattern for type-level exceptions
export type unbox<t extends struct> = {
    [type in types<t>]: t[type] extends funct<any, infer ret>
        ? (arg: ret) => any
        : t[type] extends struct
        ? {
              [typeexception]: `variant <${sanitize<type>}> is of type <union>. migrate logic to <none> variant to capture <${sanitize<type>}> types.`;
          }
        : (value: t[type]) => any;
};

它是如何运作的

typeexception 是一个独特的符号，充当我们错误消息的特殊键
当我们遇到无效类型状态时，我们返回一个带有 typeexception 属性的对象类型
此类型在运行时不可构造，迫使 typescript 显示我们的自定义错误消息
错误消息可以包含使用模板文字的类型信息

示例 1：带有自定义错误的变体处理

以下示例展示了如何将此模式与变体类型一起使用：

type datavariant = 
    | { type: 'text'; content: string }
    | { type: 'number'; value: number }
    | { type: 'complex'; nested: { data: string } };

type varianthandler = unbox<{
    text: (content: string) => void;
    number: (value: number) => void;
    complex: { // this will trigger our custom error
        [typeexception]: `variant <complex> is of type <union>. migrate logic to <none> variant to capture <complex> types.`
    };
}>;

// this will show our custom error at compile time
const invalidhandler: varianthandler = {
    text: (content) => console.log(content),
    number: (value) => console.log(value),
    complex: (nested) => console.log(nested) // error: type has unconstructable signature
};

示例 2：递归类型验证

这是一个更复杂的示例，展示了如何将模式与递归类型一起使用：

type treenode<t> = {
    value: t;
    children?: treenode<t>[];
};

type treehandler<t> = unbox<{
    leaf: (value: t) => void;
    node: treenode<t> extends struct
        ? {
              [typeexception]: `cannot directly handle node type. use leaf handler for individual values.`;
          }
        : never;
}>;

// usage example - will show custom error
const invalidtreehandler: treehandler<string> = {
    leaf: (value) => console.log(value),
    node: (node) => console.log(node) // error: cannot directly handle node type
};

示例 3：类型状态验证

以下是我们如何使用该模式来强制执行有效的类型状态转换：

type loadingstate<t> = {
    idle: null;
    loading: null;
    error: error;
    success: t;
};

type statehandler<t> = unbox<{
    idle: () => void;
    loading: () => void;
    error: (error: error) => void;
    success: (data: t) => void;
    // prevent direct access to state object
    state: loadingstate<t> extends struct
        ? {
              [typeexception]: `cannot access state directly. use individual handlers for each state.`;
          }
        : never;
}>;

// this will trigger our custom error
const invalidstatehandler: statehandler<string> = {
    idle: () => {},
    loading: () => {},
    error: (e) => console.error(e),
    success: (data) => console.log(data),
    state: (state) => {} // error: cannot access state directly
};

何时使用此模式

此模式在以下情况下特别有用：

您需要在编译时阻止某些类型组合
您希望针对类型违规提供清晰的描述性错误消息
您正在构建复杂的类型层次结构，其中某些操作应受到限制
您需要通过有用的错误消息引导开发人员采用正确的使用模式

技术细节

让我们分解一下该模式的内部工作原理：

// The [TypeException] property creates an unconstructable type because:
// 1. The symbol cannot be constructed at runtime
// 2. The property is a template literal type containing useful information
// 3. TypeScript will try to unify this type with any attempted implementation

// When you try to implement a type with TypeException:
type Invalid = {
    [TypeException]: string;
};

// TypeScript cannot create a value matching this type because:
// - The TypeException symbol is not constructable
// - The property type is a literal template that cannot be satisfied
const invalid: Invalid = {
    // No possible implementation can satisfy this type
};