---
title: "Immutable data"
slug: "immutable-data"
category: "glossary"
tags: ["glossary", "coding", "immutability", "functional", "concurrency"]
status: "stable"
last_updated: 2026-05-14
summary: "Immutable data is data that cannot be modified in place after creation; updates produce new values, which simplifies concurrency, caching, and reasoning."
related:
  [
    "[[coding/general-principles]]",
    "[[coding/swift]]",
    "[[glossary/side-effect]]",
    "[[glossary/idempotent]]",
    "[[coding/typescript]]",
    "[[frontend/react-state-management]]",
  ]
---

## Overview

This page is the atomic definition. The general-principles deep-dive lives at [[coding/general-principles]].

## Definition

Immutable data is data that cannot be modified in place after it is created. Any "update" returns a new value with the change applied, leaving the original untouched. Languages enforce immutability through value types (Swift `struct`, Rust by default), `const` bindings, frozen objects (`Object.freeze`), or persistent data structures (Immutable.js, Immer). Immutability eliminates a class of bugs caused by shared mutable state and makes equality checks cheap (compare references).

## When it applies

Default to immutable data for function arguments, returned values, and shared state across threads or components. Reach for mutable structures only when measured performance demands it.

## Example

```ts
// Mutable: caller can observe a change to the array.
function addUser(users: User[], u: User) {
  users.push(u)
  return users
}

// Immutable: caller's array is untouched.
function addUser(users: readonly User[], u: User) {
  return [...users, u]
}
```

## Related concepts

- [[coding/general-principles]] - the broader principles that include immutability.
- [[glossary/side-effect]] - mutating shared data is the canonical side effect.
- [[glossary/idempotent]] - idempotent operations are easier with immutable inputs.
- [[coding/swift]] - Swift's value-type model enforces immutability by default.
- [[frontend/react-state-management]] - React relies on immutable updates for change detection.

## Citing this term

> See [[glossary/immutable-data|Immutable data]] (llmbestpractices.com/glossary/immutable-data).

## Related

- [[coding/general-principles]]
- [[coding/swift]]
- [[frontend/react-state-management]]
- [[glossary/side-effect]]
- [[glossary/idempotent]]