Part 1: Pure Functions and Immutability - Predictable Code

Introduction

My first production bug came from a "simple" utility function that cached results in a global variable. In single-threaded tests, it worked perfectly. In production with concurrent requests, it returned wrong data to users. Customer A got customer B's account balance. The function wasn't pure - it had hidden state and side effects.

I refactored it to a pure function. No global state. Same input always produced same output. No side effects. The bug disappeared. Tests became trivial. That's when I understood the power of pure functions and immutability.

This article teaches you to write predictable, testable code through pure functions and immutable data structures, using real TypeScript backend examples.

What is a Pure Function?

A pure function has two properties:

1. Deterministic - Same input always returns same output

2. No Side Effects - Doesn't modify external state or interact with the outside world

Impure Function

// Impure - depends on external state
let discount = 0.1;

function calculatePrice(basePrice: number): number {
    return basePrice * (1 - discount);  // Depends on external 'discount'
}

console.log(calculatePrice(100));  // 90

discount = 0.2;  // Someone changed discount!
console.log(calculatePrice(100));  // 80 - same input, different output!

Problems:

• Output depends on external state

• Hard to test (must control discount)

• Hard to reason about (must track all changes to discount)

• Cannot parallelize safely

Pure Function

// Pure - all inputs explicit
function calculatePrice(basePrice: number, discount: number): number {
    return basePrice * (1 - discount);
}

console.log(calculatePrice(100, 0.1));  // 90
console.log(calculatePrice(100, 0.1));  // 90 - always same!
console.log(calculatePrice(100, 0.2));  // 80

// Easy to test
function testCalculatePrice() {
    const result = calculatePrice(100, 0.1);
    console.assert(result === 90, 'Price calculation failed');
}

Benefits:

• Deterministic - same input, same output

• Easy to test - just verify input/output

• Easy to reason about - no hidden dependencies

• Can parallelize safely

Side Effects

Side effects are interactions with the outside world:

// Impure - has side effects
function processOrder(order: Order): void {
    // Side effect 1: Console logging
    console.log(`Processing order ${order.id}`);
    
    // Side effect 2: Database write
    database.save(order);
    
    // Side effect 3: API call
    fetch('https://api.example.com/notify', {
        method: 'POST',
        body: JSON.stringify(order)
    });
    
    // Side effect 4: Modifying input
    order.processed = true;
}

Common side effects:

• Reading/writing files or databases

• Network requests

• Console logging

• Modifying input arguments

• Modifying global variables

• Random number generation

• Current time/date

Managing Side Effects

Pure functions can't eliminate side effects (we need them!), but we can isolate them:

