Command-based undo for JS apps

I’ve always been fascinated by undo/redo in web applications. It’s a useful addition to nearly any app and arguably expected in complex ones. If it’s there, it becomes integral to how the product is used, like search or a command palette. And it’s invisible! Users can’t “see” it, but they generally have a good idea of what should happen when they use it. And as an implementor, it can be mind-melting.

If you’re dealing with a single component or a smaller-scoped project, there are libraries available for implementing undo that you can and should be using. If you’re building an app on the scale of something like Figma or TLDraw, then undo stops being a “feature” and starts becoming part of your architecture. Implementing undo is less about installing the right library and more about following the right patterns.

The command pattern is one that I’ve found to be the most flexible for robust undo implementation, but it’s been challenging to find practical examples to learn from. I always seem to first land on the simple examples and then jump straight to CRDTs without anything in between. I wanted to dig into this pattern more and see how it could be applied using everyday, “boring” frontend tooling. This is admittedly a bit of a brain dump for my later self, but hopefully others will find it useful.

If you’re interested in going straight into some code, check out the repository and demo.

The memento pattern

First, a quick primer on the memento pattern. It’s a state-based approach that deals with undo/redo from the perspective of state changes. The idea is save a snapshot of the undoable state for every change made. Undoing means restoring a previous state. If you’ve built a lot of Redux apps, this approach will feel familiar. It’s a straightforward and generalizable approach and it’s the official recommendation from the Redux docs. I’ve used this approach with good success. If it works for you I’d recommend it.

{
  counter: {
    past: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
    present: 10,
    future: []
  }
}

There’s a couple of downsides with this pattern though:

1. You need to store your undoable state for every change, which could get excessively large. In practice, I’ve never had an issue with this. If you’re following Redux/React typical best practices, you are likely performing immutable updates and achieving some structural sharing.
2. You’re forced to store all of your undoable state in a single object. If your application state is spread around to multiple stores like Jotai atoms or Tanstack query cache, this may not work for you.
3. After an undo, you might need to persist a save to the backend in a format that’s different from your undoable state shape. Knowing the state snapshot is not enough information to persist the change.
4. You might need to attach other metadata to the change to perform side effects. For example, re-focusing an input element after undoing an edit. Another example might be providing a human-readable description of a change.
5. It’s all-or-nothing. Every action has to be undoable. If you perform an action on the state that is not undoable, you have to clear the undo stack.

The command pattern

Contrasted with the state-based approach above, the command pattern is more action-based. Undo/redo is handled by defining commands that can execute and undo a change.

const myCommand = {
  exec() {
    // ...
  },
  undo() {
    // ...
  },
};

To make a change on the system, a command is dispatched to a central handler to call the exec or undo functions and move the command between an undo stack and a redo stack.

function dispatch(command) {
  command.exec();
  undoStack.push(command);
}

function undo() {
  const command = undoStack.pop();
  if (command) {
    command.undo();
    redoStack.push(command);
  }
}

function redo() {
  const command = redoStack.pop();
  if (command) {
    command.exec();
    undoStack.push(command);
  }
}

This approach is more flexible, but less generalizable. Ultimately, the command pattern is not a pattern specific to undo implementations, it’s more of a general architectural pattern. This is where we veer off into “how do I build undo” to “how do I build an event-driven, command-based architecture (that also has undo)?” It’s hard to describe a command-based undo system that’s just focused on undo because it has an effect on your whole system.

Keeping a history log

The state-based approach and the action-based approach are different in how they approach undo, but they share a common pattern: keeping a log. This seems obvious to point out, but to undo a change you have to know that a change occurred and you have to know a few details about how it happened. The entries in the log are what we use to derive the current state from past user actions. How the entries in the log are structured can vary, but typically you have an undoStack and a redoStack. You might also see these named as past and future.

In the memento pattern, it’s a log of state snapshots. The log isn’t concerned with how the snapshots were created, only the end result. This is nice because the how doesn’t inject its way into the rest of the architecture. It can be contained to a single component or service and you can fairly easy “upgrade” a piece of state to be undoable.

In the command pattern, the log holds instances of commands, but I prefer to think of them as just “events” or “entries”. The events contain any information you might need to execute or undo an action. This could be functions to make state like .exec() or .undo() or any other plain data you want to attach to the event.

const undoStack = [
  {
    params: {
      id: "xxx",
      previous: "foo",
      next: "bar",
    },
    exec() {
      state[params.id].value === params.next;
    },
    undo() {
      state[params.id].value === params.previous;
    },
  },
];

In contrast to the memento pattern, commands do care about how the state changes are applied. The exec and undo functions on a command typically need to work together for the implementation to work as expected.

Using Patches

One way to retain some of the advantages of the memento pattern could be to use patches in your event log. Patches can be a more compact way to describe state changes without needing to store the entire state. Using a library like Immer, you could build something like this:

import { produceWithPatches, applyPatches } from "immer";

const myCommand = {
  params: {
    id: "xxx",
    previous: "foo",
    next: "bar",
  },
  exec(params) {
    const [nextState, patches, inversePatches] = produceWithPatches((state) => {
      state[params.id].value === params.next;
    });

    setState(nextState);

    // Return this for the `undo` call
    return { patches, inversePatches };
  },
  undo(logEntry) {
    // Apply the inverse patches to revert the `exec` function
    const nextState = applyPatches(state, logEntry.inversePatches);
    setState(nextState);
  },
};

function dispatch(command) {
  const payload = command.exec(command.params);
  const entry = {
    commmand,
    payload,
  };
  undoStack.push(entry);
}

