Command — Give an action a value

01 / The idea

A button starts the work. It doesn’t have to own it.

You’re building a small layout editor. There is one selected card with a name and a horizontal position. At first, the Rename button reads an input and updates the name. A direct handler is clear, easy to follow, and enough for that first interaction.

Now the command palette needs the same action. Extracting a shared function handles that reuse. Later, you want to keep a list of completed edits, show “Undo Rename,” and let another control choose when an action runs. The request itself has become something you want to pass around.

Command represents a request as a value that another part of the program can execute. A rename carries the requested name and knows how to apply it. The button creates the request; the editor decides when to execute it and whether to keep it in history.

A function with captured arguments can be enough. An object becomes useful when you also need a label or several related operations. The decision is to separate preparing a request from invoking its behavior.

02 / See the shape

Carry the new value. Remember the old one when you act.

Start with Basic form: create a rename, then hand it to an invoker with the current document. The same request can come from a button, a palette, or a test. It produces a new document value; the original is left intact.

In the wild grows this into an editor. Rename and Move validate their arguments, return no change when the requested value is already present, and otherwise return a new document together with an inverse. Rename to Launch might return Rename to Release as its inverse. Move to 80 might return Move to 20.

The editor keeps the forward and inverse commands together. Undo runs the inverse and transfers that entry from Past to Future. Redo runs the forward command and transfers it back, keeping the inverse captured when the entry first ran; Undo restored exactly that state, so the inverse is still the right one. A successful new edit clears Future because you have chosen a different continuation.

Read in

Compare with

A rename carries the requested name. An invoker runs it against a document supplied at execution. This small form has no validation or history.

TypeScriptReading

editor.ts

export type BasicCommand = { execute(document: Document): Document };

export function renameBasic(name: string): BasicCommand {
	return { execute: (document) => ({ ...document, name }) };
}

export function invokeBasic(document: Document, command: BasicCommand): Document {
	return command.execute(document);
}

GoAlongside

editor.go

type BasicCommand func(Document) Document

func RenameBasic(name string) BasicCommand {
	return func(document Document) Document { document.Name = name; return document }
}

func InvokeBasic(document Document, command BasicCommand) Document {
	return command(document)
}

Read the complete sources without JavaScript

TypeScript source

editor.ts

export type Document = Readonly<{ name: string; x: number }>;

export type BasicCommand = { execute(document: Document): Document };

export function renameBasic(name: string): BasicCommand {
	return { execute: (document) => ({ ...document, name }) };
}

export function invokeBasic(document: Document, command: BasicCommand): Document {
	return command.execute(document);
}

export type Change = { document: Document; inverse: Command };
export interface Command {
	readonly label: string;
	// Pure: reject before changing anything; null means no change.
	execute(document: Document): Change | null;
}

function validateName(name: string) {
	if (name.length === 0) throw new Error('Name must not be empty');
}
function validatePosition(x: number) {
	if (!Number.isInteger(x) || x < 0 || x > 100)
		throw new Error('Position must be a whole number from 0 to 100');
}

export function rename(name: string): Command {
	return {
		label: 'Rename',
		execute(document) {
			validateName(name);
			if (name === document.name) return null;
			return {
				document: { ...document, name },
				inverse: rename(document.name) // Capture the old name at execution time.
			};
		}
	};
}

export function moveTo(x: number): Command {
	return {
		label: 'Move',
		execute(document) {
			validatePosition(x);
			if (x === document.x) return null;
			return { document: { ...document, x }, inverse: moveTo(document.x) };
		}
	};
}

type Entry = { forward: Command; inverse: Command };
export class Editor {
	#document: Document;
	#past: Entry[] = [];
	#future: Entry[] = [];

	constructor(document: Document = { name: 'Card', x: 20 }) {
		validateName(document.name);
		validatePosition(document.x);
		this.#document = Object.freeze({ ...document });
	}

