DEV Community: Deva Krishna

Type-Safe Regex Matching from First Principles

Deva Krishna — Sun, 30 Nov 2025 16:33:34 +0000

I came across a post from ArkType recently:

Regex patterns being parsed at compile time! TypeScript inferring exact string literals like "ac" | "abc" from the pattern "^ab?c$". Not just string, but the actual possible matches.

That got me curious. Regex has always been a runtime thing, you write a pattern, match strings against it, and the type system just sees string everywhere. But this was doing it all at compile time. I wanted to understand how, so I decided to build a minimal version myself.

What is ArkType Regex?

ArkType Regex is a compile-time regex parser written entirely in TypeScript's type system. Instead of just validating that a string might match a regex at runtime, it infers the exact string literal types that a regex can produce.

For example:

// Traditional regex: gives you `string`
const match = "abc".match(/^ab?c$/) // string | null

// ArkType regex: gives you the exact type
type Pattern = Regex<"^ab?c$"> // "ac" | "abc"

How does this work?

The implementation uses Template literal types to manipulate strings at the type level.

The parser reads the regex pattern character by character, builds an internal representation (AST), and then "finalizes" it into the actual TypeScript union type representing all possible matches.

Building Our Own From First Principles

Let's forget about ArkType's full implementation and build a minimal type-level regex parser ourselves. This will teach us the fundamental concepts of type-level computation in TypeScript.

The Goal

We want to create a Regex<Pattern> type that:

Takes a regex pattern string
Returns a union of all possible string literals that match

type R1 = Regex<"abc">     // "abc"
type R2 = Regex<"ab?c">    // "ac" | "abc"  
type R3 = Regex<"a|b">     // "a" | "b"
type R4 = Regex<"^ab?c$">  // "ac" | "abc"

Step 1: Understanding Template Literal Type Manipulation

Before we parse anything, we need to understand how to work with strings at the type level.

TypeScript's template literal types let us decompose strings:

// Extract the first character and the rest
type Shift<S extends string> = 
  S extends `${infer Head}${infer Tail}` 
    ? [Head, Tail] 
    : null

type Test1 = Shift<"abc">  // ["a", "bc"]
type Test2 = Shift<"a">    // ["a", ""]
type Test3 = Shift<"">     // null

The infer keyword lets us pattern-match on template literals and capture parts of the string into type variables.

We can also build strings:

type Concat<A extends string, B extends string> = `${A}${B}`

type Test4 = Concat<"hello", "world">  // "helloworld"

Step 2: Designing the State Machine

What Does "Parsing" Even Mean?

Parsing means reading through a string character by character and building up some result. In JavaScript, you might write:

function parse(pattern) {
  let result = ""
  for (let i = 0; i < pattern.length; i++) {
    const char = pattern[i]
    // do something with char, build up result
  }
  return result
}

Notice what we naturally need:

Where we are in the input - the index i
What we've built so far - the result we're accumulating

This is state - information that persists and changes as we move through the loop.

Tracking Position: Index vs. "What's Left"

In the loop above, we use i to know our position. But there's another way to think about it.

Instead of "I'm at position 2 of abc", we can say "I've already read ab, and c is left to read."

// Using index:
pattern = "abc", i = 2 → next char is pattern[2] = "c"

// Using "what's left":
unscanned = "c" → next char is "c"

Both track the same thing - where we are. But "what's left" is easier to work with in TypeScript's type system as we'll see in the following section.

The Problem: Types Can't Have Variables

In runtime JavaScript, we have mutable variables. We can write result += char and i++.

But TypeScript's type system has no variables. Types are immutable. So how do we "loop" and "accumulate"?

The answer: recursion with parameters.

Instead of mutating variables, we pass updated values to the next recursive call:

// Runtime approach (mutation):
let result = ""
for (char of input) {
  result = result + char  // mutate
}

// Type-level approach (recursion):
type Parse<Input, Result> = 
  Input extends `${infer Char}${infer Rest}`
    ? Parse<Rest, `${Result}${Char}`>  // "pass" new values to next iteration
    : Result  // base case: return accumulated result

Each "iteration" is a new type instantiation with updated parameters. If you don't understand this it's fine, read further you will get an understanding.

What State Do We Need?

At minimum, we need to track:

type State = {
  unscanned: string   // What's LEFT to read (like the remaining input)
  result: string      // What we've BUILT so far
}

Let's trace parsing "abc" with the simplest possible logic (just accumulate characters):

Step	unscanned	result	Action
0	`abc`	`""`	Start
1	`bc`	`a`	Read `a`, add to result
2	`c`	`ab`	Read `b`, add to result
3	`""`	`abc`	Read `c`, add to result
Done	`""`	`abc`	Nothing left, return result

This is the essence of parsing: consume input, build output.

Why Can't `result` Just Be a Simple String?

For basic concatenation, result: string works fine. But regex has quantifiers like ?.

Consider parsing ab?c. When we hit ?, we need to make the previous thing optional. In this case we will need to match ac and abc, as b is considered optional.

Step	unscanned	result	Action
0	`ab?c`	`""`	Start
1	`b?c`	`a`	Read `a`
2	`?c`	`ab`	Read `b`
3	`c`	`???`	Read `?` - now what?

Problem: We see ? and need to make b optional. But result is ab - just a flat string. How do we know that ? applies to b and not to ab or just a?

We've lost track of what the last thing we added was.

The Fix: Track "Current Element" Separately

We need to split our result into two parts:

type State = {
  unscanned: string   // What's left to read
  sequence: string    // Everything BEFORE the current element
  root: string        // The CURRENT element (what quantifiers target)
}

