← Map / Filter / Reduce Polyfills Browser APIs →

Immutability in JavaScript

Learn how to write predictable, bug-free code by embracing immutable data patterns.

Why Immutability Matters

Immutability is a core concept in functional programming that brings numerous benefits to your JavaScript applications.

Predictability
Data doesn't change unexpectedly

Debugging
Track changes through time

Performance
Enable memoization & optimization

Concurrency
Safe parallel processing

🔄 Mutability vs Immutability

Understand the fundamental difference between mutable and immutable approaches.

JavaScript Editor

// Understanding Mutability vs Immutability

// MUTABLE EXAMPLE
console.log("=== MUTABLE ===");
let mutableArray = [1, 2, 3];
let mutableObject = { name: "Alice", age: 25 };

// Modifying the original data
mutableArray.push(4);  // Original array is changed
mutableObject.age = 26; // Original object is changed

console.log("Mutable array after push:", mutableArray); // [1, 2, 3, 4]
console.log("Mutable object after update:", mutableObject); // {name: "Alice", age: 26}

// IMMUTABLE EXAMPLE
console.log("\n=== IMMUTABLE ===");
let immutableArray = [1, 2, 3];
let immutableObject = { name: "Alice", age: 25 };

// Creating new data instead of modifying
let newArray = [...immutableArray, 4]; // Spread operator
let newObject = { ...immutableObject, age: 26 }; // Spread operator

console.log("Original array:", immutableArray); // [1, 2, 3] - unchanged!
console.log("New array:", newArray); // [1, 2, 3, 4]
console.log("Original object:", immutableObject); // {name: "Alice", age: 25}
console.log("New object:", newObject); // {name: "Alice", age: 26}

// The Problem with Mutation
console.log("\n=== THE PROBLEM ===");
const originalUsers = [
  { id: 1, name: "Alice", role: "admin" },
  { id: 2, name: "Bob", role: "user" }
];

// ❌ Mutable approach (causes bugs)
function promoteUserMutable(users, userId) {
  const user = users.find(u => u.id === userId);
  user.role = "admin"; // Mutates original!
  return users;
}

const mutatedUsers = promoteUserMutable(originalUsers, 2);
console.log("Original users after mutation:", originalUsers[1]);
console.log("Mutated users:", mutatedUsers[1]);
console.log("Are they the same reference?", originalUsers[1] === mutatedUsers[1]);

// ✅ Immutable approach (safe)
const originalUsers2 = [
  { id: 1, name: "Alice", role: "admin" },
  { id: 2, name: "Bob", role: "user" }
];

function promoteUserImmutable(users, userId) {
  return users.map(user => 
    user.id === userId 
      ? { ...user, role: "admin" } // New object
      : user
  );
}

const updatedUsers = promoteUserImmutable(originalUsers2, 2);
console.log("\nOriginal users (immutable):", originalUsers2[1]);
console.log("Updated users:", updatedUsers[1]);
console.log("Are they the same reference?", originalUsers2[1] === updatedUsers[1]);

Key Differences:

Aspect	Mutable	Immutable
Data Changes	Modify original	Create new copy
Side Effects	Common	Avoided
Reference Equality	Same reference	New reference
Thread Safety	Not safe	Safe

🎯 Primitive vs Reference Types

JavaScript has different rules for different data types.

JavaScript Editor

// Primitive Types are Immutable, Reference Types are Mutable

console.log("=== PRIMITIVE TYPES (Immutable by nature) ===");

let str = "hello";
let newStr = str.toUpperCase(); // Returns NEW string

console.log("Original string:", str); // "hello"
console.log("New string:", newStr); // "HELLO"
console.log("Same?", str === newStr); // false

let num = 42;
let newNum = num + 1; // Returns NEW number

console.log("\nOriginal number:", num); // 42
console.log("New number:", newNum); // 43

// Primitive reassignment doesn't affect copies
let a = 10;
let b = a; // b gets the VALUE 10
a = 20;

