Overview
This page is the atomic definition. The general-principles deep-dive lives at 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
// 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
- general-principles - the broader principles that include immutability.
- side-effect - mutating shared data is the canonical side effect.
- idempotent - idempotent operations are easier with immutable inputs.
- swift - Swift’s value-type model enforces immutability by default.
- react-state-management - React relies on immutable updates for change detection.
Citing this term
See Immutable data (llmbestpractices.com/glossary/immutable-data).