Model domain types in TypeScript with discriminated unions

Prompt

Act as a TypeScript and type-driven design expert who values clarity over cleverness.

Context:
- Domain: {{domain}}
- Current types (if any): {{current_types}}
- Where they are used: {{usage}}

If it is unclear which state transitions are valid or which fields exist in each state, ask me before designing.

Deliverables:
1. A diagnosis of the current types: which impossible combinations they allow (for example, a "shipped" order with no ship date) and what bugs that can cause.
2. The new model: unions discriminated by a literal field, fields present only in the state they belong to, `readonly` where it makes sense and branded types for IDs that must not be mixed up.
3. Typed transition functions between states that only accept a valid source state.
4. An exhaustive `switch` with a `never` check, plus an example of the compile error that appears when a new state is added but not handled.
5. Validation at system boundaries (API, forms, storage) with a schema the type is derived from, so the type and the validation cannot drift apart.
6. Type tests with `@ts-expect-error` or `expectTypeOf` proving that impossible states do not compile.
7. When this model is overkill and something simpler would do.

Constraints:
- Prefer literal unions over `enum`, unless you explain why an enum is better here.
- No complex conditional types or generics unless they clearly pay off; a mid-level developer must be able to read the code.
- Do not invent business rules: mark the ones I must confirm with [FILL IN].

Output format: diagnosis, code blocks labeled with file names and a table of states and transitions.

How to use it

Usage example

Sample output

export type OrderId = string & { readonly __brand: 'OrderId' };

type Base = { readonly id: OrderId };

export type Order =
  | (Base & { status: 'pending' })
  | (Base & { status: 'paid'; paidAt: Date })
  | (Base & { status: 'shipped'; paidAt: Date; trackingNumber: string })
  | (Base & { status: 'delivered'; paidAt: Date; trackingNumber: string })
  | (Base & { status: 'cancelled'; cancelReason: string });

type InStatus<S extends Order['status']> = Extract<Order, { status: S }>;

export function ship(order: InStatus<'paid'>, trackingNumber: string): InStatus<'shipped'> {
  return { ...order, status: 'shipped', trackingNumber };
}

export function label(order: Order): string {
  switch (order.status) {
    case 'pending': return 'Awaiting payment';
    case 'paid': return 'Paid';
    case 'shipped': return `Shipped (${order.trackingNumber})`;
    case 'delivered': return 'Delivered';
    case 'cancelled': return `Cancelled: ${order.cancelReason}`;
    default: {
      const exhaustive: never = order;
      return exhaustive;
    }
  }
}

Key facts

Category

Programming & development · TypeScript

Output type

Code

Level

Advanced

Designed for

ChatGPT, Claude, Gemini and Microsoft Copilot

Verified in

Pending editorial verification

Variables

Domain, Current types and Where they are used

Language

English

Price

Free, no sign-up

Updated

Nov 7, 2026

Frequently asked questions