console.log("\na:", a); // 20
console.log("b:", b); // 10 (unchanged!)

console.log("\n=== REFERENCE TYPES (Mutable) ===");

let arr1 = [1, 2, 3];
let arr2 = arr1; // arr2 references SAME array
arr1.push(4);

console.log("arr1:", arr1); // [1, 2, 3, 4]
console.log("arr2:", arr2); // [1, 2, 3, 4] (also changed!)
console.log("Same array?", arr1 === arr2); // true

let obj1 = { x: 1 };
let obj2 = obj1; // obj2 references SAME object
obj1.x = 2;

console.log("\nobj1:", obj1); // {x: 2}
console.log("obj2:", obj2); // {x: 2} (also changed!)

console.log("\n=== CREATING TRUE COPIES ===");

// Shallow copy techniques
const original = [1, 2, 3];
const shallowCopy1 = [...original]; // Spread operator
const shallowCopy2 = original.slice(); // slice()
const shallowCopy3 = Array.from(original); // Array.from()

original.push(4);
console.log("Original:", original); // [1, 2, 3, 4]
console.log("Copy 1:", shallowCopy1); // [1, 2, 3]
console.log("Copy 2:", shallowCopy2); // [1, 2, 3]
console.log("Copy 3:", shallowCopy3); // [1, 2, 3]

// The problem with nested objects (shallow copy limitation)
const nestedOriginal = {
  name: "Alice",
  address: {
    city: "NYC",
    zip: "10001"
  }
};

const shallowNestedCopy = { ...nestedOriginal };
shallowNestedCopy.address.city = "LA";

console.log("\nOriginal nested object:", nestedOriginal.address.city); // "LA" 😱
console.log("Shallow copy:", shallowNestedCopy.address.city); // "LA"
console.log("Same reference?", nestedOriginal.address === shallowNestedCopy.address); // true

Copying Techniques:

Shallow Copy:

{...obj} - Spread operator
Object.assign(, obj)
array.slice()
[...array]
Array.from(array)

Deep Copy:

JSON.parse(JSON.stringify(obj))
structuredClone(obj) (modern)
Lodash _.cloneDeep()
Custom recursive function

🔧 Immutable Operations

Learn how to perform common operations immutably.

JavaScript Editor

// Immutable Operations with Arrays and Objects

console.log("=== IMMUTABLE ARRAY OPERATIONS ===");

const originalArray = [1, 2, 3, 4, 5];

// Adding elements (immutably)
const withPush = [...originalArray, 6]; // Like push
const withUnshift = [0, ...originalArray]; // Like unshift
const withInsert = [
  ...originalArray.slice(0, 2), // First 2 elements
  2.5, // New element
  ...originalArray.slice(2) // Rest
];

console.log("Original:", originalArray);
console.log("With push (immutable):", withPush);
console.log("With unshift (immutable):", withUnshift);
console.log("With insert at index 2:", withInsert);

// Removing elements (immutably)
const withoutFirst = originalArray.slice(1); // Remove first
const withoutLast = originalArray.slice(0, -1); // Remove last
const withoutIndex2 = [ // Remove at index 2
  ...originalArray.slice(0, 2),
  ...originalArray.slice(3)
];

console.log("\nWithout first:", withoutFirst);
console.log("Without last:", withoutLast);
console.log("Without index 2:", withoutIndex2);

// Updating elements (immutably)
const updatedArray = originalArray.map((item, index) => 
  index === 2 ? item * 10 : item
);
console.log("\nUpdated at index 2:", updatedArray);

console.log("\n=== IMMUTABLE OBJECT OPERATIONS ===");

const originalObject = {
  name: "Alice",
  age: 25,
  address: {
    city: "NYC",
    zip: "10001"
  }
};

// Adding/Updating properties
const withNewProp = { ...originalObject, occupation: "Developer" };
const withUpdatedAge = { ...originalObject, age: 26 };
const withNestedUpdate = {
  ...originalObject,
  address: {
    ...originalObject.address,
    city: "LA"
  }
};