Now let's trace ab?c:

Step	unscanned	sequence	root	Action
0	`ab?c`	`""`	`""`	Start
1	`b?c`	`""`	`a`	`a` becomes current element
2	`?c`	`a`	`b`	`a` moves to sequence, `b` is current
3	`c`	`a`	`""` \| `b`	`?` makes root optional!
4	`""`	`a` \| `ab`	`c`	`c` is current, root joins sequence
Done				Combine: `ac` \| `abc`

By keeping the "current element" in root separate from "everything before" in sequence, we always know exactly what a quantifier should modify.

One More Thing: Alternation Needs Memory

The | operator creates alternatives: a|b should produce a | b.

When we see |, we need to:

Save the current pattern as a completed branch
Start fresh for the next alternative

We need somewhere to store those saved branches:

type State = {
  unscanned: string    // What's left to read
  sequence: string     // Pattern before current element  
  root: string         // Current element (quantifier target)
  branches: string[]   // Completed alternatives (for |)
}

Trace a|b:

Step	unscanned	sequence	root	branches	Action
0	`a\|b`	`""`	`""`	`[]`	Start
1	`\|b`	`""`	`a`	`[]`	`a` is current
2	`b`	`""`	`""`	`["a"]`	See `\|`: save `a`, reset
3	`""`	`""`	`b`	`["a"]`	`b` is current
Done					Union: `a` \| `b`

Summary: Why Each Field Exists

Field	Why We Need It
`unscanned`	Track what's left to read (our "loop counter")
`sequence`	Accumulate "finished" parts of pattern
`root`	Keep "current element" separate so quantifiers know what to modify
`branches`	Store completed alternatives when we see `\|`

type State = {
  unscanned: string
  sequence: string
  root: string
  branches: string[]
}

type Init<S extends string> = {
  unscanned: S
  sequence: ""
  root: ""
  branches: []
}

Now we have a state structure that can handle the core regex operations. Next, we'll build the logic that transforms this state character by character.

Step 3: The Core Parse Loop

Recursive types let us implement loops:

type Parse<S extends State> = 
  S["unscanned"] extends ""      // Is input exhausted?
    ? Finalize<S>                // Yes: finalize and return result
    : Parse<Next<S>>             // No: process next char, recurse

This is the heart of the parser. It repeatedly calls Next to process one character until the input is empty, then calls Finalize to produce the result.

Step 4: Processing Literal Characters

Let's start with the simplest case: literal characters.

What we expect:

type Result = Regex<"abc"> // "abc"

Implementation:

type Next<S extends State> = 
  S["unscanned"] extends `${infer H}${infer T}` 
    ? {
        unscanned: T                           // Consume the character
        sequence: `${S["sequence"]}${S["root"]}`  // Push old root to sequence
        root: H                                // New char becomes root
        branches: S["branches"]                // Branches unchanged
      }
    : S

What's happening here:

Extract the first character H and rest T
The current root joins the sequence (it's no longer the "current token")
The new character becomes the root
Branches stay the same

Let's add a simple finalizer:

type CurrentPattern<S extends State> = `${S["sequence"]}${S["root"]}`

type Finalize<S extends State> = 
  S["branches"] extends [] 
    ? CurrentPattern<S>                              // No branches: just return pattern
    : [...S["branches"], CurrentPattern<S>][number]  // Branches: union them all

The [number] trick converts an array type to a union of its elements.

Test it:

type R = Parse<Init<"abc">>  // "abc"

Step 5: The Optional Quantifier `?`

Now the interesting part. When we see ?, we need to make the root optional.

What we expect:

type Result = Regex<"ab?c"> // "ac" | "abc"

Implementation:

type Next<S extends State> = 
  S["unscanned"] extends `${infer H}${infer T}` 
    ? H extends "?"
      ? {
          unscanned: T
          sequence: S["sequence"]       // Sequence unchanged
          root: "" | S["root"]          // Root becomes optional!
          branches: S["branches"]
        }
      : {
          unscanned: T
          sequence: `${S["sequence"]}${S["root"]}`
          root: H
          branches: S["branches"]
        }
    : S

The magic is "" | S["root"]. If root was b, it becomes "" | b.

When we finalize with sequence = "a" and root = "" | "b":

`${S["sequence"]}${S["root"]}`
// = `${"a"}${"" | "b"}`
// = "a" | "ab"

TypeScript distributes the union across the template literal! This is key to the whole approach.

Wait, we also need to handle c after ?. Let's trace through ab?c:

Initial: {unscanned: "ab?c", sequence: "", root: "", branches: []}
After a: {unscanned: "b?c", sequence: "", root: "a", branches: []}
After b: {unscanned: "?c", sequence: "a", root: "b", branches: []}
After ?: {unscanned: "c", sequence: "a", root: "" | "b", branches: []}
After c: {unscanned: "", sequence: "a" | "ab", root: "c", branches: []}
Finalize: "ac" | "abc"

The distribution happens at step 5 when we concatenate the union in root into sequence.

Step 6: Handling Anchors

Anchors ^ and $ assert position but don't consume characters. For simplicity, let's strip them:

type StripAnchors<S extends string> = 
  S extends `^${infer R}` 
    ? R extends `${infer M}$` 
      ? M 
      : R
    : S extends `${infer M}$` 
      ? M 
      : S

type Regex<S extends string> = Parse<Init<StripAnchors<S>>>

Now Regex<"^ab?c$"> works like Regex<"ab?c">.

Step 7: Adding More Quantifiers

Let's add + (one or more) and * (zero or more).

What we expect:

type Result1 = Regex<"a+"> // `a${string}`
type Result2 = Regex<"a*"> // "" | `a${string}`

Implementation:

type Next<S extends State> = 
  S["unscanned"] extends `${infer H}${infer T}` 
    ? H extends "?"
      ? { 
          unscanned: T
          sequence: S["sequence"]
          root: "" | S["root"]           // 0 or 1
          branches: S["branches"] 
        }
      : H extends "+"
      ? { 
          unscanned: T
          sequence: S["sequence"]
          root: `${S["root"]}${string}`  // 1 or more
          branches: S["branches"] 
        }
      : H extends "*"
      ? { 
          unscanned: T
          sequence: S["sequence"]
          root: "" | `${S["root"]}${string}`  // 0 or more
          branches: S["branches"] 
        }
      : { 
          unscanned: T
          sequence: `${S["sequence"]}${S["root"]}`
          root: H
          branches: S["branches"] 
        }
    : S

For + and *, we can't enumerate all possibilities (infinite), so we use ${string} to represent "any continuation":

a+ → `a${string}` (starts with a, followed by anything)
a* → "" | `a${string}` (empty or starts with a)

This widens the type but keeps it useful for validation.

Step 8: The Alternation Operator `|`

The | creates alternatives. When we see it, we need to:

Finalize the current branch
Push it to branches
Start fresh for the next alternative

What we expect:

type Result = Regex<"a|b"> // "a" | "b"

Implementation:

type Next<S extends State> = 
  S["unscanned"] extends `${infer H}${infer T}` 
    ? H extends "|"
      ? {
          unscanned: T
          sequence: ""                         // Reset sequence
          root: ""                               // Reset root
          branches: [...S["branches"], CurrentPattern<S>]  // Save current branch
        }
      : H extends "?"
        // ... rest of cases

In Finalize, we union all branches together:

type Finalize<S extends State> = 
  S["branches"] extends [] 
    ? CurrentPattern<S>
    : [...S["branches"], CurrentPattern<S>][number]

The [...array, lastElement][number] pattern creates a union from the array plus the last element.

The Complete Implementation

// === STATE TYPES ===
type State = {
  unscanned: string
  sequence: string  
  root: string
  branches: string[]
}

type Init<S extends string> = {
  unscanned: S
  sequence: ""
  root: ""
  branches: []
}

// === HELPERS ===
type CurrentPattern<S extends State> = `${S["sequence"]}${S["root"]}`

type StripAnchors<S extends string> = 
  S extends `^${infer R}` 
    ? R extends `${infer M}$` ? M : R
    : S extends `${infer M}$` ? M : S

// === FINALIZE ===
type Finalize<S extends State> = 
  S["branches"] extends [] 
    ? CurrentPattern<S>
    : [...S["branches"], CurrentPattern<S>][number]

// === NEXT - CHARACTER DISPATCH ===
type Next<S extends State> = 
  S["unscanned"] extends `${infer H}${infer T}` 
    ? H extends "|"
      ? { unscanned: T; sequence: ""; root: ""; 
          branches: [...S["branches"], CurrentPattern<S>] }
      : H extends "?"
      ? { unscanned: T; sequence: S["sequence"]; root: "" | S["root"]; 
          branches: S["branches"] }
      : H extends "+"
      ? { unscanned: T; sequence: S["sequence"]; root: `${S["root"]}${string}`; 
          branches: S["branches"] }
      : H extends "*"
      ? { unscanned: T; sequence: S["sequence"]; root: "" | `${S["root"]}${string}`; 
          branches: S["branches"] }
      : { unscanned: T; sequence: `${S["sequence"]}${S["root"]}`; root: H; 
          branches: S["branches"] }
    : S

// === PARSE LOOP ===
type Parse<S extends State> = 
  S["unscanned"] extends "" ? Finalize<S> : Parse<Next<S>>

// === PUBLIC API ===
type Regex<S extends string> = Parse<Init<StripAnchors<S>>>

// === TESTS ===
type T1 = Regex<"abc">       // "abc"
type T2 = Regex<"^abc$">     // "abc"  
type T3 = Regex<"ab?c">      // "ac" | "abc"
type T4 = Regex<"a|b">       // "a" | "b"
type T5 = Regex<"^a?b?$">    // "" | "a" | "b" | "ab"
type T6 = Regex<"a+">        // `a${string}`
type T7 = Regex<"a*">        // "" | `a${string}`

What We've Built

Our ~50 lines of type-level code can:

Parse literal characters
Handle optional ?, one-or-more +, and zero-or-more * quantifiers
Process alternation with |
Strip anchors ^ and $

What's Still Missing

A production implementation (like ArkType's) would add:

Groups (...) - Requires a stack to track nested groups
Character classes [abc] - Need a sub-parser for charsets
Escape sequences \d, \w - Map to appropriate types like ${bigint}
Range quantifiers {n,m} - Need recursive loops to enumerate
Backreferences \1 - Track captures and resolve references
Named captures (?<name>...) - Track in separate context

Each feature adds complexity, but the fundamental approach remains: recursive type computation with state threading.

This approach demonstrates that TypeScript's type system can implement surprisingly complex algorithms purely at compile time, catching errors before your code ever runs.

Found this useful? I write about TypeScript, type-level programming, and the weird corners of web development. Subscribe to catch the next one.

Follow me on X for more TypeScript tips and dev thoughts.

Stop Memorizing Patterns, Start Writing Tests: A Pragmatic Guide to Better Code

Deva Krishna — Fri, 28 Nov 2025 17:41:38 +0000

Writing good code is hard. The industry's response has been to create an ever-growing catalog of design patterns, principles, and architectural guidelines. While these have their place, there's a simpler practice that yields better results: writing tests.

A Simple Feature Request

Let's start with something simple. You need to build a function that calculates the total price of items in a shopping cart, including tax.

That's it. A straightforward requirement.

Let's see how this can go wrong when we think in patterns first, and how tests lead us to better design.

The Pattern-First Approach

Step 1: "I need a Cart class"

The first instinct is often to create a class.

class ShoppingCart {
  private items: CartItem[] = [];

  addItem(item: CartItem): void {
    this.items.push(item);
  }

  getItems(): CartItem[] {
    return this.items;
  }
}

The thought process: "A cart has items, so I'll make a Cart class that holds them. This is basic OOP."

The problem introduced: We've coupled storage and retrieval together. The cart now manages its own state. Testing requires instantiating the class and calling methods in sequence.

Step 2: "I should separate concerns"

Now we need to calculate the total. But wait—calculation is a different concern than storage. Let's add a separate calculator.

class PriceCalculator {
  calculate(cart: ShoppingCart): number {
    const items = cart.getItems();
    return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  }
}

The thought process: "Single Responsibility Principle says each class should have one reason to change. Storage might change independently from calculation logic."

The problem introduced: Now we have two classes that are tightly coupled anyway. PriceCalculator depends on ShoppingCart. We can't test the calculator without creating a cart first.

Step 3: "I need an interface for flexibility"

What if we want different cart implementations later? Let's add an interface.

interface ICart {
  getItems(): CartItem[];
}

class ShoppingCart implements ICart {
  private items: CartItem[] = [];

  addItem(item: CartItem): void {
    this.items.push(item);
  }

  getItems(): CartItem[] {
    return this.items;
  }
}

class PriceCalculator {
  calculate(cart: ICart): number {
    const items = cart.getItems();
    return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  }
}

The thought process: "Dependency Inversion Principle says we should depend on abstractions. Now I can swap cart implementations."

The problem introduced: We've added an interface for a flexibility we don't need yet. The interface mirrors the concrete class exactly. This is speculation, not design.

Step 4: "Tax calculation should be configurable"

Now we remember we need tax. Different regions have different tax rates. This calls for a strategy pattern.

interface TaxStrategy {
  calculateTax(subtotal: number): number;
}

class FlatTaxStrategy implements TaxStrategy {
  constructor(private rate: number) {}

  calculateTax(subtotal: number): number {
    return subtotal * this.rate;
  }
}

class PriceCalculator {
  constructor(private taxStrategy: TaxStrategy) {}

  calculate(cart: ICart): number {
    const items = cart.getItems();
    const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
    const tax = this.taxStrategy.calculateTax(subtotal);
    return subtotal + tax;
  }
}

The thought process: "Strategy pattern allows me to swap algorithms at runtime. Tax rules might change or vary by region."

The problem introduced: To calculate a total, we now need to instantiate a tax strategy, inject it into a calculator, create a cart, add items to it, then call calculate. We've built machinery for hypothetical requirements.

Step 5: "I should add a factory"

Creating all these objects is tedious. Let's add a factory to simplify instantiation.

class PriceCalculatorFactory {
  static createForRegion(region: string): PriceCalculator {
    const taxRates: Record<string, number> = {
      US: 0.08,
      UK: 0.2,
      DE: 0.19,
    };

    const rate = taxRates[region] ?? 0;
    const taxStrategy = new FlatTaxStrategy(rate);
    return new PriceCalculator(taxStrategy);
  }
}

The thought process: "Factory pattern encapsulates object creation. Now callers don't need to know about tax strategies."

The problem introduced: We've added another class. The factory hides the complexity but doesn't remove it. The system is harder to understand because behavior is spread across multiple files.

The Final "Architecture"

Here's what we built for a simple calculation:

// types.ts
interface CartItem {
  name: string;
  price: number;
  quantity: number;
}

// interfaces/ICart.ts
interface ICart {
  getItems(): CartItem[];
}

// interfaces/TaxStrategy.ts
interface TaxStrategy {
  calculateTax(subtotal: number): number;
}

// implementations/ShoppingCart.ts
class ShoppingCart implements ICart {
  private items: CartItem[] = [];

  addItem(item: CartItem): void {
    this.items.push(item);
  }

  getItems(): CartItem[] {
    return this.items;
  }
}

// implementations/FlatTaxStrategy.ts
class FlatTaxStrategy implements TaxStrategy {
  constructor(private rate: number) {}

  calculateTax(subtotal: number): number {
    return subtotal * this.rate;
  }
}

// services/PriceCalculator.ts
class PriceCalculator {
  constructor(private taxStrategy: TaxStrategy) {}

  calculate(cart: ICart): number {
    const items = cart.getItems();
    const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
    const tax = this.taxStrategy.calculateTax(subtotal);
    return subtotal + tax;
  }
}

// factories/PriceCalculatorFactory.ts
class PriceCalculatorFactory {
  static createForRegion(region: string): PriceCalculator {
    const taxRates: Record<string, number> = {
      US: 0.08,
      UK: 0.2,
      DE: 0.19,
    };

    const rate = taxRates[region] ?? 0;
    const taxStrategy = new FlatTaxStrategy(rate);
    return new PriceCalculator(taxStrategy);
  }
}

// Usage
const cart = new ShoppingCart();
cart.addItem({ name: 'Book', price: 20, quantity: 2 });
cart.addItem({ name: 'Pen', price: 5, quantity: 3 });

const calculator = PriceCalculatorFactory.createForRegion('US');
const total = calculator.calculate(cart);

We have 6 files, 2 interfaces, 4 classes, and roughly 70 lines of code. Testing this requires mocking interfaces and understanding the relationships between components.

The Test-First Approach

Let's start over. This time, we write a test first.

Step 1: Write the simplest test

What do we actually need? A function that takes items and a tax rate, and returns a total.

import { describe, it, expect } from 'vitest';

describe('calculateTotal', () => {
  it('calculates total with tax', () => {
    const items = [
      { name: 'Book', price: 20, quantity: 2 },
      { name: 'Pen', price: 5, quantity: 3 },
    ];

    const total = calculateTotal(items, { taxRate: 0.08 });

    // Subtotal: (20 * 2) + (5 * 3) = 55
    // Tax: 55 * 0.08 = 4.4
    // Total: 59.4
    expect(total).toBe(59.4);
  });
});

The thought process: "What's the simplest way to express what I need? I have items, I have a tax rate, I want a number back."

What this reveals: We don't need a cart class. We just need an array of items. We don't need a tax strategy interface. We just need a tax rate number.

Step 2: Write the simplest implementation

interface CartItem {
  name: string;
  price: number;
  quantity: number;
}

interface CalculationOptions {
  taxRate: number;
}

function calculateTotal(items: CartItem[], options: CalculationOptions): number {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const tax = subtotal * options.taxRate;
  return subtotal + tax;
}

The test passes. We're done with the basic requirement.

Step 3: Add tests for edge cases

What happens with empty carts? Zero tax? Let's find out by writing tests.

describe('calculateTotal', () => {
  it('calculates total with tax', () => {
    const items = [
      { name: 'Book', price: 20, quantity: 2 },
      { name: 'Pen', price: 5, quantity: 3 },
    ];

    const total = calculateTotal(items, { taxRate: 0.08 });

    expect(total).toBe(59.4);
  });

  it('returns zero for empty cart', () => {
    const total = calculateTotal([], { taxRate: 0.08 });

    expect(total).toBe(0);
  });

  it('handles zero tax rate', () => {
    const items = [{ name: 'Book', price: 100, quantity: 1 }];

    const total = calculateTotal(items, { taxRate: 0 });

    expect(total).toBe(100);
  });

  it('handles single item', () => {
    const items = [{ name: 'Book', price: 25, quantity: 1 }];

    const total = calculateTotal(items, { taxRate: 0.1 });

    expect(total).toBe(27.5);
  });
});

All tests pass without changing the implementation. The function already handles these cases correctly.

Step 4: Add a new requirement with a new test

Now suppose we need to support discounts. Write the test first.

it('applies discount before tax', () => {
  const items = [{ name: 'Book', price: 100, quantity: 1 }];

  const total = calculateTotal(items, { taxRate: 0.1, discount: 0.2 });

  // Subtotal: 100
  // After 20% discount: 80
  // Tax: 80 * 0.1 = 8
  // Total: 88
  expect(total).toBe(88);
});

Now update the implementation to pass this test:

interface CalculationOptions {
  taxRate: number;
  discount?: number;
}

function calculateTotal(items: CartItem[], options: CalculationOptions): number {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const discountAmount = subtotal * (options.discount ?? 0);
  const afterDiscount = subtotal - discountAmount;
  const tax = afterDiscount * options.taxRate;
  return afterDiscount + tax;
}

Step 5: Handle complexity only when tests demand it

Suppose we now need region-based tax rates. A test drives this decision:

it('uses region-specific tax rate', () => {
  const items = [{ name: 'Book', price: 100, quantity: 1 }];

  const total = calculateTotal(items, { region: 'UK' });

  // UK tax rate is 20%
  expect(total).toBe(120);
});

Now we have a reason to add region handling:

const TAX_RATES: Record<string, number> = {
  US: 0.08,
  UK: 0.2,
  DE: 0.19,
};

interface CalculationOptions {
  taxRate?: number;
  region?: string;
  discount?: number;
}

function calculateTotal(items: CartItem[], options: CalculationOptions): number {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const discountAmount = subtotal * (options.discount ?? 0);
  const afterDiscount = subtotal - discountAmount;

  const taxRate = options.taxRate ?? TAX_RATES[options.region ?? ''] ?? 0;
  const tax = afterDiscount * taxRate;

  return afterDiscount + tax;
}

The Final Implementation

// cart.ts
interface CartItem {
  name: string;
  price: number;
  quantity: number;
}

const TAX_RATES: Record<string, number> = {
  US: 0.08,
  UK: 0.2,
  DE: 0.19,
};

interface CalculationOptions {
  taxRate?: number;
  region?: string;
  discount?: number;
}

function calculateTotal(items: CartItem[], options: CalculationOptions = {}): number {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const discountAmount = subtotal * (options.discount ?? 0);
  const afterDiscount = subtotal - discountAmount;

  const taxRate = options.taxRate ?? TAX_RATES[options.region ?? ''] ?? 0;
  const tax = afterDiscount * taxRate;

  return afterDiscount + tax;
}

export { calculateTotal, CartItem, CalculationOptions };

// cart.test.ts
import { describe, it, expect } from 'vitest';
import { calculateTotal } from './cart';

describe('calculateTotal', () => {
  it('calculates total with tax', () => {
    const items = [
      { name: 'Book', price: 20, quantity: 2 },
      { name: 'Pen', price: 5, quantity: 3 },
    ];

    const total = calculateTotal(items, { taxRate: 0.08 });

    expect(total).toBe(59.4);
  });

  it('returns zero for empty cart', () => {
    const total = calculateTotal([], { taxRate: 0.08 });

    expect(total).toBe(0);
  });

  it('handles zero tax rate', () => {
    const items = [{ name: 'Book', price: 100, quantity: 1 }];

    const total = calculateTotal(items, { taxRate: 0 });

    expect(total).toBe(100);
  });

  it('applies discount before tax', () => {
    const items = [{ name: 'Book', price: 100, quantity: 1 }];

    const total = calculateTotal(items, { taxRate: 0.1, discount: 0.2 });

    expect(total).toBe(88);
  });

  it('uses region-specific tax rate', () => {
    const items = [{ name: 'Book', price: 100, quantity: 1 }];

    const total = calculateTotal(items, { region: 'UK' });

    expect(total).toBe(120);
  });

  it('prefers explicit tax rate over region', () => {
    const items = [{ name: 'Book', price: 100, quantity: 1 }];

    const total = calculateTotal(items, { region: 'UK', taxRate: 0.05 });

    expect(total).toBe(105);
  });

  it('defaults to zero tax when no rate or region provided', () => {
    const items = [{ name: 'Book', price: 100, quantity: 1 }];

    const total = calculateTotal(items);

    expect(total).toBe(100);
  });
});

One file, one function, 30 lines of implementation, 50 lines of tests. Every behavior is documented and verified.

Comparing the Two Approaches

Aspect	Pattern-First	Test-First
Lines of code	~70	~30
Interfaces	2	0
Classes	4	0
Test setup complexity	High (mocks, instantiation)	Low (just call the function)
Flexibility	Theoretical	Actual (easy to modify)
Documentation	Scattered across files	Tests describe all behaviors

Why Tests Lead to Better Design

Tests punish unnecessary complexity

Every abstraction you add makes tests harder to write. If you need three mocks to test one function, the function has too many dependencies. Tests make this pain immediate.

Tests force you to think about inputs and outputs

When you write a test, you must decide: what goes in, and what comes out? This naturally leads to functions with clear contracts rather than objects with hidden state.

Tests document behavior

Six months from now, which is easier to understand: a class diagram showing PriceCalculator depends on ICart and TaxStrategy, or a test that says "applies discount before tax"?

Tests enable safe refactoring

With the test-first approach, you can completely rewrite the implementation. As long as tests pass, behavior is preserved. With the pattern-first approach, you're locked into the structure you created.

When Patterns Are Appropriate

Patterns aren't always wrong. They're appropriate when:

You have proven, repeated need (you've written similar code three times)
The team benefits from shared vocabulary
The codebase is large enough that consistency aids navigation

The key difference is timing. Let patterns emerge from needs that tests reveal, rather than imposing them upfront based on speculation.

Conclusion

The pattern-first approach asks: "What structure should this code have?"

The test-first approach asks: "What should this code do?"

The second question leads to simpler, more maintainable code. Write tests first. Let them guide your design. Add abstractions only when tests become hard to write or requirements genuinely demand flexibility.

Your future self, and your teammates, will thank you.

Disclaimer: This article isn't advocating for strict Test-Driven Development (TDD) as a methodology. The core message is simpler: writing tests whether before, during, or after your implementation forces you to think clearly about your code's design and helps you avoid unnecessary complexity. Use tests as a design tool, not a dogma.

Found this useful? I write about TypeScript, type-level programming, and the weird corners of web development. Subscribe to catch the next one.

Follow me on X for more TypeScript tips and dev thoughts.

The False Security of tRPC Type Safety: Catching Serialization Bugs at Compile Time

Deva Krishna — Thu, 27 Nov 2025 20:27:37 +0000

If you're using tRPC, you probably feel invincible. Full end-to-end type safety. Your IDE autocompletes everything, TypeScript validates your queries, and life is good.

Until it isn't.

Yesterday, I returned a dayjs object from a tRPC procedure. TypeScript was happy. My IDE showed all the methods. And then my app crashed at runtime with:

TypeError: format is not a function

Let me show what happened, why it happened, and how I built a TypeScript utility that catches this class of bugs at compile time before they ever reach production.

The Problem: A Tale of Two Types

Here is the scenario. We are using superjson and dayjs.

Here's the code that broke production:

// SERVER
const appRouter = t.router({
  getEvent: t.procedure.query(() => ({
    name: "Tech Conference 2025",
    // Returning a Dayjs instance
    date: dayjs('2025-11-28'),
  })),
});

export type AppRouter = typeof appRouter;

// CLIENT
const event = await client.getEvent.query();

// ❌ Error at runtime
console.log(event.date.format('YYYY-MM-DD'));

TypeScript sees event.date as type Dayjs. It autocompletes .format(), .add(), .subtract() the full API. Everything looks fine.

But at runtime? event.date is just a plain string. There's no .format() method. The app crashed.

Why Does This Happen?

The culprit is serialization. When data travels from server to client, it goes through JSON serialization. And JSON doesn't know what a Dayjs object is.

Here's what actually happens:

Server Creates a real Dayjs object with all its methods.
SuperJSON converts it to JSON for transport, in this case it converts Dayjs object into a ISOString.
Client Receives ISOString, but not a Dayjs instance

SuperJSON is smarter than regular JSON.stringify(), it handles Date, Map, Set, BigInt, and more. But it doesn't know about dayjs out of the box. So it falls back to string, and doesn't reconstruct it on the other side.

The type system, however, has no idea this happened. It still thinks you have a Dayjs object.

The Quick Fix: Teaching SuperJSON About Dayjs

Before we dive into the compile-time solution, here's how to actually fix the runtime behavior:

import superjson from 'superjson';
import dayjs, { Dayjs } from 'dayjs';

superjson.registerCustom<Dayjs, string>(
  {
    isApplicable: (v): v is Dayjs => dayjs.isDayjs(v),
    serialize: (v) => v.toISOString(),
    deserialize: (v) => dayjs(v),
  },
  'dayjs'
);

Now SuperJSON knows how to serialize dayjs objects and crucially how to reconstruct them on the client side.

Problem solved. But here's the major issue:

What about the next library I use that has the same problem?

What about Decimal.js? What about that custom class my teammate adds next month?

I wanted TypeScript to catch these issues before they become runtime errors.

Building a Compile-Time Validator

The goal: create a type that analyzes all tRPC router outputs and fails compilation if any of them contain non-serializable values.

Let's build this step by step.

Step 1: Define What "Safe" Means

First, we need to define what types are safe to serialize. These are types that either:

Are primitives (string, number, boolean, null, undefined)
Are already handled by SuperJSON (Date, BigInt)
Are types we've explicitly registered (like Dayjs after our fix)
Are arrays or objects composed entirely of safe types

type SafePrimitive =
  | string
  | number
  | boolean
  | null
  | undefined
  | Date        // SuperJSON handles this
  | bigint      // SuperJSON handles this
  | void;

Step 2: Create a Type-Level Validator

Now we need a type that recursively checks whether a type is "safe." If it is, it returns true. If it isn't, it returns the problematic type itself (so we can see what's wrong).

type IsSerializable<T> = 
  // Is it a primitive we know is safe?
  T extends SafePrimitive
    ? true
    // Is it a function? Functions can't be serialized!
    : T extends (...args: any[]) => any
      ? T  // Return the function type as the "error"
      // Is it an array? Check the element type
      : T extends Array<infer U>
        ? IsSerializable<U>
        // Is it an object? Check all properties
        : T extends object
          ? CheckAllProperties<T>
          // Unknown type - be conservative and flag it
          : T;

For objects, we need to check that every property is serializable:

type CheckAllProperties<T> = {
  [K in keyof T]: IsSerializable<T[K]>;
} extends {
  [K in keyof T]: true;
}
  ? true
  : T;  // Return the object type as the "error"

We map over every key in the object, check if each property is serializable, and then ask: "Does this produce an object where every value is true?"

If yes, the whole object is safe. If not, we return the object type itself so the error message shows what went wrong.

Step 3: Handle tRPC's Streaming (AsyncIterables)

tRPC supports subscriptions and streaming, which use AsyncIterable. We need to handle these too:

type YieldType<T> = T extends AsyncIterable<infer U> ? U : never;

type IsSerializable<T> = 
  T extends SafePrimitive
    ? true
    : T extends AsyncIterable<unknown>
      ? IsSerializable<YieldType<T>>  // Check what the stream yields
      : T extends (...args: any[]) => any
        ? T
        : T extends Array<infer U>
          ? IsSerializable<U>
          : T extends object
            ? CheckAllProperties<T>
            : T;

Step 4: Apply to All Router Outputs

Now we connect this to tRPC's type system:

import { inferRouterOutputs } from "@trpc/server";
import type { AppRouter } from "./server";

type RouterOutputs = inferRouterOutputs<AppRouter>;

// Check each procedure in each router
type CheckRouter = {
  [K in keyof RouterOutputs]: {
    [P in keyof RouterOutputs[K]]: IsSerializable<RouterOutputs[K][P]>;
  } extends {
    [P in keyof RouterOutputs[K]]: true;
  }
    ? true
    : false;
};

// Final check: are ALL procedures safe?
type AllOutputsSerializable = CheckRouter extends {
  [K in keyof RouterOutputs]: true;
}
  ? true
  : false;

Step 5: The Assertion

Finally, we create a type that causes a compile error if anything is wrong:

type Expect<T extends true> = T;

// This line is the sentinel
type _AssertAllOutputsSerializable = Expect<AllOutputsSerializable>;

If AllOutputsSerializable is true, this compiles fine.

If it's false, TypeScript throws:

Type 'false' does not satisfy the constraint 'true'.

The Complete Solution

Here's everything together, ready to drop into your codebase:

import { inferRouterOutputs } from "@trpc/server";
import type { AppRouter } from "./server";
import dayjs from "dayjs";

// === Type Utilities ===

type YieldType<T> = T extends AsyncIterable<infer U> ? U : never;

type Expect<T extends true> = T;

// === Serialization Safety ===

// Types that are safe to serialize over the wire
// Add types here as you register them with SuperJSON!
type SafePrimitive =
  | string
  | number
  | boolean
  | null
  | undefined
  | Date
  | void
  | bigint
  | dayjs.Dayjs;  // ← Add this AFTER registering with SuperJSON

type IsSerializable<T> = T extends SafePrimitive
  ? true
  : T extends AsyncIterable<unknown>
    ? IsSerializable<YieldType<T>>
    : T extends (...args: any[]) => any
      ? T  // Functions are not serializable - return type for error message
      : T extends Array<infer U>
        ? IsSerializable<U>
        : T extends object
          ? {
              [K in keyof T]: IsSerializable<T[K]>;
            } extends {
              [K in keyof T]: true;
            }
              ? true
              : T  // Return the problematic object type
          : T;

// === Router Validation ===

type RouterOutputs = inferRouterOutputs<AppRouter>;

type ValidateProcedure<K extends keyof RouterOutputs> = {
  [P in keyof RouterOutputs[K]]: IsSerializable<RouterOutputs[K][P]>;
} extends {
  [P in keyof RouterOutputs[K]]: true;
}
  ? true
  : false;

type ValidateAllProcedures = {
  [K in keyof RouterOutputs]: ValidateProcedure<K>;
} extends {
  [K in keyof RouterOutputs]: true;
}
  ? true
  : false;

// If this line errors, you have an unregistered type in your router outputs!
type _EnsureSerializableOutputs = Expect<ValidateAllProcedures>;

How to Use This

Create a file called router-type-check.ts (or similar)
Paste the code above
Import your AppRouter type
Run tsc (or let your IDE do it)

If you have an unserializable type, you'll get a compile error. To fix it:

Register the type with SuperJSON using registerCustom()
Add the type to the SafePrimitive union

The key insight: the SafePrimitive list is your contract. It says "these are the types I've verified are safe." When you add a new custom type, you must:

Register it with SuperJSON (runtime fix)
Add it to SafePrimitive (compile-time acknowledgment)

This two-step process ensures you can't forget either half of the fix.

What Errors Look Like

When something is wrong, TypeScript will show:

Type 'false' does not satisfy the constraint 'true'.
  Type 'false' is not assignable to type 'true'.
    at type _EnsureSerializableOutputs = Expect<ValidateAllProcedures>

Getting Better Error Messages

The default error only tells you something is wrong, not what. To pinpoint the problematic type, you can manually invoke IsSerializable on specific procedure outputs:

import { inferRouterOutputs } from "@trpc/server";
import type { AppRouter } from "./server";

type RouterOutputs = inferRouterOutputs<AppRouter>;

// Hover over this type or check the error message
type DebugGetEvent = IsSerializable<RouterOutputs["events"]["getEvent"]>;
//   ^? type DebugGetEvent = { name: string; date: Dayjs }

When a type is serializable, you'll see true. When it's not, TypeScript returns the problematic type itself. In this example, hovering over DebugGetEvent reveals the full object type containing the Dayjs field—immediately showing you where the issue is.

You can drill down further into nested properties:

type DebugDate = IsSerializable<RouterOutputs["events"]["getEvent"]["date"]>;
//   ^? type DebugDate = Dayjs

Now you know exactly which field is causing the problem. Once you register Dayjs with SuperJSON and add it to SafePrimitive, this will resolve to true.

Wrapping Up

Type safety in tRPC feels complete, but it has a blind spot: serialization. The types flow from server to client, but they describe what's returned, not what survives the journey.

By building a compile time validator, we can catch these issues before they become production incidents. It's not perfect, but it's a significant improvement over discovering the problem when a user reports a crash.

The broader lesson: when two systems meet (in this case, TypeScript's type system and JSON serialization), there's often a gap where assumptions don't hold. Finding those gaps and building bridges, even imperfect ones, is where a lot of real world engineering happens.

Found this useful? I write about TypeScript, type-level programming, and the weird corners of web development. Subscribe to catch the next one.

Follow me on X for more TypeScript tips and dev thoughts.

DEV Community: Deva Krishna

Type-Safe Regex Matching from First Principles

What is ArkType Regex?

Building Our Own From First Principles

The Goal

Step 1: Understanding Template Literal Type Manipulation

Step 2: Designing the State Machine

What Does "Parsing" Even Mean?

Tracking Position: Index vs. "What's Left"

The Problem: Types Can't Have Variables

What State Do We Need?

Why Can't result Just Be a Simple String?

The Fix: Track "Current Element" Separately

One More Thing: Alternation Needs Memory

Summary: Why Each Field Exists

Step 3: The Core Parse Loop

Step 4: Processing Literal Characters

Step 5: The Optional Quantifier ?

Step 6: Handling Anchors

Step 7: Adding More Quantifiers

Step 8: The Alternation Operator |

The Complete Implementation

What We've Built

What's Still Missing

Stop Memorizing Patterns, Start Writing Tests: A Pragmatic Guide to Better Code

A Simple Feature Request

The Pattern-First Approach

Step 1: "I need a Cart class"

Step 2: "I should separate concerns"

Step 3: "I need an interface for flexibility"

Step 4: "Tax calculation should be configurable"

Step 5: "I should add a factory"

The Final "Architecture"

The Test-First Approach

Step 1: Write the simplest test

Step 2: Write the simplest implementation

Step 3: Add tests for edge cases

Step 4: Add a new requirement with a new test

Step 5: Handle complexity only when tests demand it

The Final Implementation

Comparing the Two Approaches

Why Tests Lead to Better Design

Tests punish unnecessary complexity

Tests force you to think about inputs and outputs

Tests document behavior

Tests enable safe refactoring

When Patterns Are Appropriate

Conclusion

The False Security of tRPC Type Safety: Catching Serialization Bugs at Compile Time

The Problem: A Tale of Two Types

Why Does This Happen?

The Quick Fix: Teaching SuperJSON About Dayjs

Building a Compile-Time Validator

Step 1: Define What "Safe" Means

Step 2: Create a Type-Level Validator

Step 3: Handle tRPC's Streaming (AsyncIterables)

Step 4: Apply to All Router Outputs

Step 5: The Assertion

The Complete Solution

How to Use This

What Errors Look Like

Getting Better Error Messages

Wrapping Up

Why Can't `result` Just Be a Simple String?

Step 5: The Optional Quantifier `?`

Step 8: The Alternation Operator `|`