UI Algorithms: A Tiny Undo Stack

· 22 Mar 2025

I’ve needed this before - a couple of times. Third time I figured I needed something small, nimble - yet complete. And - at the same time - wondering about how to do it in a very simple manner. I think it worked out great, so let’s dig in.

Most UIs will have some form of undo functionality. Now, there are generally two forms of it: undo stacks and version histories. A “version history” is what Photoshop history gives you - the ability to “paint through” to a previous state of the system. You can add five paint strokes, and then reveal a stroke you have made 4 steps back.

But most apps won’t need that. What you will need is an undo stack, which can be specced out as follows:

An undoable action gets performed and gets pushed onto the stack.
If undo is requested, the stack is popped and the rollback action gets applied for the popped action.
If an action was undone, you can redo that action. If you have undone 2 actions, you can redo 2 actions.
If you push an undoable action onto the stack in presence of actions that can be redone, they get discarded - there is no branching, remember?

If you are curious how “the big guys” used to do it - check out the NSUndoManager documentation

So, as I usually like to do, I want to understand the API that would be optimal. For this use case - drawing - I had the following workflow:

When you draw a stroke the input points get added to currentStroke
When you release the pen the currentStroke gets appended to strokes and reset for the next stroke.

I wanted something like this:

let addStroke = () => strokes.push(currentPaintStroke);
let removeStroke = () => strokes.pop();
undoThing.push(addStroke, removeStroke);

// then, on user action
undoThing.undo(); // calls removeStroke()
undoThing.redo(); // calls strokes.push(...) again

The perils of stack pointers

Simplest thing in the world. Now, if you look at most recommended (and some existing!) implementations of an undo stack, you will find they usually make use of a stack with a pointer. Like here and here - you would have a stack, usually represented as a JS array, and some kind of pointer or an index that you would use to index into it.

And while it is workable and standard, it just didn’t jive with me well. See, using an index into an array usually makes JS code susceptible to two things, which bite me every single time:

Indexing into a nonexistent index - hello undefined checks
Mistakes in offsets when calling Array.slice and Array.splice. Oh, and confusing slice and splice, of course.

The fact that Ruby and JS have different semantics for slice - one uses the index bounds, the other uses two offsets - doesn’t help things. And what happens if an API uses offsets into a vector? Exactly: confusion whether those offsets are inclusive or exclusive. Oh, and the offsets change after you mutate the array, which makes it even more painful.

Could we not index?

So what came to mind was this: we effectively have two stacks, not one. We have an undoStack (things that can be rolled back) and a redoStack - things that can be rolled forward. All the things we do with our undo-redo actions actually do not change the pointer - they move things from one stack to another. And rules change between these two stacks! We erase the redoable actions when we add a new undoable action, remember? So while an undoable stack will rarely get “nullified”, the redoable stack likely will be nullified frequently.

Once this became clear, the implementation practically wrote itself:

function createUndoStack() {
  let past = [];
  let future = [];

  return {
    push(doFn, undoFn) {
      doFn();
      past.push({doFn, undoFn});
      // Adding a new action wipes the redoable steps
      future.length = 0;
    },
    undo() {
     let action = past.pop();
     if (action) {
       action.undoFn();
       future.unshift(action);
     }
    },
    redo() {
      let action = future.shift();
      if (action) {
        action.doFn();
        past.push(action);
      }
    }
  };
}

So instead of trying to save resources by having just one array (and miserably failing with off-by-one index errors), we can embrace dynamically sized arrays and just forget indices altogether. Neat!

Let’s add a couple more methods to display our UI:

  get canUndo() {
    return past.length > 0;
  },
  get canRedo() {
    return future.length > 0;
  }

There is a catch with our implementation though. JS has rather interesting lexical scoping rules: what is defined in the scope of the definition of the function will be referenced from within the function. This means that when we start pulling a new currentStroke our undoFn closure will not use a copy of the currentStroke it was created with, but our current one. And our doFn and undoFn must satisfy an important guarantee: they must be idempotent. No matter what the state of the surrounding system is, appending the currentStroke should always append the stroke the redoFn was created for.

If we do not take care of this, the following doFn:

let doFn = () => strokes.push(currentStroke)

is going to grab the currentStroke from the surrounding scope (whatever its value is) and append it to the strokes array. The currentStroke at that time may be just empty. To avoid this behavior, we want our doFn to use a cloned copy of the currentStroke - current at time of definition of doFn, and we want it to do so always. If your undoable action is some kind of delete (“pop”) you want the reverse for your undoFn - the undo function must push the deleted object back into the array, and not mutate it in any way. To create a deep copy of our currentStroke, modern JS offers us a feature called structuredClone(). We can use the ... rest parameters to package any arguments into one array, which we will then clone:

  push(doFn, undoFn, ...withArgumentsToClone) {
    const clonedArgs = structuredClone(withArgumentsToClone);
    const action = {
      doWithData() {
        doFn(...clonedArgs);
      },
      undoWithData() {
        undoFn(...clonedArgs);
      },
    };
    action.doWithData();
  
    // Adding a new action wipes the redoable steps
    past.push(action);
    future.length = 0;
  }

and we’ll amend our functions accordingly. Instead of closuring over currentStroke we’ll make it an argument:

let appendStroke = strokes.push.bind(strokes);
undoStack.push(appendStroke, () => strokes.pop(), currentStroke);

with the push() of our undoStack taking care of making a deep clone for us. Nice!

The complete definition then becomes:

function createUndoStack() {
  const past = [];
  const future = [];
  return {
    push(doFn, undoFn, ...withArgumentsToClone) {
      const clonedArgs = structuredClone(withArgumentsToClone);
      const action = {
        doWithData() {
          doFn(...clonedArgs);
        },
        undoWithData() {
          undoFn(...clonedArgs);
        },
      };
      action.doWithData();

      // Adding a new action wipes the redoable steps
      past.push(action);
      future.length = 0;
    },
    undo() {
      let action = past.pop();
      if (action) {
        action.undoWithData();
        future.unshift(action);
      }
    },
    redo() {
      let action = future.shift();
      if (action) {
        action.doWithData();
        past.push(action);
      }
    },
    get undoAvailable() {
      return past.length > 0;
    },
    get redoAvailable() {
      return future.length > 0;
    },
    clear() {
      past.length = 0;
      future.length = 0;
      return true;
    }
  }
}

export {createUndoStack};

Robust, small, and no indexing errors. My jam.

UI Algorithms: A Tiny Undo Stack

The perils of stack pointers

Could we not index?

The call-by-sharing problem