console.log("Original object:", originalObject);
console.log("With new property:", withNewProp);
console.log("With updated age:", withUpdatedAge);
console.log("With nested update:", withNestedUpdate);
console.log("Original nested unchanged?", originalObject.address.city); // "NYC"

// Removing properties (immutably)
const { age, ...withoutAge } = originalObject;
console.log("\nWithout age property:", withoutAge);

console.log("\n=== COMMON IMMUTABLE PATTERNS ===");

// Updating arrays of objects
const users = [
  { id: 1, name: "Alice", active: false },
  { id: 2, name: "Bob", active: true },
  { id: 3, name: "Charlie", active: false }
];

// Activate user with id 1
const activatedUsers = users.map(user =>
  user.id === 1 ? { ...user, active: true } : user
);

// Remove user with id 2
const filteredUsers = users.filter(user => user.id !== 2);

// Sort immutably
const sortedUsers = [...users].sort((a, b) => 
  a.name.localeCompare(b.name)
);

console.log("Original users:", users);
console.log("Activated user 1:", activatedUsers);
console.log("Without user 2:", filteredUsers);
console.log("Sorted users:", sortedUsers);

Array Operations:

// Add
            [...arr, item]           // push
            [item, ...arr]           // unshift

            // Remove
            arr.slice(1)             // shift
            arr.slice(0, -1)         // pop
            arr.filter(x => x !== value)

            // Update
            arr.map(x => x === old ? new : x)

            // Insert
            [...arr.slice(0, i), item, ...arr.slice(i)]

Object Operations:

// Add/Update
            {...obj, key: value}

            // Remove
            const {key, ...rest} = obj

            // Multiple updates
            {...obj, ...updates}

            // Nested update
            {
            ...obj,
            nested: {
                ...obj.nested,
                key: value
            }
            }

🏗️ Deep Immutability & Structural Sharing

Advanced patterns for efficient immutable updates.

JavaScript Editor

// Deep Immutability and Performance Considerations

console.log("=== DEEP CLONING ===");

const complexObject = {
  users: [
    { id: 1, profile: { name: "Alice", settings: { theme: "dark" } } },
    { id: 2, profile: { name: "Bob", settings: { theme: "light" } } }
  ],
  metadata: {
    createdAt: "2024-01-01",
    updatedAt: "2024-01-15"
  }
};

// Method 1: JSON.stringify/parse (simple but limited)
const deepCloneJSON = JSON.parse(JSON.stringify(complexObject));
deepCloneJSON.users[0].profile.settings.theme = "blue";

console.log("Original theme:", complexObject.users[0].profile.settings.theme); // "dark"
console.log("Clone theme:", deepCloneJSON.users[0].profile.settings.theme); // "blue"
console.log("Different reference?", 
  complexObject.users[0] !== deepCloneJSON.users[0]); // true

// Limitations of JSON method
const objWithSpecialTypes = {
  date: new Date(),
  func: () => console.log("hello"),
  undefined: undefined,
  infinity: Infinity,
  nan: NaN
};

const jsonClone = JSON.parse(JSON.stringify(objWithSpecialTypes));
console.log("\nJSON clone issues:");
console.log("Date becomes:", typeof jsonClone.date); // string
console.log("Function?", jsonClone.func); // undefined
console.log("Undefined?", jsonClone.undefined); // undefined (but property missing)
console.log("Infinity?", jsonClone.infinity); // null
console.log("NaN?", jsonClone.nan); // null

console.log("\n=== STRUCTURAL SHARING ===");

// Efficient updates with structural sharing
const largeDataset = {
  data: Array.from({length: 1000}, (_, i) => ({ id: i, value: i * 10 })),
  metadata: { count: 1000, version: "1.0" }
};

// Instead of deep cloning everything, share unchanged parts
function updateItem(dataset, id, newValue) {
  return {
    ...dataset, // Copy top level
    data: dataset.data.map(item =>
      item.id === id 
        ? { ...item, value: newValue } // New object for changed item
        : item // Keep reference to unchanged items
    )
  };
}