	execute(command: Command): boolean {
		const change = command.execute(this.#document);
		if (!change) return false;
		this.#document = Object.freeze({ ...change.document });
		this.#past.push({ forward: command, inverse: change.inverse });
		this.#future = []; // Only a successful new edit abandons the old branch.
		return true;
	}

	undo(): boolean {
		const entry = this.#past.at(-1);
		if (!entry) return false;
		const change = entry.inverse.execute(this.#document);
		if (!change) return false;
		this.#document = Object.freeze({ ...change.document });
		this.#past.pop();
		this.#future.push(entry);
		return true;
	}

	redo(): boolean {
		const entry = this.#future.at(-1);
		if (!entry) return false;
		const change = entry.forward.execute(this.#document);
		if (!change) return false;
		this.#document = Object.freeze({ ...change.document });
		this.#future.pop();
		this.#past.push(entry);
		return true;
	}

	snapshot() {
		return {
			document: { ...this.#document },
			past: this.#past.map((entry) => entry.forward.label),
			future: this.#future.map((entry) => entry.forward.label)
		};
	}
}

export function runExample() {
	const editor = new Editor();
	const fromToolbar = () => editor.execute(rename('Release'));
	const fromPalette = () => editor.execute(moveTo(80));
	try {
		fromToolbar();
		fromPalette();
		editor.undo(); // Release, x = 20. Move is ready to redo.
		editor.execute(rename('Launch')); // A new branch discards that Move.
		console.log(editor.redo()); // false
		console.log(editor.snapshot()); // Launch, x = 20; past: Rename, Rename
	} catch (error) {
		console.error(error instanceof Error ? error.message : 'Edit failed');
	}
}

runExample();

Go source

editor.go

package main

import (
	"errors"
	"fmt"
	"math"
)

type Document struct {
	Name string  `json:"name"`
	X    float64 `json:"x"`
}

type BasicCommand func(Document) Document

func RenameBasic(name string) BasicCommand {
	return func(document Document) Document { document.Name = name; return document }
}

func InvokeBasic(document Document, command BasicCommand) Document {
	return command(document)
}


type Change struct {
	Document Document
	Inverse  Command
}
type Command interface {
	Label() string
	Execute(Document) (*Change, error)
}

func validateName(name string) error {
	if len(name) == 0 {
		return errors.New("Name must not be empty")
	}
	return nil
}
func validatePosition(x float64) error {
	if math.IsNaN(x) || math.IsInf(x, 0) || math.Trunc(x) != x || x < 0 || x > 100 {
		return errors.New("Position must be a whole number from 0 to 100")
	}
	return nil
}

type Rename struct{ Name string }

func (Rename) Label() string { return "Rename" }
func (command Rename) Execute(document Document) (*Change, error) {
	if err := validateName(command.Name); err != nil {
		return nil, err
	}
	if command.Name == document.Name {
		return nil, nil
	}
	inverse := Rename{Name: document.Name} // Capture when executed.
	document.Name = command.Name
	return &Change{document, inverse}, nil
}

type MoveTo struct{ X float64 }

func (MoveTo) Label() string { return "Move" }
func (command MoveTo) Execute(document Document) (*Change, error) {
	if err := validatePosition(command.X); err != nil {
		return nil, err
	}
	if command.X == document.X {
		return nil, nil
	}
	inverse := MoveTo{X: document.X}
	document.X = command.X
	return &Change{document, inverse}, nil
}

type entry struct{ forward, inverse Command }
type Editor struct {
	document     Document
	past, future []entry
}

func NewEditor(document Document) (*Editor, error) {
	if err := validateName(document.Name); err != nil {
		return nil, err
	}
	if err := validatePosition(document.X); err != nil {
		return nil, err
	}
	return &Editor{document: document}, nil
}
func (editor *Editor) Execute(command Command) (bool, error) {
	change, err := command.Execute(editor.document)
	if err != nil || change == nil {
		return false, err
	}
	editor.document = change.Document
	editor.past = append(editor.past, entry{command, change.Inverse})
	editor.future = nil
	return true, nil
}
func (editor *Editor) Undo() (bool, error) {
	if len(editor.past) == 0 {
		return false, nil
	}
	index := len(editor.past) - 1
	item := editor.past[index]
	change, err := item.inverse.Execute(editor.document)
	if err != nil || change == nil {
		return false, err
	}
	editor.document = change.Document
	editor.past[index] = entry{} // Release retained interface values.
	editor.past = editor.past[:index]
	editor.future = append(editor.future, item)
	return true, nil
}
func (editor *Editor) Redo() (bool, error) {
	if len(editor.future) == 0 {
		return false, nil
	}
	index := len(editor.future) - 1
	item := editor.future[index]
	change, err := item.forward.Execute(editor.document)
	if err != nil || change == nil {
		return false, err
	}
	editor.document = change.Document
	editor.future[index] = entry{}
	editor.future = editor.future[:index]
	editor.past = append(editor.past, item)
	return true, nil
}

type Snapshot struct {
	Document Document `json:"document"`
	Past     []string `json:"past"`
	Future   []string `json:"future"`
}

func (editor *Editor) Snapshot() Snapshot {
	result := Snapshot{editor.document, []string{}, []string{}}
	for _, item := range editor.past {
		result.Past = append(result.Past, item.forward.Label())
	}
	for _, item := range editor.future {
		result.Future = append(result.Future, item.forward.Label())
	}
	return result
}


func runExample() error {
	editor, err := NewEditor(Document{"Card", 20})
	if err != nil {
		return err
	}
	fromToolbar := func() (bool, error) { return editor.Execute(Rename{"Release"}) }
	fromPalette := func() (bool, error) { return editor.Execute(MoveTo{80}) }
	if _, err = fromToolbar(); err != nil {
		return err
	}
	if _, err = fromPalette(); err != nil {
		return err
	}
	if _, err = editor.Undo(); err != nil {
		return err
	}
	if _, err = editor.Execute(Rename{"Launch"}); err != nil {
		return err
	}
	changed, err := editor.Redo()
	if err != nil {
		return err
	}
	fmt.Println(changed)           // false
	fmt.Println(editor.Snapshot()) // Launch, 20; past: Rename, Rename
	return nil
}
func main() {
	if err := runExample(); err != nil {
		fmt.Println(err)
	}
}

Python source

editor.py

"""Represent reversible editor requests as values."""

from __future__ import annotations

from dataclasses import dataclass
import math
from typing import Callable, Protocol


@dataclass(frozen=True, slots=True)
class Document:
    name: str
    x: float


BasicCommand = Callable[[Document], Document]


def rename_basic(name: str) -> BasicCommand:
    return lambda document: Document(name, document.x)


def invoke_basic(document: Document, command: BasicCommand) -> Document:
    return command(document)




class Command(Protocol):
    @property
    def label(self) -> str: ...

    def execute(self, document: Document) -> Change | None: ...


@dataclass(frozen=True, slots=True)
class Change:
    document: Document
    inverse: Command


def validate_name(name: str) -> None:
    if len(name) == 0:
        raise ValueError("Name must not be empty")


def validate_position(x: float) -> None:
    if (
        isinstance(x, bool)
        or not isinstance(x, (int, float))
        or not math.isfinite(x)
        or not float(x).is_integer()
        or not 0 <= x <= 100
    ):
        raise ValueError("Position must be a whole number from 0 to 100")


@dataclass(frozen=True, slots=True)
class Rename:
    name: str
    label: str = "Rename"

    def execute(self, document: Document) -> Change | None:
        validate_name(self.name)
        if self.name == document.name:
            return None
        return Change(Document(self.name, document.x), Rename(document.name))


@dataclass(frozen=True, slots=True)
class MoveTo:
    x: float
    label: str = "Move"

    def execute(self, document: Document) -> Change | None:
        validate_position(self.x)
        if self.x == document.x:
            return None
        return Change(Document(document.name, self.x), MoveTo(document.x))


@dataclass(frozen=True, slots=True)
class Entry:
    forward: Command
    inverse: Command


class Editor:
    def __init__(self, document: Document | None = None) -> None:
        initial = document if document is not None else Document("Card", 20)
        validate_name(initial.name)
        validate_position(initial.x)
        self._document = Document(initial.name, initial.x)
        self._past: list[Entry] = []
        self._future: list[Entry] = []

    def execute(self, command: Command) -> bool:
        change = command.execute(self._document)
        if change is None:
            return False
        self._document = Document(change.document.name, change.document.x)
        self._past.append(Entry(command, change.inverse))
        self._future.clear()
        return True

    def undo(self) -> bool:
        if not self._past:
            return False
        entry = self._past[-1]
        change = entry.inverse.execute(self._document)
        if change is None:
            return False
        self._document = Document(change.document.name, change.document.x)
        self._past.pop()
        self._future.append(entry)
        return True

    def redo(self) -> bool:
        if not self._future:
            return False
        entry = self._future[-1]
        change = entry.forward.execute(self._document)
        if change is None:
            return False
        self._document = Document(change.document.name, change.document.x)
        self._future.pop()
        self._past.append(entry)
        return True

    def snapshot(self) -> dict[str, object]:
        return {
            "document": {"name": self._document.name, "x": self._document.x},
            "past": [entry.forward.label for entry in self._past],
            "future": [entry.forward.label for entry in self._future],
        }




def run_example() -> None:
    editor = Editor()
    from_toolbar = lambda: editor.execute(Rename("Release"))
    from_palette = lambda: editor.execute(MoveTo(80))
    try:
        from_toolbar()
        from_palette()
        editor.undo()  # Release, x = 20. Move is ready to redo.
        editor.execute(Rename("Launch"))  # A new branch discards that Move.
        print(editor.redo())  # False
        print(editor.snapshot())  # Launch, x = 20; past: Rename, Rename
    except Exception as error:
        print(str(error) or "Edit failed")




if __name__ == "__main__":
    run_example()

Java source

CommandExample.java

import java.util.ArrayList;
import java.util.List;

record Document(String name, double x) {}

@FunctionalInterface
interface BasicCommand {
    Document execute(Document document);
}

final class BasicCommands {
    private BasicCommands() {}

    static BasicCommand renameBasic(String name) {
        return document -> new Document(name, document.x());
    }

    static Document invokeBasic(Document document, BasicCommand command) {
        return command.execute(document);
    }
}

record Change(Document document, Command inverse) {}

interface Command {
    String label();
    Change execute(Document document);
}

final class Validation {
    private Validation() {}

    static void name(String name) {
        if (name.isEmpty()) throw new IllegalArgumentException("Name must not be empty");
    }

    static void position(double x) {
        if (!Double.isFinite(x) || x != Math.rint(x) || x < 0 || x > 100) {
            throw new IllegalArgumentException("Position must be a whole number from 0 to 100");
        }
    }
}

record Rename(String name) implements Command {
    @Override
    public String label() {
        return "Rename";
    }

    @Override
    public Change execute(Document document) {
        Validation.name(name);
        if (name.equals(document.name())) return null;
        return new Change(new Document(name, document.x()), new Rename(document.name()));
    }
}

record MoveTo(double x) implements Command {
    @Override
    public String label() {
        return "Move";
    }

    @Override
    public Change execute(Document document) {
        Validation.position(x);
        if (x == document.x()) return null;
        return new Change(new Document(document.name(), x), new MoveTo(document.x()));
    }
}

record Entry(Command forward, Command inverse) {}

final class Editor {
    private Document document;
    private final List<Entry> past = new ArrayList<>();
    private final List<Entry> future = new ArrayList<>();

    Editor() {
        this(new Document("Card", 20));
    }

    Editor(Document document) {
        Validation.name(document.name());
        Validation.position(document.x());
        this.document = new Document(document.name(), document.x());
    }

    boolean execute(Command command) {
        Change change = command.execute(document);
        if (change == null) return false;
        document = new Document(change.document().name(), change.document().x());
        past.add(new Entry(command, change.inverse()));
        future.clear();
        return true;
    }

    boolean undo() {
        if (past.isEmpty()) return false;
        Entry entry = past.get(past.size() - 1);
        Change change = entry.inverse().execute(document);
        if (change == null) return false;
        document = new Document(change.document().name(), change.document().x());
        past.remove(past.size() - 1);
        future.add(entry);
        return true;
    }

    boolean redo() {
        if (future.isEmpty()) return false;
        Entry entry = future.get(future.size() - 1);
        Change change = entry.forward().execute(document);
        if (change == null) return false;
        document = new Document(change.document().name(), change.document().x());
        future.remove(future.size() - 1);
        past.add(entry);
        return true;
    }

    Snapshot snapshot() {
        List<String> pastLabels = past.stream().map(entry -> entry.forward().label()).toList();
        List<String> futureLabels = future.stream().map(entry -> entry.forward().label()).toList();
        return new Snapshot(new Document(document.name(), document.x()), pastLabels, futureLabels);
    }
}

record Snapshot(Document document, List<String> past, List<String> future) {}

public final class CommandExample {
    private CommandExample() {}

    static List<String> runExample() {
        Editor editor = new Editor();
        editor.execute(new Rename("Release"));
        editor.execute(new MoveTo(80));
        editor.undo();
        editor.execute(new Rename("Launch"));
        return List.of(Boolean.toString(editor.redo()), editor.snapshot().toString());
    }

    public static void main(String[] args) {
        runExample().forEach(System.out::println);
    }
}

Rust source

editor.rs

#[derive(Clone, Debug, PartialEq)]
pub struct Document {
    pub name: String,
    pub x: f64,
}

pub fn rename_basic(name: String) -> impl Fn(&Document) -> Document {
    move |document| Document {
        name: name.clone(),
        ..document.clone()
    }
}
pub fn invoke_basic(document: &Document, command: impl Fn(&Document) -> Document) -> Document {
    command(document)
}

pub struct Change {
    pub document: Document,
    pub inverse: Box<dyn Command>,
}
pub trait Command {
    fn label(&self) -> &str;
    fn execute(&self, document: &Document) -> Result<Option<Change>, String>;
}
fn validate_name(name: &str) -> Result<(), String> {
    if name.is_empty() {
        return Err("Name must not be empty".into());
    }
    Ok(())
}
fn validate_position(x: f64) -> Result<(), String> {
    if !x.is_finite() || x.fract() != 0.0 || !(0.0..=100.0).contains(&x) {
        return Err("Position must be a whole number from 0 to 100".into());
    }
    Ok(())
}

pub struct Rename(pub String);
impl Command for Rename {
    fn label(&self) -> &str {
        "Rename"
    }
    fn execute(&self, document: &Document) -> Result<Option<Change>, String> {
        validate_name(&self.0)?;
        if self.0 == document.name {
            return Ok(None);
        }
        Ok(Some(Change {
            document: Document {
                name: self.0.clone(),
                ..document.clone()
            },
            inverse: Box::new(Rename(document.name.clone())), // Capture when executed.
        }))
    }
}
pub struct MoveTo(pub f64);
impl Command for MoveTo {
    fn label(&self) -> &str {
        "Move"
    }
    fn execute(&self, document: &Document) -> Result<Option<Change>, String> {
        validate_position(self.0)?;
        if self.0 == document.x {
            return Ok(None);
        }
        Ok(Some(Change {
            document: Document {
                x: self.0,
                ..document.clone()
            },
            inverse: Box::new(MoveTo(document.x)),
        }))
    }
}
struct Entry {
    forward: Box<dyn Command>,
    inverse: Box<dyn Command>,
}
pub struct Editor {
    document: Document,
    past: Vec<Entry>,
    future: Vec<Entry>,
}
impl Editor {
    pub fn new(document: Document) -> Result<Self, String> {
        validate_name(&document.name)?;
        validate_position(document.x)?;
        Ok(Self {
            document,
            past: vec![],
            future: vec![],
        })
    }
    pub fn execute(&mut self, command: Box<dyn Command>) -> Result<bool, String> {
        let Some(change) = command.execute(&self.document)? else {
            return Ok(false);
        };
        self.document = change.document;
        self.past.push(Entry {
            forward: command,
            inverse: change.inverse,
        });
        self.future.clear();
        Ok(true)
    }
    pub fn undo(&mut self) -> Result<bool, String> {
        let Some(entry) = self.past.last() else {
            return Ok(false);
        };
        let Some(change) = entry.inverse.execute(&self.document)? else {
            return Ok(false);
        };
        self.document = change.document;
        let entry = self.past.pop().expect("past entry was checked above");
        self.future.push(entry);
        Ok(true)
    }
    pub fn redo(&mut self) -> Result<bool, String> {
        let Some(entry) = self.future.last() else {
            return Ok(false);
        };
        let Some(change) = entry.forward.execute(&self.document)? else {
            return Ok(false);
        };
        self.document = change.document;
        let entry = self.future.pop().expect("future entry was checked above");
        self.past.push(entry);
        Ok(true)
    }
    pub fn snapshot(&self) -> Snapshot {
        Snapshot {
            document: self.document.clone(),
            past: self
                .past
                .iter()
                .map(|entry| entry.forward.label().to_string())
                .collect(),
            future: self
                .future
                .iter()
                .map(|entry| entry.forward.label().to_string())
                .collect(),
        }
    }
}
#[derive(Debug, PartialEq)]
pub struct Snapshot {
    pub document: Document,
    pub past: Vec<String>,
    pub future: Vec<String>,
}

pub fn run_example() -> Result<(), String> {
    let mut editor = Editor::new(Document {
        name: "Card".into(),
        x: 20.0,
    })?;
    let from_toolbar = |editor: &mut Editor| editor.execute(Box::new(Rename("Release".into())));
    let from_palette = |editor: &mut Editor| editor.execute(Box::new(MoveTo(80.0)));
    from_toolbar(&mut editor)?;
    from_palette(&mut editor)?;
    editor.undo()?;
    editor.execute(Box::new(Rename("Launch".into())))?;
    println!("{}", editor.redo()?); // false
    println!("{:?}", editor.snapshot()); // Launch, 20; past: Rename, Rename
    Ok(())
}
fn main() {
    if let Err(error) = run_example() {
        eprintln!("{error}");
    }
}

The behavior every example promisesResults, no changes, and failures

A document begins as Card at x = 20. Names must contain at least one character; they are preserved exactly, including spaces and Unicode. Positions must be finite whole numbers from 0 through 100.

Commands validate when executed. An invalid request fails before changing state. A valid request for the current value reports no change. Both leave the document, Past, and Future untouched. Empty Undo or Redo also reports no change.

Only successful new edits add an entry and clear Future. Undo and Redo move existing entries. In source snapshots, the last array element is next; the lab displays that entry first. Inspection returns independent document values and label lists, so inspecting history cannot rewrite it.

All edits run synchronously through one editor. Commands must calculate their result without changing the input or performing external work. The shipped Rename and Move commands meet that contract. Arbitrary plugin code is not sandboxed by this interface, and arbitrary JSON needs validation before it becomes a typed request.

Reading the TypeScriptClosures, private fields, and null

rename(name) returns an object whose method closes over the requested name. It does not read the old name yet. execute(document) reads that later and returns a separate inverse object. Preparing or reusing a command therefore does not overwrite an earlier history entry’s inverse.

Change | null separates an edit from an unchanged request; invalid requests throw. The editor’s #past, #future, and #document fields are private. Readonly is a type constraint, while Object.freeze protects the current document at runtime. Its two fields are scalar values, so a shallow copy is enough here.

Reading the GoInterface values, copies, and returned errors

The basic command is a function value. The practical Command interface asks for Label and Execute; Rename and MoveTo satisfy it through their methods. We pass structs by value, so the stored commands carry copies of their string or float64 arguments; the float is deliberate, so a fractional position can be rejected as it is in TypeScript.

(*Change, error) distinguishes a change, nil, nil for no change, and a returned error. The document is also passed by value. That is enough for a string and number; adding slices or maps would require an explicit copying policy. Popped entries are zeroed before shortening slices so their backing arrays do not retain command references unnecessarily.

Reading the PythonDataclasses, protocols, and exceptions

Document, Change, and the built-in commands are frozen dataclasses. A Command protocol describes the label and execution method without forcing inheritance. Rename and MoveTo create a new document and capture an inverse from the document passed to that execution.

The editor copies document values, moves entries between its two lists, and raises ValueError for invalid requests. The built-in commands are synchronous and deterministic; a custom collaborator still has to honor the same contract.

03 / Follow the values

There is a Move waiting in the future.

We renamed Card to Release, moved it to 80, then undid the move. Before you touch the controls, predict: will renaming it to Launch keep that Move available? What if you submit Release again, or leave the name empty?

One edit creates a different future.

Start after an undo. Predict what a new edit will do to the pending Move, then execute it.

Current document Release

0x = 20100

Past 1

Renamenext to undo

Future 1

Movenext to redo

Rename to Release, move to 80, then undo the move. You are back at x = 20, with Move ready to redo.

Enable JavaScript to run commands. In this initial state, renaming Release to Launch clears the pending Move. An empty name fails and keeps it; renaming to Release changes nothing and also keeps it.

Runs the displayed TypeScript editor. The Go implementation uses the same behavior cases in native tests.

Try Undo after a successful rename. The old name returns because that execution saved it in an inverse. The old Move branch does not return: starting a new branch discarded it. Undoing the branch’s first edit is still different from recovering a discarded future.

04 / Try a decision

“Before” belongs to an execution.

A command can be prepared before it runs. That makes timing part of the design: the requested value can be captured early, but the value being replaced must come from the state the operation actually receives.

05 / Give it a real job

One open document, one owner of its history.

In a layout editor, create an Editor when a document is opened. A toolbar handler or palette action supplies a fresh command using the user’s chosen value. The editor invokes it, commits its result, and retains its inverse. The view then renders the returned inspection value and updates Undo and Redo availability.

View connections as text

UI controls: Read user intent and submit a command. Multiple controls can share the same action.
Editor: Own the current document and history. Invoke first, then commit a successful result.
Rename / Move: Validate the request; calculate a new document and an inverse using the current value.
Document: The name and position being edited, returned as a new value.

UI controls submits request Editor
Editor retains and invokes Rename / Move
Rename / Move calculates next value Document
Editor owns current value Document

The traditional roles are client, invoker, command, and receiver. Here the receiver’s state is a document value. The command returns its result to the editor, which installs it. A classic object version might call methods on a mutable document receiver instead; the responsibility separation can stay the same.

Suppose you add a Rotate action. The document needs an angle, the new command needs its validation and inverse, and the controls need a way to select it. The editor’s history algorithm can stay the same because it calls the command contract without inspecting whether the action is Rename, Move, or Rotate.

Build UIs?A toolbar button, a palette entry, and a shortcut that share one rename already converge on a command, and one day undo will need its inverse.

Where it already is in your components

A Rename button in the toolbar, a “Rename selection” entry in the command palette, and Ctrl/⌘+Z on the canvas: three controls, one handler, and an undo stack held in component state, useState in React or $state in Svelte. You have written this panel. Two lines in it are the lesson. The three entry points converge on a single value, rename(draft), and none of them knows how a rename is carried out. And the inverse comes back from execute already holding the name the document had at that moment, which is section 04’s capture point sitting inside your click handler. The two arrays are the editor’s Past and Future from section 03; redo runs the stored command again rather than restoring a saved copy of the document.

Reach for useReducer instead and dispatch({ type: 'rename', name: draft }) makes the same move with the behavior taken out: the action is a plain record, and the reducer is the invoker that knows how to apply it. React accepts an action of any type, but Redux’s style guide rates keeping functions out of actions as essential, so that debugging with the Redux DevTools, which records each action, works as expected. That is where this lesson’s commands differ. JSON.stringify(rename('Launch')) gives {"label":"Rename"}: the execute method is dropped, so a saved list of these commands cannot run again, while a saved log of { type, name } records replays through the reducer to the same state. Dispatch a command object through Redux Toolkit and its development check says so: “A non-serializable value was detected in an action, in the path: payload.execute.”

When you have to own it

Component state lives as long as the component. Collapse the sidebar, change route, or let React remount the panel, and the history is gone while the document is still open. A real app also keeps its shortcuts in one place, a single keydown listener on the document, not a prop on the canvas. So the editor and its history move into a module that outlives the panel: React subscribes through useSyncExternalStore, Svelte reads module-level $state. Both remove the document listener on unmount, and both act only when the canvas is the event’s target, so the name field keeps native text-input undo. That is the same rule the adapter below applies at the canvas.

A rename panel: toolbar, palette, and shortcut hand the same rename(draft) value to one handler, and the undo stack is component state.

ReactAlready in your code

RenameToolbar.tsx

import { useState, type KeyboardEvent } from 'react';
import { rename, type Command, type Document } from '../editor';

// One entry per successful edit: the command that ran and the inverse it handed
// back. No copies of the document; the inverse is all that undo needs.
type Entry = { forward: Command; inverse: Command };

export function RenameToolbar() {
	const [doc, setDoc] = useState<Document>({ name: 'Card', x: 20 });
	// The undo stack, in component state. Past and Future are the editor's two
	// lists from section 03, kept here because this is where they usually start.
	const [past, setPast] = useState<Entry[]>([]);
	const [future, setFuture] = useState<Entry[]>([]);
	const [draft, setDraft] = useState('');
	const [status, setStatus] = useState('Ready');

	function run(command: Command) {
		try {
			const change = command.execute(doc);
			if (!change) return setStatus('Unchanged');
			// change.inverse was built inside execute() from the name the document
			// has right now. That is the capture moment from section 04: the inverse
			// of renaming 'Card' exists only because the rename ran against 'Card'.
			setDoc(change.document);
			setPast([...past, { forward: command, inverse: change.inverse }]);
			setFuture([]); // A new edit abandons the redo branch.
			setStatus(`${command.label}: ${change.document.name}`);
		} catch (error) {
			setStatus(error instanceof Error ? error.message : 'Edit failed');
		}
	}
	function undo() {
		const entry = past.at(-1);
		if (!entry) return;
		const change = entry.inverse.execute(doc);
		if (!change) return;
		setDoc(change.document);
		setPast(past.slice(0, -1));
		setFuture([...future, entry]);
	}
	function redo() {
		const entry = future.at(-1);
		if (!entry) return;
		// Redo runs the original command again. Nothing was saved to restore.
		const change = entry.forward.execute(doc);
		if (!change) return;
		setDoc(change.document);
		setFuture(future.slice(0, -1));
		setPast([...past, entry]);
	}

	// Three entry points, one value. The toolbar button, the palette entry, and
	// the shortcut all arrive here; none of them knows how a rename is done.
	const renameSelection = () => run(rename(draft));

	function onCanvasKey(event: KeyboardEvent<HTMLDivElement>) {
		// Attached to the canvas, so the shortcut fires only while the canvas has
		// focus. Typing in the name field keeps the browser's own undo.
		if (!(event.ctrlKey || event.metaKey) || event.key.toLowerCase() !== 'z') return;
		event.preventDefault();
		if (event.shiftKey) redo();
		else undo();
	}

	return (
		<div>
			<div role="toolbar" aria-label="Edit">
				<button type="button" onClick={renameSelection}>
					Rename
				</button>
				<button type="button" onClick={undo} disabled={past.length === 0}>
					Undo
				</button>
				<button type="button" onClick={redo} disabled={future.length === 0}>
					Redo
				</button>
			</div>
			{/* The palette lists actions by name; its entry points at the same handler. */}
			<ul role="menu" aria-label="Command palette">
				<li role="none">
					<button type="button" role="menuitem" onClick={renameSelection}>
						Rename selection…
					</button>
				</li>
			</ul>
			<input aria-label="Name" value={draft} onChange={(event) => setDraft(event.target.value)} />
			<div role="application" tabIndex={0} aria-label="Canvas" onKeyDown={onCanvasKey}>
				{doc.name} at x = {doc.x}
			</div>
			<p role="status">{status}</p>
		</div>
	);
}

Two controls, one action; shortcuts belong to the focused editorTypeScript browser application

This browser adapter connects two existing buttons to the same rename action. A canvas shortcut sends Undo or Redo to the same editor. It only handles keys targeted at the canvas itself, so typing in the name field keeps native text-input undo.

The caller supplies labeled elements and a document’s editor. Render feedback as text, provide visible Undo/Redo buttons, and call the returned cleanup function when the view is removed. A Svelte component can use equivalent event handlers and its mount/teardown lifecycle; the command implementation does not need to import Svelte.

frontend.ts

import { Editor, rename } from './editor';

// Authored browser integration. Supply existing, labeled controls.
// The canvas should have tabindex="0" and an accessible name.
// Both buttons should have type="button".
export function mountEditorControls(
	canvas: HTMLElement,
	toolbarButton: HTMLButtonElement,
	paletteButton: HTMLButtonElement,
	nameInput: HTMLInputElement,
	status: HTMLElement,
	editor: Editor
): () => void {
	function render(message: string) {
		const { document } = editor.snapshot();
		status.textContent = `${message}: ${document.name}, x = ${document.x}`;
	}
	function renameSelection() {
		try {
			const changed = editor.execute(rename(nameInput.value));
			render(changed ? 'Renamed' : 'Unchanged');
		} catch (error) {
			status.textContent = error instanceof Error ? error.message : 'Edit failed';
		}
	}
	function onKey(event: KeyboardEvent) {
		// Only handle a shortcut on the canvas itself. Text inputs keep native undo.
		if (event.target !== canvas || event.isComposing || event.repeat || event.altKey) return;
		if (!(event.ctrlKey || event.metaKey) || event.key.toLowerCase() !== 'z') return;
		event.preventDefault();
		try {
			const changed = event.shiftKey ? editor.redo() : editor.undo();
			render(changed ? (event.shiftKey ? 'Redone' : 'Undone') : 'No history');
		} catch (error) {
			status.textContent = error instanceof Error ? error.message : 'Edit failed';
		}
	}
	toolbarButton.addEventListener('click', renameSelection);
	paletteButton.addEventListener('click', renameSelection);
	canvas.addEventListener('keydown', onKey);
	render('Ready');
	return () => {
		toolbarButton.removeEventListener('click', renameSelection);
		paletteButton.removeEventListener('click', renameSelection);
		canvas.removeEventListener('keydown', onKey);
	};
}
// During UI mount: const dispose = mountEditorControls(canvas, toolbarButton,
//   paletteButton, nameInput, status, new Editor());
// Call dispose() on teardown. Provide visible Undo/Redo controls too.

The assumptions that keep these inverses validLifetime, grouping, and failure

Keep edits in order. An inverse assumes the surrounding history has been undone in reverse order. A remote edit or a direct mutation outside this editor can invalidate that assumption. Collaborative undo needs a conflict or transformation policy.

Choose what one Undo means. Dragging a card through 80 pointer events probably should not require 80 undos. One approach is a temporary drag preview followed by a single committed Move when the gesture ends. Merging commands must retain the first old position and the final new position.

Bound the lifetime. This editor retains history until it is reset or discarded. A real editor needs limits on steps or retained memory. Closing a document should release its editor and UI listeners. Saving a document and marking a history position as saved are separate responsibilities.

Commit only after success. These commands calculate new values without I/O, and the editor changes its document and history only after they return. A command that sends a request and then throws may already have changed the world. Supporting asynchronous operations requires pending-state, ordering, cancellation, and failure rules.

06 / Already in your toolbox

Recognize the contract behind the name.

Notice which part each public API makes explicit: invoking an action, deciding whether it applies, or reversing it.

Qt: an action that can be undone

Qt’s undo framework explicitly uses Command. A QUndoCommand defines redo and undo behavior; QUndoStack holds the history. The stack owns its commands and discards an undone branch when a new command is pushed. Our forward/inverse pair expresses a similar obligation using separate command values.

Qt undo framework →QUndoCommand contract →

ProseMirror: functions as editing commands

A ProseMirror command receives editor state and an optional dispatch function. It reports whether it applies; omitting dispatch allows an applicability check without performing the action.

ProseMirror command guide →

VS Code: one action, several entry points

registerCommand connects an ID to a handler. Keybindings, UI controls, and executeCommand can invoke it. This combines discoverable names with reusable actions. Treat it as a counterexample to “a command must have undo”: the general registration API binds a handler without requiring an inverse.

VS Code command API guide →

07 / Make the choice

What do you need to do with the request?

If a button calls a short function immediately, I’d keep that function until another requirement appears. Commands earn their place when the request needs a life beyond that call site: it will be passed to another invoker, retained in history, described in the UI, or scheduled for later.

Pressure	A simpler starting point	What Command adds
Two buttons perform the same edit	A shared function removes duplicate behavior.	A request value helps when the caller also needs to pass or retain the action.
Undo one local edit	Save a previous state (Memento) when snapshots are small and sufficient.	Retain the operation and the information needed to reverse that execution.
Add a third kind of edit	A small, closed reducer can handle a tagged action clearly.	A new implementation can supply behavior through the existing invoker contract.
Execute a request after restart	Persist a validated data record with a handler.	The request model can guide that design, but closures and trait objects need a separate serializable representation.

Queues, logs, and macros ask for moreUseful extensions with distinct contracts

A background job can represent intent as data: an operation name, target ID, arguments, and schema version. A worker resolves and executes it later. Persistence does not make retries safe; the operation still needs a duplicate-delivery policy.

A macro can group commands into one user action, but failure halfway through raises a new question: are earlier steps rolled back, retained as partial success, or performed in a transaction? Running a list in a loop does not supply atomicity.

A command requests an action. An event records something that happened. Logging attempted commands alone is not a trustworthy history of successful state changes.

08 / Take the idea with you

Explain what the button hands off.

“The controls create an edit request. The editor executes it and keeps the inverse from that execution, so another control can reverse the last completed edit.” You can explain the design before naming the pattern.

Try a transfer: add Rotate. Write its input rule, unchanged case, and inverse. Then explain why renaming to the current name should preserve a pending redo. Finally, find an action in your own application and ask whether passing it as a value would solve a concrete problem.

Connections to follow nextRelated lessons

Stack supplies the order for undo and redo. Command supplies executable requests and, in this example, their inverses.
Memento preserves restorable state. A command can use a snapshot when an inverse operation would be awkward. Our Rename inverse remembers one previous field value; it does not save the entire document.
Strategy supplies a policy to an ongoing workflow. Command packages a request to be invoked. Both can use functions; the responsibility explains the distinction.
Registry can find a command handler by name. Discovery is separate from execution and history.
Publish / subscribe can announce that an edit completed. Publishing that fact is separate from requesting the edit.