immutability-patterns

Immutability Patterns

Create new objects instead of mutating existing ones. Immutability prevents shared-state bugs, makes code easier to reason about, and enables reliable change detection.

When to Use

• Writing any function that transforms data
• Updating React/Vue/Svelte state
• Working with Redux or other state management
• Reviewing code that modifies objects or arrays in place
• Any time .push(), .splice(), delete, or direct property assignment appears on shared data

Core Patterns

JavaScript/TypeScript: Object Updates

// WRONG: Mutation
function updateUser(user: User, name: string): User {
  user.name = name;  // Mutates the original!
  return user;
}

// CORRECT: Spread operator
function updateUser(user: User, name: string): User {
  return { ...user, name };
}

// CORRECT: Nested object update
function updateAddress(user: User, city: string): User {
  return {
    ...user,
    address: {
      ...user.address,
      city,
    },
  };
}

// CORRECT: Conditional field update
function toggleAdmin(user: User): User {
  return {
    ...user,
    role: user.role === "admin" ? "user" : "admin",
  };
}

JavaScript/TypeScript: Array Operations

// WRONG: Mutating arrays
function addItem(items: Item[], item: Item): Item[] {
  items.push(item);   // Mutates!
  return items;
}

// CORRECT: Immutable array operations
const added = [...items, newItem];                          // append
const prepended = [newItem, ...items];                      // prepend
const removed = items.filter((item) => item.id !== id);     // remove
const updated = items.map((item) =>                         // update
  item.id === id ? { ...item, name: "new" } : item
);
const inserted = [                                          // insert at index
  ...items.slice(0, index),
  newItem,
  ...items.slice(index),
];

TypeScript: Readonly Types

// Mark data as immutable at the type level
interface Config {
  readonly apiUrl: string;
  readonly timeout: number;
  readonly retries: number;
}

// Readonly arrays
function processItems(items: readonly Item[]): readonly Item[] {
  // items.push(x) -> TypeScript error!
  return items.filter((item) => item.active);
}

// Deep readonly utility
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

// Readonly records
const routes: Readonly<Record<string, string>> = {
  home: "/",
  login: "/auth/login",
  dashboard: "/app/dashboard",
};