const updatedDataset = updateItem(largeDataset, 42, 999);
console.log("Same metadata reference?", 
  largeDataset.metadata === updatedDataset.metadata); // true
console.log("Same unchanged item reference?", 
  largeDataset.data[0] === updatedDataset.data[0]); // true
console.log("Different changed item reference?", 
  largeDataset.data[42] === updatedDataset.data[42]); // false

console.log("\n=== IMMUTABLE LIBRARIES PATTERN ===");

// Manual immutable update helper
function immutableUpdate(obj, path, value) {
  if (path.length === 0) return value;
  
  const [first, ...rest] = path;
  
  if (Array.isArray(obj)) {
    return obj.map((item, index) =>
      index === first ? immutableUpdate(item, rest, value) : item
    );
  } else if (obj !== null && typeof obj === 'object') {
    return {
      ...obj,
      [first]: immutableUpdate(obj[first], rest, value)
    };
  }
  
  return obj;
}

// Usage
const state = {
  user: {
    profile: {
      name: "Alice",
      preferences: {
        theme: "dark",
        notifications: true
      }
    }
  }
};

const newState = immutableUpdate(
  state,
  ["user", "profile", "preferences", "theme"],
  "light"
);

console.log("Original theme:", state.user.profile.preferences.theme); // "dark"
console.log("New theme:", newState.user.profile.preferences.theme); // "light"
console.log("Same user reference?", state.user === newState.user); // false
console.log("Same profile reference?", state.user.profile === newState.user.profile); // false
console.log("Same preferences reference?", 
  state.user.profile.preferences === newState.user.profile.preferences); // false

Structural Sharing Benefits:

Memory efficient: Unchanged parts share references
Fast equality checks: Compare references instead of deep equality
Predictable updates: Only changed parts get new references
Memoization friendly: Cache computations based on reference equality

🚀 Real-world Example: Redux State Management

JavaScript Editor

// Real-world Example: Redux-style State Management

console.log("=== REDUX-STATE MANAGEMENT EXAMPLE ===");

// Initial state (immutable by convention)
const initialState = {
  loading: false,
  error: null,
  users: [],
  filters: {
    activeOnly: false,
    sortBy: "name"
  }
};

// Action types
const ActionTypes = {
  FETCH_USERS_START: "FETCH_USERS_START",
  FETCH_USERS_SUCCESS: "FETCH_USERS_SUCCESS",
  FETCH_USERS_ERROR: "FETCH_USERS_ERROR",
  UPDATE_FILTERS: "UPDATE_FILTERS",
  UPDATE_USER: "UPDATE_USER"
};

// Reducer function (pure, immutable)
function usersReducer(state = initialState, action) {
  switch (action.type) {
    
    case ActionTypes.FETCH_USERS_START:
      return {
        ...state,
        loading: true,
        error: null
      };
    
    case ActionTypes.FETCH_USERS_SUCCESS:
      return {
        ...state,
        loading: false,
        users: action.payload,
        error: null
      };
    
    case ActionTypes.FETCH_USERS_ERROR:
      return {
        ...state,
        loading: false,
        error: action.payload
      };
    
    case ActionTypes.UPDATE_FILTERS:
      return {
        ...state,
        filters: {
          ...state.filters,
          ...action.payload
        }
      };
    
    case ActionTypes.UPDATE_USER:
      return {
        ...state,
        users: state.users.map(user =>
          user.id === action.payload.id
            ? { ...user, ...action.payload.updates }
            : user
        )
      };
    
    default:
      return state;
  }
}

// Action creators
const fetchUsersStart = () => ({ type: ActionTypes.FETCH_USERS_START });
const fetchUsersSuccess = (users) => ({
  type: ActionTypes.FETCH_USERS_SUCCESS,
  payload: users
});
const updateFilters = (filters) => ({
  type: ActionTypes.UPDATE_FILTERS,
  payload: filters
});
const updateUser = (id, updates) => ({
  type: ActionTypes.UPDATE_USER,
  payload: { id, updates }
});

