TypeScript discriminated unions are one of the nicest parts of the language.

They make it easy to model state, events, command results, API responses, agent events, and all kinds of variant-heavy domain logic without giving up type safety.

At the beginning, everything usually feels simple. You reach for whatever is most obvious: a switch, an if/else, a lookup object, whatever gets the job done.

And honestly, most of the time, that is completely fine.

The problem usually comes a few branches later.

The union grows. The cases stop being trivial. Some handlers need several fields, not just the discriminant. Some cases share behavior. Sometimes the field you care about lives on a nested path. Sometimes the source becomes promise-backed. Sometimes the data crosses a boundary and validation becomes part of the same flow.

At that point, discriminated unions are still doing their job.

But the code around them starts getting annoying.

Where it usually stops being trivial

Take a realistic event stream from an agentic application. Something like this is easy to model in TypeScript:

type AgentRunEvent =
  | {
      type: "run-start"
      runId: string
      agent: "planner" | "coder"
      timestamp: number
    }
  | {
      type: "text-delta"
      messageId: string
      delta: string
      timestamp: number
    }
  | {
      type: "thinking-delta"
      messageId: string
      delta: string
      timestamp: number
    }
  | {
      type: "tool-call-start"
      toolCallId: string
      toolName: string
      input?: {
        files?: string[]
        prompt?: string
      }
      timestamp: number
    }
  | {
      type: "tool-call-end"
      toolCallId: string
      toolName: string
      output: {
        summary: string
        artifacts?: {
          path: string
          kind: "file" | "diff"
        }[]
      }
      timestamp: number
    }
  | {
      type: "warning"
      code: "rate-limit" | "context-pressure"
      detail: string
      timestamp: number
    }
  | {
      type: "error"
      reason: "aborted" | "tool-failed" | "model-error"
      message: string
      retryable: boolean
      timestamp: number
    }
  | {
      type: "run-end"
      runId: string
      reason: "completed" | "stopped" | "error"
      timestamp: number
    }

This is exactly the kind of thing TypeScript is very good at.

The problem is what happens next.

Usually, you are not just checking the tag. You want the fully narrowed payload. You want to group related cases. You want the branching to be easy to scan. And once the event surface grows, a plain switch can start turning into a wall of control flow.

Something like this is perfectly valid:

function reduceAgentRun(state: RunState, event: AgentRunEvent): RunState {
  switch (event.type) {
    case "text-delta":
    case "thinking-delta":
      return appendStreamingDelta(state, event.messageId, event.delta)

    case "tool-call-start":
      return registerToolCall(
        state,
        event.toolCallId,
        event.toolName,
        event.input,
      )

    case "tool-call-end":
      return completeToolCall(state, event.toolCallId, event.output)

    case "warning":
      return addWarning(state, event.code, event.detail)

    case "error":
      return failRun(state, event.reason, event.message)

    case "run-end":
      return finishRun(state, event.reason)

    default:
      return state
  }
}

There is nothing wrong with this code.

But it is not the shape I always want.

The control flow starts taking more visual space than the intent. The reducer is still type-safe, but it becomes a bit harder to scan. And the bigger the union gets, the easier it is for the branching structure to become the thing you are fighting with.

The version I often want to write looks more like this:

function reduceAgentRun(state: RunState, event: AgentRunEvent): RunState {
  return matchBy(event, "type")
    .with("text-delta", "thinking-delta", (event) =>
      appendStreamingDelta(state, event.messageId, event.delta),
    )
    .with("tool-call-start", (event) =>
      registerToolCall(state, event.toolCallId, event.toolName, event.input),
    )
    .with("tool-call-end", (event) =>
      completeToolCall(state, event.toolCallId, event.output),
    )
    .with("warning", (event) =>
      addWarning(state, event.code, event.detail),
    )
    .with("error", (event) =>
      failRun(state, event.reason, event.message),
    )
    .with("run-end", (event) =>
      finishRun(state, event.reason),
    )
    .otherwise(() => state)
}

This is not a dramatic change in power.

It is a change in shape.

And for this kind of code, shape matters. I want the branch key to be obvious. I want the cases to be easy to scan. I want the handler to receive the narrowed event. And I do not want the reducer to be dominated by ceremony.

That is the kind of problem ts-match is trying to solve.

The specific kind of branching I wanted to make nicer

I am already using ts-match inside OpenWaggle, an open source desktop coding agent powered by Pi.

That has been a good proving ground because the code naturally has a lot of this stuff: discriminated unions, event streams, async orchestration, UI states, tool calls, and state transitions that get noisy fast if the branching shape is not kept under control.

That is where matchBy came from.

After writing enough code like this, I realized I kept wanting a first-class API for the common case where:

• I know the branch key
• I still want the full narrowed value in the handler
• I do not want to rewrite every case as an object pattern
• I want the code to stay readable when the union grows

For example, this is the kind of UI code where I like the shape:

function SettingsTabContent({ tab }: { tab: SettingsTab }) {
  return matchBy(tab, "type")
    .with("general", () => <GeneralSection />)
    .with("waggle", () => <WaggleSection />)
    .with("mcp", () => <McpSection />)
    .with("connections", () => <ConnectionsSection />)
    .with("archived", () => <ArchivedSection />)
    .otherwise(() => <GeneralSection />)
}

Could this be a switch? Of course.

But this is the point: I do not always want branching code to look like control flow. Sometimes I want it to look like a direct mapping from variants to behavior.

That is especially true in UI code, reducers, event handlers, and agent/event pipelines.

Why ts-pattern was still not exactly what I wanted

I want to be very clear about this: ts-pattern deserves a lot of credit.

It is an excellent library. It pushed this space forward. And it was definitely part of the inspiration for ts-match.

But I was looking for a slightly different bias.

I was not trying to out-generalize ts-pattern. I wanted something smaller and shaped around the cases I kept hitting in application code.

The main things I wanted were:

1. A first-class discriminant/path dispatch API with matchBy(...)
2. Promise-aware matching, so async values do not force a different branching style
3. A fail-fast assertion helper with assertMatching(...)
4. A small ESM-only package with an API that feels simple to reach for

That is the honest explanation.

I like general structural matching. It is powerful. But in a lot of my own code, I am often doing something simpler: dispatching by a known key and keeping the narrowed payload in the handler.

That is the path I wanted to optimize for.

Promise-backed values

Another thing I wanted was to keep the same branching style when the value comes from a promise.

Because in real applications, this happens all the time. A function starts synchronous, then later the source becomes async, and suddenly the branching style changes too.

I did not want that.

const nextStep = await match.promise(runAgentTurn(input))
  .with({ type: "needs-auth" }, () => ({
    type: "open-settings",
  }))
  .with({ type: "rate-limited" }, () => ({
    type: "retry-later",
  }))
  .with({ type: "ok" }, ({ output }) => ({
    type: "show-output",
    output,
  }))
  .otherwise(() => ({
    type: "show-error",
  }))

The interesting part here is not that promises are hard.

They are not.

The point is that I wanted the same matching style to work cleanly regardless of whether the value was already available or promise-backed.

Small thing, but it matters when you are trying to keep application code consistent.

Boundary assertions

The other adjacent case was boundary checks.

Sometimes data comes from JSON.parse, local storage, an IPC message, a tool response, or any other place where TypeScript cannot really protect you.

In those cases, I do not always want to bring a full validation layer just to fail fast on an obviously wrong shape.

const event = JSON.parse(raw)

assertMatching(event, {
  type: P.string,
  payload: P.object,
})

handleEvent(event)

To be clear, I would still reach for Zod, Valibot, or any other validation library when I need proper validation, parsing, transformation, reusable schemas, or good error reporting.

assertMatching is not trying to replace that.

But sometimes a full schema is overkill. Sometimes I just want a small boundary assertion so the rest of the code does not have to carry defensive checks everywhere.

Why this matters more with coding agents, not less

There is another reason I care about this now.

Coding agents are becoming part of the way we build software. They generate reducers, handlers, UI states, tool integrations, event pipelines, tests, and all the glue code around them.

So it is tempting to think that code shape matters less because agents can write the code for us.

I think it is the opposite.

If an agent generates the code, I still need to review it. I still need to understand it. I still need to trust it. And I still need to maintain it later.

Clean branching helps with that.

It gives humans a clearer way to audit what the code is doing. It gives agents a pattern they can repeat instead of inventing a slightly different control flow every time. It makes case coverage easier to reason about. And it helps keep ownership of the codebase with the people building the system, instead of slowly accepting generated code as opaque output.

That is also why I created an agent SKILL.md for ts-match.

Not because agents need magic documentation for everything, but because I want them to learn the intended usage patterns. I want the output to be not just valid, but consistent with the way the codebase is supposed to be written.

For me, that is becoming more important.

Agents are very good at producing code that works locally. They are not always good at preserving the shape of a codebase over time unless we give them clear patterns to follow.

So no, I do not think these patterns become irrelevant because agents can write code.

I think they become more important.

We still need to think, review, and own the systems we are building.

Try it

ts-match is not trying to replace TypeScript’s discriminated unions.

It is trying to make the code around them easier to read, easier to review, and easier to repeat consistently — for humans and for agents.

If this sounds like the kind of branching cleanup you care about, give it a try and let me know what you think. I am fully open to feedback.

pnpm add @diegogbrisa/ts-match
npm install @diegogbrisa/ts-match
yarn add @diegogbrisa/ts-match
bun add @diegogbrisa/ts-match

Repo: https://github.com/DiegoGBrisa/ts-match

OpenWaggle: https://openwaggle.ai

OpenWaggle repo: https://github.com/OpenWaggle/OpenWaggle