function undo() {
  const entry = undoStack.pop();
  if (entry) {
    entry.command.undo(entry);
    // TODO: What's the redoStack here?
  }
}

In this example, there’s a new thing called an “entry” that represents a command that’s been executed. Another name might be a “transaction”. The command exec function returns the patches and inversePatches that can be used later to undo it. If you can constrain all of your commands to adhere to this pattern, you can abstract this even more to make commands very succinct.

Beware, though, that there’s an implicit parameter with patches though and that’s the “base” that we’re applying the patches against. You don’t want to apply patches to the wrong base object, otherwise you’ll end up at the wrong result.

import type { ActionFunctionArgs } from "@remix-run/node"; // or cloudflare/deno
import { redirect } from "@remix-run/node"; // or cloudflare/deno
import { useNavigation } from "@remix-run/react";

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const project = await createRecord({
    name: formData.get("name"),
    owner: formData.get("owner"),
  });
  return redirect(`/projects/${project.id}`);
}

export default function CreateProject() {
  const navigation = useNavigation();

  // important to check you're submitting to the action
  // for the pending UI, not just any action
  const isSubmitting = navigation.formAction === "/create-project";

  return (
    <Form method="post" action="/create-project">
      <fieldset disabled={isSubmitting}>
        <label>
          Name: <input type="text" name="projectName" />
        </label>
        <label>
          Owner: <UserSelect />
        </label>
        <button type="submit">Create</button>
      </fieldset>
      {isSubmitting ? <BusyIndicator /> : null}
    </Form>
  );
}

function CreateForm() {
  <form
    onSubmit={(evt) => {
      const formData = new FormData(evt.target);

      // Go to the server first to create the entity
      const serverResult = await fetch("/api/create", {
        title: formData.get("title"),
      }).then((res) => res.json());

      // Now create a new command entry
      dispatch(
        createEntity({
          entity: serverResult.data,
        }),
      );
    }}
  >
    <input name="title" />
    <button>Submit</button>
  </form>;
}

const createEntity = (entity) => ({
  // The `exec` command could be async to allow for setups.
  exec(params) {
    updateUI((state) => {
      state[entity.id] = entity;
    });

    // Maybe we return a payload we will want later in the `undo`
    // operation
    return {
      type: "exec",
      id: entity.id,
    };
  },
  undo(entry) {
    updateUI((state) => {
      state[entry.payload.id].isArchived = true;
    });

    return {
      id: entry.payload.id,
      type: "undo",
    };
  },
  redo(entry) {
    updateUI((state) => {
      state[entry.payload.id].isArchived = false;
    });
    return {
      id: entry.payload.id,
      type: "undo",
    };
  },

  syncToBackend(entry) {
    if (entry.type === "exec") {
      // Nothing to do here because we already created the entity
    }

    if (entry.type === "undo") {
      fetch("/api/markArchived", {
        method: "POST",
        body: JSON.stringify({
          id: entry.payload.id,
        }),
      });
    }
  },
});

function dispatch(command, params) {
  const payload = command.exec(params);
  const transaction = createTransaction(command, payload);
  syncQueue.push(transaction);
  undoStack.push(transaction);
}

function undo() {
  const txn = undoStack.pop();
  if (txn) {
    txn.command.undo(txn);
    // Create a new transaction after the undo
    const nextTxn = createTransaction(txn.command, txn.payload);
    syncQueue.push(nextTxn);
    redoStack.push(nextTxn);
  }
}

const myCommand = {
  exec(state) {
    const [state, patches, inversePatches] = produceWithPatches(
      currentState,
      (state) => {
        state.value = "foo";
      },
    );

    return { patches, inversePatches };
  },
  undo(executeTxn) {
    // We apply the inverse patches from the `exec` transaction and return
    // _new_ patches to be used later for redo
    const [state, patches, inversePatches] = produceWithPatches(
      currentState,
      (state) => {
        applyPatches(state, executeTxn.inversePatches);
      },
    );

    return { patches, inversePatches };
  },
  redo(undoTxn) {
    // Now we are undoing and undo with the inverse patches produced by the
    // `undo` operation
    const [state, patches, inversePatches] = produceWithPatches(
      currentState,
      (state) => {
        applyPatches(state, executeTxn.inversePatches);
      },
    );

    return { patches, inversePatches };
  },
};

const myCommand = {
  params: {
    id: "xxx",
    previous: "foo",
    next: "bar",
    focusId: "yyy",
  },
  exec() {
    state[params.id].value === params.next;
  },
  undo() {
    state[params.id].value === params.previous;
    document.getElementById(params.focusId)?.focus();
  },
};

const myCommand = {
  params: {
    id: "xxx",
    previous: "foo",
    next: "bar",
    focusId: "yyy",
  },
  exec() {
    state[params.id].value === params.next;
  },
  undo(createEffect) {
    state[params.id].value === params.previous;

    createEffect(() => {
      document.getElementById(params.focusId)?.focus();
    });
  },
};

function undo() {
  const txn = undoStack.pop();
  if (txn) {
    const effects = [];
    const createEffect = (effect) => effects.push(effect);
    const entry = txn.command.undo(createEffect);

    // push the effects needed to run
    state.effects = effects;
  }
}

function App() {
  const effects = useEffects();

  // Now run all of the effects created in the last transaction;
  useEffect(() => {
    // TODO: Cancellation!
    effects.forEach((effect) => {
      effect();
    });
  }, [effects]);
}