// Simulate state changes
console.log("Initial state:", initialState);

const state1 = usersReducer(initialState, fetchUsersStart());
console.log("\nState after fetch start:", {
  loading: state1.loading,
  error: state1.error
});

const mockUsers = [
  { id: 1, name: "Alice", email: "alice@example.com", active: true },
  { id: 2, name: "Bob", email: "bob@example.com", active: false },
  { id: 3, name: "Charlie", email: "charlie@example.com", active: true }
];

const state2 = usersReducer(state1, fetchUsersSuccess(mockUsers));
console.log("\nState after fetch success:", {
  loading: state2.loading,
  usersCount: state2.users.length
});

const state3 = usersReducer(state2, updateFilters({ activeOnly: true }));
console.log("\nState after filter update:", {
  filters: state3.filters,
  sameUsersRef: state2.users === state3.users // true - structural sharing!
});

const state4 = usersReducer(state3, updateUser(2, { active: true }));
console.log("\nState after user update:", {
  user2: state4.users.find(u => u.id === 2),
  sameUser1Ref: state3.users[0] === state4.users[0] // true - unchanged!
});

console.log("\n=== IMMUTABLE ADVANTAGES ===");

// 1. Predictable state changes
console.log("1. State transitions are predictable");

// 2. Easy debugging (time travel)
const stateHistory = [initialState, state1, state2, state3, state4];
console.log("2. Can travel back in time:", stateHistory.length, "states saved");

// 3. Easy testing
function testReducer() {
  const startState = { loading: false, users: [] };
  const action = { type: ActionTypes.FETCH_USERS_START };
  const result = usersReducer(startState, action);
  
  console.log("3. Test result:", 
    result.loading === true && result.users === startState.users
    ? "✓ Pass" : "✗ Fail"
  );
}
testReducer();

// 4. Performance optimizations
console.log("4. Can memoize calculations:");
function getActiveUsers(users) {
  console.log("Calculating active users...");
  return users.filter(u => u.active);
}

// Since users array reference only changes when users actually change,
// we can cache/memoize this calculation!

Redux Principles:

Single source of truth: Entire app state in one store
State is read-only: Only changed through actions
Changes via pure functions: Reducers produce new state
Immutable updates: Never mutate existing state

⚡ Performance Patterns

JavaScript Editor

// Performance Patterns and Optimization

console.log("=== PERFORMANCE CONSIDERATIONS ===");

// 1. Avoid unnecessary deep clones
const largeObject = {
  data: Array.from({length: 10000}, (_, i) => ({ id: i, value: Math.random() })),
  metadata: { version: "1.0" }
};

console.time("Deep clone with JSON");
const deepClone = JSON.parse(JSON.stringify(largeObject));
console.timeEnd("Deep clone with JSON");

console.time("Shallow clone with spread");
const shallowClone = { ...largeObject };
console.timeEnd("Shallow clone with spread");

// 2. Use immutable patterns for lists
console.log("\n=== IMMUTABLE LIST PATTERNS ===");

class ImmutableList {
  constructor(items = []) {
    this.items = items;
  }
  
  push(item) {
    return new ImmutableList([...this.items, item]);
  }
  
  update(index, updater) {
    return new ImmutableList(
      this.items.map((item, i) => 
        i === index ? updater(item) : item
      )
    );
  }
  
  filter(predicate) {
    return new ImmutableList(this.items.filter(predicate));
  }
  
  get(index) {
    return this.items[index];
  }
  
  get size() {
    return this.items.length;
  }
}

const list1 = new ImmutableList([1, 2, 3]);
const list2 = list1.push(4);
const list3 = list2.update(0, x => x * 10);

console.log("List1:", list1.items);
console.log("List2:", list2.items);
console.log("List3:", list3.items);
console.log("All different?", list1 !== list2 && list2 !== list3);

