Immutable by Default: Practical TypeScript Patterns

Value tables → unions you can trust

Instead of scattering string literals across your code, freeze them in one place and let TypeScript do the heavy lifting.

const FEATURES = ['posts', 'comments', 'users', 'groups'] as const
const OPERATIONS = ['create', 'read', 'update', 'delete'] as const

type Feature = (typeof FEATURES)[number]
type Operation = (typeof OPERATIONS)[number]
type Permission = `${Feature}:${Operation}`

const buildPermissions = (
  features: readonly Feature[],
  operations: readonly Operation[],
): readonly Permission[] =>
  features.flatMap((f) => operations.map((o) => `${f}:${o}` as const))

const PERMISSIONS = buildPermissions(FEATURES, OPERATIONS) satisfies readonly Permission[]

Whenever you add a new feature or operation, the compiler updates the entire permission set. No typos, no missed strings. Just one definition, everywhere consistent.

This pattern scales beyond static permissions. Here’s a real-world example from a Todo app: the filter state that powers both our business logic and the UI tabs.

export const FILTER_STATE = {
  all: 'all',
  done: 'done',
  notDone: 'not-done',
} as const

export type TodoFilter = (typeof FILTER_STATE)[keyof typeof FILTER_STATE]

const filterFunctions = {
  [FILTER_STATE.all]: (todos: Todo[]) => todos,
  [FILTER_STATE.done]: (todos: Todo[]) => todos.filter((t) => t.isDone),
  [FILTER_STATE.notDone]: (todos: Todo[]) => todos.filter((t) => !t.isDone),
} as const satisfies Record<TodoFilter, (todos: Todo[]) => Todo[]>

And then in the UI:

<Tabs.Root value={filter} onValueChange={(d) => onFilterChange(d.value as TodoFilter)}>
  <Tabs.List>
    <Tabs.Trigger value={FILTER_STATE.all}>All</Tabs.Trigger>
    <Tabs.Trigger value={FILTER_STATE.notDone}>Not Done</Tabs.Trigger>
    <Tabs.Trigger value={FILTER_STATE.done}>Done</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value={filter}>{children}</Tabs.Content>
</Tabs.Root>

👉 Why this works so well:

• Single source of truth. The filter values ('all' | 'done' | 'not-done') live in one place. Add a new filter and the compiler forces you to update the functions and tabs.
• Types from values. TodoFilter is derived from FILTER_STATE. You can’t pass an invalid string anywhere—TypeScript will catch it.
• Immutable guarantees. Because the table is as const, the keys and values are frozen. No widening to plain string, no typos slipping through.
• End-to-end consistency. The same literal drives your state, your filter functions, and your UI. There’s zero chance of your logic and UI drifting apart.

It’s not just about immutability—it’s about locking values, types, and logic together. That’s what makes this pattern so powerful.

Template literal types that carry intent

Once you start treating strings as types, you can encode intent directly in them.

const isBlogUrl = (url: string): url is `/blog/${string}` => url.startsWith('/blog/')

Functions that expect a blog URL can now say so in the signature. That tiny guard helps future maintainers - or future you.

as const, explicit types, and satisfies without the traps

Here’s the trick: let as const infer, and use satisfies to validate. That way you get the best of both worlds: precise types and compile-time checks.

type Hex = '#ff0000' | '#00ff00' | '#0000ff'

const COLORS = ['#ff0000', '#00ff00', '#0000ff']
  as const satisfies readonly Hex[]

const COLOR_MAP = {
  red: '#ff0000',
  green: '#00ff00',
  blue: '#0000ff',
} as const satisfies Record<string, Hex>

This avoids accidental widening and keeps both values and types locked in sync.

const COLORS = ['#ff0000', '#00ff00', '#0000ff'] as const
// 1) ?^ const COLORS: readonly ["#ff0000", "#00ff00", "#0000ff"]

const COLORS = ['#ff0000', '#00ff00', '#0000ff'] as const satisfies Hex[]
// 2) ?^ const COLORS: ["#ff0000", "#00ff00", "#0000ff"]

