Pure functions & side effects

Same input, same output, no surprises

A pure function is a function you can trust, like a pocket calculator. It follows two rules:

• Give it the same inputs, and it gives back the same answer. Every time.
• It changes nothing outside itself. Nobody outside the function can tell it ran, except by its answer.

The inputs are the values you pass in the brackets, called arguments. The answer is the value the function gives back with return, called the return value.

Pure functions are not fancy. This one is pure:

function add(a, b) {
  return a + b;
}

add(2, 3) always gives 5. Calling it does not print anything, save anything, or change anything. It also does not read anything that can change, like the clock.

You learned how to write functions in the functions basics lesson. Pure functions matter most when you pass them to array methods like map, filter, and reduce.

function double(price) {
  return price * 2;
}

console.log(double(4));
console.log(double(4));

Line 1 says double takes one input, price. Line 2 doubles it and returns the result. Lines 5 and 6 call double(4) twice. Both lines print 8.

The function reads nothing except price. It does not read the clock, a random number, or a variable from outside. It does not change anything either.

Here is what comes next in this lesson:

• You will find the hidden changes that make a function impure.
• You will replace a pure call with its answer and see that nothing changes.
• You will split a messy checkout function into a pure part and an outside part.
• You will see why pure functions make tests simple.

A side effect is anything a function does besides returning a value, that someone outside can notice. Common side effects in JavaScript:

• Changing an argument, an object, an array, or a variable outside the function.
• Writing somewhere: console.log, the page, browser storage, a file, or the network.
• Reading something that changes on its own: Date.now() (the current time), Math.random() (a random number), a variable outside the function, the page address, or a form field.
• Starting a timer, sending an event, or changing the browser's back-button history.

Reading the time counts. Reading a random number counts too. A function that only reads can still be impure, because its answer no longer depends only on its arguments.

console.log counts as well. It puts a new message in the console, and anyone can see that message.

let taxRate = 0.1;

function totalWithGlobal(price) {
  return price + price * taxRate;
}

function totalWithArgument(price, tax) {
  return price + price * tax;
}

console.log(totalWithGlobal(10));
taxRate = 0.2;
console.log(totalWithGlobal(10));
console.log(totalWithArgument(10, 0.1));

totalWithGlobal reads taxRate, a variable outside the function. Line 11 prints 11. Line 12 changes taxRate to 0.2. Now line 13 makes the very same call, but prints 12.

totalWithArgument gets the tax in its brackets instead. Line 14 passes 0.1, so it prints 11 again. Date.now() and Math.random() are hidden inputs in the same way as taxRate.

1let counter = 0;2 3function addTax(price) {4  return price * 1.1;5}6 7function stampedTotal(price) {8  return price + Date.now();9}10 11function luckyDiscount(price) {12  return price - Math.random();13}14 15function countCalls(price) {16  counter += 1;17  return price + counter;18}19 20function announce(price) {21  console.log("checking", price);22  return price;23}24 25function addItem(cart, item) {26  cart.push(item);27  return cart.length;28}

The checker calls each small function twice with the same input. Look at two things:

• Did the answer change? Then the function is impure.
• Did something outside change, even with the same answer? Then the function is impure too.

So purity is not only about the return value. It is about everything the outside world can notice.

You can replace a pure call with its answer, and the program still does the same thing. The long name for this is referential transparency.

For example, add(2, 3) is pure and gives 5. So anywhere you see add(2, 3), you could write 5 instead. The program would behave the same.

1function add(a, b) {2  return a + b;3}4 5const total = add(2, 3) * add(2, 3);Run6const replaced = 5 * 5;7console.log(total);8console.log(replaced);

This is why pure functions are easy to read. You can understand one line by looking only at that line.

The impure counter is different. To know what nextCount() gives, you must ask:

• How many times has it run already?
• Did any other code change counter?

Once the answer depends on questions like these, you can't replace the call with one fixed value.

Real apps need side effects. A checkout page has to:

• read the cart;
• know the current time;
• maybe pick a random discount;
• save the order;
• update the screen.

So the goal is not to remove side effects. The goal is to move them to the edges of your code. Then the middle is a plain calculation.

Two names describe this split:

• The shell is the outer code. It does the side effects: it reads the page, the time, and random numbers, and it saves and shows results.
• The core is the inner code. It is pure. It gets plain values as arguments and returns a plain value.

function cartTotal(cart, discount) {
  const subtotal = cart.reduce(
    (total, item) => total + item.price * item.quantity,
    0,
  );
  return subtotal - discount;
}

const cart = [
  { name: "Notebook", price: 12, quantity: 2 },
  { name: "Pen", price: 3, quantity: 3 },
];
console.log(cartTotal(cart, 5));

reduce goes through the cart one item at a time and keeps a running total. For each item, it adds price times quantity. That gives 24 for the notebooks and 9 for the pens.

The cart and the discount both come in as arguments. The total is 33, minus the discount of 5. So line 13 prints 28, every time. A shell can read the real cart and pass it in. This function never has to reach outside.

