Rich Compile-Time Exceptions in TypeScript Using Unconstructable Types

TypeScript's type system is powerful, but its error messages can sometimes be cryptic and hard to understand. In this article, we'll explore a pattern that uses unconstructable types to create clear, descriptive compile-time exceptions. This approach helps prevent runtime errors by making invalid states unrepresentable with helpful error messages.

The Pattern: Unconstructable Types with Custom Messages

First, let's break down the core pattern:

// 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;
};

How It Works

1. TypeException is a unique symbol that acts as a special key for our error messages
2. When we encounter an invalid type state, we return an object type with a TypeException property
3. This type is unconstructable at runtime, forcing TypeScript to show our custom error message
4. The error message can include type information using template literals

Example 1: Variant Handling with Custom Errors

Here's an example showing how to use this pattern with variant types:

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
};

Example 2: Recursive Type Validation

Here's a more complex example showing how to use the pattern with recursive types:

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
};

Example 3: Type State Validation

Here's how we can use the pattern to enforce valid type state transitions:

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
};

When to Use This Pattern

This pattern is particularly useful when:

1. You need to prevent certain type combinations at compile time
2. You want to provide clear, descriptive error messages for type violations
3. You're building complex type hierarchies where certain operations should be restricted
4. You need to guide developers toward correct usage patterns with helpful error messages

Technical Details

Let's break down how the pattern works internally:

// 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
};

Benefits Over Traditional Approaches

1. Clear Error Messages: Instead of TypeScript's default type errors, you get custom messages that explain exactly what went wrong
2. Compile-Time Safety: All errors are caught during development, not at runtime
3. Self-Documenting: Error messages can include instructions on how to fix the issue
4. Type-Safe: Maintains full type safety while providing better developer experience
5. Zero Runtime Cost: All checking happens at compile time with no runtime overhead

Conclusion

Using unconstructable types with custom error messages is a powerful pattern for creating self-documenting type constraints. It leverages TypeScript's type system to provide clear guidance at compile time, helping developers catch and fix issues before they become runtime problems.

This pattern is particularly valuable when building complex type systems where certain combinations should be invalid. By making invalid states unrepresentable and providing clear error messages, we can create more maintainable and developer-friendly TypeScript code.

Comments

[Boopathi]

This is a great approach to catching errors early in the development process! I especially like how the custom error messages provide specific guidance on how to fix the issue. This will definitely make my TypeScript code more robust and easier to maintain.

[Ja]

😊😁😉 Just passing some things that have helped me in my typescript adventures. Nothing worse than being knee deep in a custom api, and you forget why you modeled things the way you have. 😅 It would be funny if it didnt happen so frequently. So I came up with this technique to future proof myself, and I havent looked back.

In any case. I'm glad you found the tip valuable... more to come!