// 3. Memoization with immutability
console.log("\n=== MEMOIZATION ===");

const memoize = (fn) => {
  const cache = new WeakMap();
  return (arg) => {
    if (!cache.has(arg)) {
      cache.set(arg, fn(arg));
    }
    return cache.get(arg);
  };
};

const expensiveCalculation = (data) => {
  console.log("Performing expensive calculation...");
  return data.reduce((sum, item) => sum + item.value, 0);
};

const memoizedCalc = memoize(expensiveCalculation);

const data1 = [{ value: 1 }, { value: 2 }, { value: 3 }];
const data2 = [{ value: 1 }, { value: 2 }, { value: 3 }]; // Same values, different reference
const data3 = data1; // Same reference

console.log("Result 1:", memoizedCalc(data1));
console.log("Result 2:", memoizedCalc(data2)); // Recalculates (different reference)
console.log("Result 3:", memoizedCalc(data3)); // Uses cache (same reference)

// 4. Persistent data structures pattern
console.log("\n=== PERSISTENT DATA STRUCTURES ===");

const persistentArray = createPersistentArray([1, 2]);
const v1 = persistentArray.push(3);
const v2 = persistentArray.push(4);

console.log("Version", persistentArray.getVersion(), ":", persistentArray.getCurrent());
console.log("Revert to version", v1, ":", persistentArray.revertTo(v1).getCurrent());
console.log("Version", v2, "from history:", persistentArray.get(v2));

console.log("\n=== WHEN TO USE IMMUTABILITY ===");

const useCases = [
  { scenario: "State management (Redux, React state)", recommendation: "✅ Always" },
  { scenario: "Configuration objects", recommendation: "✅ Recommended" },
  { scenario: "High-frequency updates (games, animations)", recommendation: "❌ Avoid" },
  { scenario: "Large datasets with few updates", recommendation: "✅ Good" },
  { scenario: "Concurrent programming", recommendation: "✅ Essential" },
  { scenario: "Simple helper functions", recommendation: "⚡ Use judgment" }
];

console.table(useCases);

When to Use Immutability:

✅ State management libraries
✅ Configuration objects
✅ Concurrent operations
✅ Data transformation pipelines
✅ Functional programming

When to Be Cautious:

❌ High-frequency updates (games)
❌ Memory-constrained environments
❌ Large object deep clones
❌ Performance-critical loops
⚡ Simple local variables

🛠️ Immutability Tools & Libraries

Immer

Create immutable state by mutating a draft. Best for Redux reducers and complex updates.

npm install immer

Immutable.js

Persistent immutable data structures. Great for large datasets with frequent updates.

npm install immutable

Redux Toolkit

Built-in immutable update patterns with Immer. Standard for modern Redux.

npm install @reduxjs/toolkit

Native JavaScript Methods:

Object.freeze() - Shallow immutability
Object.seal() - Prevent adding/removing
Object.preventExtensions() - Prevent adding

structuredClone() - Native deep clone
Spread operator (...)
Array.prototype methods

Mastered Immutability?

You've learned how to write predictable, maintainable code with immutable patterns. These concepts are essential for modern JavaScript development.

← Back to Array Methods Next: Classes & OOP →

← Map / Filter / Reduce Polyfills Browser APIs →

JavaScript Tutorial

Immutability in JavaScript

Why Immutability Matters

🔄 Mutability vs Immutability

Key Differences:

🎯 Primitive vs Reference Types

Copying Techniques:

🔧 Immutable Operations

Array Operations:

Object Operations:

🏗️ Deep Immutability & Structural Sharing

Structural Sharing Benefits:

🚀 Real-world Example: Redux State Management

Redux Principles:

⚡ Performance Patterns

When to Use Immutability:

When to Be Cautious:

🛠️ Immutability Tools & Libraries

Immer

Immutable.js

Redux Toolkit

Native JavaScript Methods:

Mastered Immutability?

Follow Us

Our Tools

Our Company

Special Tools