1const globalCart = [Run2  { name: "Notebook", price: 12, quantity: 2 },3  { name: "Pen", price: 3, quantity: 3 },4];5 6function checkoutSummary() {7  const subtotal = globalCart.reduce(8    (sum, item) => sum + item.price * item.quantity,9    0,10  );11  const discount = Math.random() < 0.5 ? 5 : 0;12  return {13    subtotal,14    discount,15    placedAt: new Date(Date.now()).toISOString(),16    total: subtotal - discount,17  };18}19 20console.log(checkoutSummary());

Compare the two versions in the replay. The first one reaches outside for the cart, the time, and a random number. The second one, summarize, gets all three as arguments:

• cart: the items to add up.
• now: the current time, as text.
• rng: a function that gives a random number. The name is short for "random number generator".

In a test, you pass a fixed time and an rng that always gives the same number. In the real app, the shell passes the real time and Math.random.

A test is a small program that calls your code and checks the answer. A good test gives the same result every time it runs. Pure functions make that easy:

• You pass in known inputs.
• You check the return value.
• The test doesn't care what time it is, or which test ran before it.

An impure function is harder. The test may need fake timers, fake random numbers, a fake page, or a fake network. It may also need to reset outside variables after each run.

1const cart = [{ price: 10, quantity: 2 }];2const fixedNow = "2026-09-25T09:00:00.000Z";3const fixedRng = () => 0.25;4 5summarize(cart, fixedNow, fixedRng);6summarize(cart, fixedNow, fixedRng);

The lab pretends to run two tests. The pure test uses a fixed random number, so it passes every time. The other test gets a different random number on each run, so its two totals don't match. A test that sometimes passes and sometimes fails is called flaky.

The same thing happens in real projects when code reads Date.now(), Math.random(), a saved value in another file, browser storage, or the page. Pass the changing value into a pure core instead. Then the test proves the behavior every time.

function cartTotal(cart, discount) {
  return cart.reduce(
    (total, item) => total + item.price * item.quantity,
    0,
  ) - discount;
}

function handleCheckout(cart) {
  const total = cartTotal(cart, 5);
  console.log("save order", total);
}

handleCheckout([{ price: 10, quantity: 2 }]);

cartTotal only calculates. handleCheckout is the shell: it calls cartTotal and then writes to the console. Line 13 calls it, and the console shows save order 15.

In a real app, handleCheckout could also read a form or save the order to a server. It would do that after the pure calculation is finished.

function formatPrice(amount) {
  return "$" + amount.toFixed(2);
}

console.log(formatPrice(3));
console.log(formatPrice(3));

Both calls print $3.00. The answer depends only on amount.

So you could save the first answer and reuse it the next time amount is 3. Saving answers to reuse them is called memoization, or caching. Never cache a function that secretly reads the time or a random number. The saved answer could be wrong later.

To mutate means to change an object or array that already exists.

The Objects & references lesson showed that passing an object or array to a function does not copy it. The caller and the function share the same one.

So if a function calls push or sort on an array it was given, the caller's array changes. The same happens if it sets a property, like user.name = "Ada", on an object it was given.

function addLabel(user, label) {
  user.labels.push(label);
  return user.labels.length;
}

const user = { labels: ["js"] };
console.log(addLabel(user, "pure"));
console.log(user.labels.join(","));

Line 2 pushes "pure" into user.labels. So line 7 prints 2, the new length. Line 8 reads the caller's own user and prints js,pure. The caller's object changed.

If addLabel returned a new object instead, the caller's user would stay as it was.

1function addTodo(todos, text) {2  todos.push(text);3  return todos;4}5 6function addTodoPure(todos, text) {7  return [...todos, text];8}9 10const list = ["learn"];11const changed = addTodo(list, "practice");12const copied = addTodoPure(list, "quiz");13console.log(list === changed);14console.log(list === copied);

The pure way is to return a new value and leave the old one alone:

• [...items, item] makes a new array with one more item.
• items.toSorted() returns a sorted copy, in browsers that support it.
• { ...user, name } makes a new object with a new name.
• For objects inside objects, copy each level you change.

Copying takes some work, and the next lesson, on immutability, goes deeper. The rule is simple: for a pure function, don't change data that other code can still see.

Where you'll use this

Pure functions fit code that turns data into other data. These are often pure:

• a search filter;
• a shopping-cart total;
• a form check, like "is this email valid?";
• a function that builds a web address;
• a function that formats a price or a date.

Then the code that runs on a click becomes a small shell. It reads the input, calls the pure function, and shows the result.

The table compares the two kinds of function. Each row asks one question; read across to see how each kind answers it.

Array methods from map, filter & reduce work best when the function you pass in is pure.

Closures need care. A closure is a function that remembers variables from where it was made. If it remembers a variable that keeps changing, it is impure. If it remembers a value that never changes, like a tax rate set once, it can still be pure.

Common misconceptions

Choose an answer, then read the explanations. The wrong answers explain common mistakes.

Key takeaways

• A pure function gives the same answer for the same inputs, and changes nothing outside itself.
• Side effects include changing outside data, writing (console, page, storage, network), and reading things that change, like the time, random numbers, or outside variables.
• You can replace a pure call with its answer, and the program still does the same thing.
• Keep the calculation in a pure core. Keep the clock, random numbers, page, storage, and network in a shell.
• Pure functions are easy to test, because everything they use comes in as an argument.

Up next: Immutability, which means changing data by making copies instead of changing the original.