const COLORS = ['#ff0000', '#00ff00', '#0000ff'] as const satisfies readonly Hex[]
// 3) ?^ const COLORS: readonly ["#ff0000", "#00ff00", "#0000ff"]

Function signatures that say “I won’t mutate your stuff”

Marking inputs readonly is a type-level promise: “This function won’t mess with your data.”

const sum = (values: readonly number[]): number =>
  values.reduce((total, v) => total + v, 0)

Same implementation as a mutable version, but infinitely clearer at the call site.

What’s more, readonly removes mutating methods from the type. You won’t even see push, sort, or splice in autocomplete, because those would break the promise. This forces you to:

• Copy first if you really need to mutate (const copy = [...values]).
• Or better: reach for the immutable ES2023 array methods like toSorted, toSpliced, or toReversed.

const sorted = values.toSorted() // immutable alternative to sort()
const withoutFirst = values.toSpliced(0, 1) // immutable splice
const reversed = values.toReversed() // immutable reverse

That’s the real win: the type system nudges you into writing pure functions and makes mutation an explicit choice, not an accident.

And when you expose collections, return immutable views:

const internalCache = new Map<string, number>()

export function getCache(): ReadonlyMap<string, number> {
  return internalCache
}

Internally flexible, externally safe.

Updating state without mutation

The real test of immutability is when you need to change something. The answer isn’t “never change” - it’s “return a new value instead of mutating the old one.”

type Todo = { id: string; title: string; isDone: boolean }

const toggleTodo = (todos: readonly Todo[], id: Todo['id']): readonly Todo[] =>
  todos.map((t) => (t.id === id ? { ...t, isDone: !t.isDone } : t))

const upsertById = <T extends { id: string | number }>(
  items: readonly T[],
  item: T,
): readonly T[] => {
  const index = items.findIndex((i) => i.id === item.id)
  return index === -1 ? items.concat(item) : items.with(index, item)
}

Pure functions. Clean diffs. No spooky side effects.

Deep immutability (only when you really need it)

When you use as const, the entire value becomes deeply immutable—no matter how many levels of nesting there are.

In contrast, Readonly<T> only makes the top-level properties immutable. Nested objects remain mutable unless you explicitly wrap them in Readonly<...> as well.

// `Readonly<T>` is shallow: only top-level properties are readonly.
const user: Readonly<{
  name: string
  profile: { greeting: string } // <- nested object is NOT readonly
}> = {
  name: 'Alice',
  profile: { greeting: 'Hello' },
}

user.name = 'Bob'
// ^ Error: `user.name` is readonly (top-level)

user.profile = { greeting: 'Hi' }
// ^ Error: `user.profile` is readonly as a top-level property (can’t reassign the object)

user.profile.greeting = 'Hola'
// ^ OK: `profile` itself is readonly, but its inner fields are still mutable

In practice, shallow immutability is usually enough. But if you need deep immutability, you can define a utility type instead of wrapping each level in Readonly<T> manually:

type DeepReadonly<T> = T extends (...args: unknown[]) => unknown
  ? T
  : T extends object
    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
    : T

Exhaustive unions that fail loudly

When you pair immutability with discriminated unions, the compiler won’t let you forget a case.

type Msg =
  | { kind: 'info'; text: string }
  | { kind: 'success'; text: string }
  | { kind: 'warning'; text: string; code: number }
  | { kind: 'error'; text: string; stack?: string }

const renderMessage = (m: Readonly<Msg>) => {
  switch (m.kind) {
    case 'info':
    case 'success':
      return m.text
    case 'warning':
      return `${m.code}: ${m.text}`
    case 'error':
      return m.stack ?? m.text
    default: {
      const _exhaustive: never = m
      return _exhaustive
    }
  }
}

Compile-time guarantees, runtime peace of mind.

Interop with Validators

Immutable tuples don’t just help TypeScript; they also make runtime validation a breeze.

import { z } from 'zod'

const STATUSES = ['draft', 'published', 'archived'] as const

export type Status = (typeof STATUSES)[number]
export const StatusSchema = z.enum(STATUSES)

One definition, two worlds covered: compile-time types and runtime checks. No drifting copies, no sync issues.