// Pure - calculates what to do
function calculateOrderTotal(items: OrderItem[]): number {
    return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Pure - creates order data
function createOrderData(
    items: OrderItem[],
    userId: string,
    timestamp: Date
): Order {
    return {
        id: generateOrderId(userId, timestamp),
        userId,
        items,
        total: calculateOrderTotal(items),
        createdAt: timestamp,
        processed: false
    };
}

// Impure - isolated side effects
async function saveOrder(order: Order): Promise<void> {
    console.log(`Saving order ${order.id}`);
    await database.save(order);
    await notifyCustomer(order);
}

// Orchestration - side effects at the edge
async function processOrder(items: OrderItem[], userId: string): Promise<void> {
    // Pure computation
    const orderData = createOrderData(items, userId, new Date());
    
    // Side effects isolated here
    await saveOrder(orderData);
}

Immutability

Immutable data cannot be changed after creation. Instead of modifying, we create new values.

The Problem with Mutations

interface User {
    id: string;
    name: string;
    email: string;
    roles: string[];
}

// Mutable approach - dangerous!
function addRole(user: User, role: string): void {
    user.roles.push(role);  // Mutates original!
}

const admin: User = {
    id: '1',
    name: 'Alice',
    email: '[email protected]',
    roles: ['user']
};

addRole(admin, 'admin');
console.log(admin.roles);  // ['user', 'admin'] - original modified!

// Problem: Who else has a reference to 'admin'?
// Did we just break something elsewhere?

Problems:

• Hard to track changes

• Race conditions in async code

• Difficult to implement undo/redo

• Cannot safely share data

• Breaks time-travel debugging

Immutable Approach

// Immutable - returns new object
function addRole(user: User, role: string): User {
    return {
        ...user,
        roles: [...user.roles, role]  // New array, old unchanged
    };
}

const admin: User = {
    id: '1',
    name: 'Alice',
    email: '[email protected]',
    roles: ['user']
};

const adminWithRole = addRole(admin, 'admin');

console.log(admin.roles);           // ['user'] - original unchanged!
console.log(adminWithRole.roles);   // ['user', 'admin'] - new object

Benefits:

• Predictable - old data never changes

• Safe to share across async operations

• Easy to implement undo/redo

• Enables time-travel debugging

• No race conditions on data

Real Example: User Profile Updates

I built a user profile service that needed to track changes:

interface UserProfile {
    id: string;
    username: string;
    email: string;
    preferences: {
        theme: string;
        language: string;
        notifications: boolean;
    };
    metadata: {
        lastLogin: Date;
        loginCount: number;
    };
}

// Immutable update functions
function updateEmail(profile: UserProfile, email: string): UserProfile {
    return {
        ...profile,
        email
    };
}

function updateTheme(profile: UserProfile, theme: string): UserProfile {
    return {
        ...profile,
        preferences: {
            ...profile.preferences,
            theme
        }
    };
}

function recordLogin(profile: UserProfile, timestamp: Date): UserProfile {
    return {
        ...profile,
        metadata: {
            ...profile.metadata,
            lastLogin: timestamp,
            loginCount: profile.metadata.loginCount + 1
        }
    };
}

// Pure function - composes updates
function updateProfile(
    profile: UserProfile,
    updates: {
        email?: string;
        theme?: string;
        recordLogin?: Date;
    }
): UserProfile {
    let updated = profile;
    
    if (updates.email) {
        updated = updateEmail(updated, updates.email);
    }
    
    if (updates.theme) {
        updated = updateTheme(updated, updates.theme);
    }
    
    if (updates.recordLogin) {
        updated = recordLogin(updated, updates.recordLogin);
    }
    
    return updated;
}

// Usage
const originalProfile: UserProfile = {
    id: '1',
    username: 'alice',
    email: '[email protected]',
    preferences: {
        theme: 'light',
        language: 'en',
        notifications: true
    },
    metadata: {
        lastLogin: new Date('2024-01-01'),
        loginCount: 10
    }
};

const updatedProfile = updateProfile(originalProfile, {
    email: '[email protected]',
    theme: 'dark',
    recordLogin: new Date('2024-01-15')
});

console.log(originalProfile.email);  // '[email protected]' - unchanged
console.log(updatedProfile.email);   // '[email protected]'
console.log(updatedProfile.metadata.loginCount);  // 11

// Can keep history
const profileHistory = [
    originalProfile,
    updateEmail(originalProfile, '[email protected]'),
    updatedProfile
];

Real Example: Shopping Cart

interface CartItem {
    productId: string;
    name: string;
    price: number;
    quantity: number;
}

interface Cart {
    items: CartItem[];
    discountCode?: string;
}

// Pure functions for cart operations
function addItem(cart: Cart, item: CartItem): Cart {
    const existingIndex = cart.items.findIndex(i => i.productId === item.productId);
    
    if (existingIndex >= 0) {
        // Update existing item quantity
        const updatedItems = [...cart.items];
        updatedItems[existingIndex] = {
            ...updatedItems[existingIndex],
            quantity: updatedItems[existingIndex].quantity + item.quantity
        };
        
        return {
            ...cart,
            items: updatedItems
        };
    }
    
    // Add new item
    return {
        ...cart,
        items: [...cart.items, item]
    };
}

function removeItem(cart: Cart, productId: string): Cart {
    return {
        ...cart,
        items: cart.items.filter(item => item.productId !== productId)
    };
}

function updateQuantity(cart: Cart, productId: string, quantity: number): Cart {
    if (quantity <= 0) {
        return removeItem(cart, productId);
    }
    
    return {
        ...cart,
        items: cart.items.map(item =>
            item.productId === productId
                ? { ...item, quantity }
                : item
        )
    };
}

function applyDiscountCode(cart: Cart, code: string): Cart {
    return {
        ...cart,
        discountCode: code
    };
}

// Pure calculation
function calculateTotal(cart: Cart): number {
    const subtotal = cart.items.reduce(
        (sum, item) => sum + item.price * item.quantity,
        0
    );
    
    if (cart.discountCode === 'SAVE10') {
        return subtotal * 0.9;
    }
    
    return subtotal;
}

// Usage - completely predictable
let cart: Cart = { items: [] };

cart = addItem(cart, { productId: '1', name: 'Laptop', price: 1200, quantity: 1 });
cart = addItem(cart, { productId: '2', name: 'Mouse', price: 25, quantity: 2 });

console.log(calculateTotal(cart));  // 1250

cart = updateQuantity(cart, '2', 1);
console.log(calculateTotal(cart));  // 1225

cart = applyDiscountCode(cart, 'SAVE10');
console.log(calculateTotal(cart));  // 1102.5

// Original cart operations don't affect old references
const cartBeforeDiscount = removeItem(cart, '2');
console.log(calculateTotal(cartBeforeDiscount));  // 1080 (1200 * 0.9)

Immutable Array Operations

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

// Add to end - immutable
const withSix = [...numbers, 6];  // [1, 2, 3, 4, 5, 6]

// Add to start - immutable
const withZero = [0, ...numbers];  // [0, 1, 2, 3, 4, 5]

// Remove item - immutable
const without3 = numbers.filter(n => n !== 3);  // [1, 2, 4, 5]

// Update item - immutable
const doubled = numbers.map(n => n === 3 ? n * 2 : n);  // [1, 2, 6, 4, 5]

// Insert at index - immutable
const insertAt2 = [...numbers.slice(0, 2), 99, ...numbers.slice(2)];  // [1, 2, 99, 3, 4, 5]

// Original unchanged
console.log(numbers);  // [1, 2, 3, 4, 5]

Immutable Object Updates

interface Config {
    api: {
        baseUrl: string;
        timeout: number;
        retries: number;
    };
    features: {
        analytics: boolean;
        cache: boolean;
    };
}

const config: Config = {
    api: {
        baseUrl: 'https://api.example.com',
        timeout: 5000,
        retries: 3
    },
    features: {
        analytics: true,
        cache: false
    }
};

// Deep update - immutable
const updatedConfig: Config = {
    ...config,
    api: {
        ...config.api,
        timeout: 10000
    }
};

console.log(config.api.timeout);         // 5000 - original unchanged
console.log(updatedConfig.api.timeout);  // 10000

// Multiple updates
const fullyUpdated: Config = {
    ...updatedConfig,
    api: {
        ...updatedConfig.api,
        retries: 5
    },
    features: {
        ...updatedConfig.features,
        cache: true
    }
};

Real Example: API Response Transformation

interface ApiUser {
    id: number;
    username: string;
    email: string;
    created_at: string;  // API returns snake_case
    is_active: boolean;
}

interface User {
    id: string;
    username: string;
    email: string;
    createdAt: Date;  // We use camelCase and Date objects
    isActive: boolean;
}

// Pure transformation function
function transformUser(apiUser: ApiUser): User {
    return {
        id: apiUser.id.toString(),
        username: apiUser.username,
        email: apiUser.email,
        createdAt: new Date(apiUser.created_at),
        isActive: apiUser.is_active
    };
}

// Pure batch transformation
function transformUsers(apiUsers: ApiUser[]): User[] {
    return apiUsers.map(transformUser);
}

// Pure filtering and transformation
function getActiveUsers(apiUsers: ApiUser[]): User[] {
    return apiUsers
        .filter(user => user.is_active)
        .map(transformUser);
}

// Pure sorting
function sortUsersByDate(users: User[]): User[] {
    return [...users].sort((a, b) => 
        b.createdAt.getTime() - a.createdAt.getTime()
    );
}

// Easy to test - no setup needed!
function testTransformUser() {
    const apiUser: ApiUser = {
        id: 1,
        username: 'alice',
        email: '[email protected]',
        created_at: '2024-01-01T00:00:00Z',
        is_active: true
    };
    
    const user = transformUser(apiUser);
    
    console.assert(user.id === '1', 'ID transformation failed');
    console.assert(user.createdAt instanceof Date, 'Date transformation failed');
    console.assert(user.isActive === true, 'Active status failed');
}

Benefits of Pure Functions

1. Easy Testing

// Pure function - trivial to test
function calculateTax(amount: number, rate: number): number {
    return amount * rate;
}

// Test - no mocks, no setup
console.assert(calculateTax(100, 0.1) === 10);
console.assert(calculateTax(0, 0.5) === 0);
console.assert(calculateTax(50, 0) === 0);

2. Easy Debugging

// Pure function - output only depends on input
function processData(data: string[]): string[] {
    return data
        .filter(s => s.length > 0)
        .map(s => s.trim())
        .map(s => s.toLowerCase());
}

// Debug - just check input and output
const input = ['  Hello  ', '', 'WORLD'];
const output = processData(input);
console.log(output);  // ['hello', 'world']

3. Memoization

// Pure function - can cache results
function fibonacci(n: number): number {
    if (n <= 1) return n;
    return fibonacci(n - 1) + fibonacci(n - 2);
}

// Add memoization
function memoize<T extends (...args: any[]) => any>(fn: T): T {
    const cache = new Map<string, any>();
    
    return ((...args: any[]) => {
        const key = JSON.stringify(args);
        
        if (cache.has(key)) {
            return cache.get(key);
        }
        
        const result = fn(...args);
        cache.set(key, result);
        return result;
    }) as T;
}

const fastFibonacci = memoize(fibonacci);
console.log(fastFibonacci(40));  // Fast with caching!

4. Parallelization

// Pure functions - safe to run in parallel
async function processItems(items: string[]): Promise<string[]> {
    // Can safely parallelize - no shared state
    const results = await Promise.all(
        items.map(item => processItemPure(item))
    );
    
    return results;
}

function processItemPure(item: string): Promise<string> {
    return Promise.resolve(item.toUpperCase());
}

Best Practices

1. Make Dependencies Explicit

// Bad - hidden dependency
const TAX_RATE = 0.1;

function calculateTotal(price: number): number {
    return price * (1 + TAX_RATE);  // Hidden dependency
}

// Good - explicit dependency
function calculateTotal(price: number, taxRate: number): number {
    return price * (1 + taxRate);
}

2. Avoid Mutating Arguments

// Bad - mutates argument
function addProperty(obj: any, key: string, value: any): void {
    obj[key] = value;  // Mutates input!
}

// Good - returns new object
function addProperty<T>(obj: T, key: string, value: any): T & Record<string, any> {
    return { ...obj, [key]: value };
}

3. Use TypeScript readonly

interface User {
    readonly id: string;
    readonly email: string;
    readonly roles: readonly string[];
}

function addRole(user: User, role: string): User {
    return {
        ...user,
        roles: [...user.roles, role]
    };
}

// Compile error if trying to mutate
// user.id = 'new-id';  // Error!
// user.roles.push('admin');  // Error!

4. Separate Pure and Impure

// Pure - calculation
function calculateShippingCost(weight: number, distance: number): number {
    return weight * 0.5 + distance * 0.1;
}

// Pure - data preparation
function prepareOrderData(items: Item[], address: Address): OrderData {
    const weight = items.reduce((sum, item) => sum + item.weight, 0);
    const distance = calculateDistance(address);
    const shippingCost = calculateShippingCost(weight, distance);
    
    return {
        items,
        address,
        shippingCost,
        total: calculateTotal(items, shippingCost)
    };
}

// Impure - side effects at the edge
async function createOrder(items: Item[], address: Address): Promise<void> {
    const orderData = prepareOrderData(items, address);  // Pure
    await saveToDatabase(orderData);  // Impure
    await sendConfirmationEmail(orderData);  // Impure
}

What's Next

You now understand:

• Pure functions and their benefits

• Side effects and how to manage them

• Immutability and why it matters

• Immutable data transformations

• Testing and debugging pure functions

In Part 2: Higher-Order Functions and Composition, you'll learn to use functions as first-class citizens, master map/filter/reduce, compose small functions into powerful pipelines, and apply functional patterns to real data processing.

---

Based on building production TypeScript backend services, learning to eliminate bugs through pure functions and immutability.