Memento — Keep a way back

01 / The idea

The object that owns the state should know how to restore it.

A rename dialog can remember one old title and put it back on Cancel. That is a reasonable solution when one string is all that changes.

Then the dialog becomes a redesign flow. It changes the title, the number of columns, and several content blocks. If the history panel copies and restores those fields itself, it must learn the editor’s internal layout. Add another field and there are now two places that need to understand a valid document.

Memento lets an object capture restorable state and later recover it, while another object keeps the checkpoint without depending on its internal representation. The editor makes the snapshot. History retains it and returns it when asked. The editor performs the restoration.

The traditional names describe those jobs: the editor is the originator, the saved state is the memento, and the history holder is the caretaker. Our caretaker stores an opaque token it cannot read, together with a label the user can recognize. Whether that token refers to the saved state or contains it is a language decision; the notes on each language below say which.

02 / See the shape

History keeps the handle. The editor knows the contents.

The Basic form saves one title behind a checkpoint and verifies that it belongs to the restoring editor. It shows the handoff without nested mutable state or a history collection.

In the wild is a newsletter editor. Its title, column layout, and two text blocks form the restorable document. A history holder keeps the latest few checkpoints. The connection and cached text preview are runtime state with different rules.

What restoration promises in this editor
State	On capture	On restore
Title, columns, blocks	Keep an independent saved version.	Make a fresh editable copy of that version.
Document identity	Bind the token to this editor instance.	Restore into the same editor; keep its identity.
Connection status	Leave it outside the checkpoint.	Keep the current status.
Cached preview	Leave it outside the checkpoint.	Clear it so it can be rendered again.

Read in

Compare with

One old title becomes an opaque checkpoint. The editor can restore it; a caller can retain and return it without learning the saved value.

TypeScriptReading

editor.ts

export class BasicEditor {
	title = 'Release notes';
	#saved = new WeakMap<object, string>();
	capture(): object {
		const token = Object.freeze({});
		this.#saved.set(token, this.title);
		return token;
	}
	restore(token: object): void {
		const title = this.#saved.get(token);
		if (title === undefined) throw new Error('foreign-checkpoint');
		this.title = title;
	}
}

GoAlongside

editor.go

type BasicCheckpoint struct {
	owner *ownerTag
	title string
}
type BasicEditor struct {
	Title string
	owner *ownerTag
}

func NewBasicEditor() *BasicEditor              { return &BasicEditor{"Release notes", &ownerTag{}} }
func (e *BasicEditor) Capture() BasicCheckpoint { return BasicCheckpoint{e.owner, e.Title} }
func (e *BasicEditor) Restore(saved BasicCheckpoint) error {
	if saved.owner == nil || saved.owner != e.owner {
		return errors.New("foreign-checkpoint")
	}
	e.Title = saved.title
	return nil
}

Read the complete sources without JavaScript

TypeScript source

editor.ts

export class BasicEditor {
	title = 'Release notes';
	#saved = new WeakMap<object, string>();
	capture(): object {
		const token = Object.freeze({});
		this.#saved.set(token, this.title);
		return token;
	}
	restore(token: object): void {
		const title = this.#saved.get(token);
		if (title === undefined) throw new Error('foreign-checkpoint');
		this.title = title;
	}
}

export type Block = { text: string; accent: boolean };
export type DocumentState = { title: string; layout: { columns: number }; blocks: Block[] };
export type Connection = 'online' | 'offline';
export type EditorView = {
	documentID: string;
	state: DocumentState;
	connection: Connection;
	preview: string | null;
};
// The private WeakMap, not this type assertion, enforces token membership at runtime.
declare const checkpointBrand: unique symbol;
export type Checkpoint = Readonly<{ [checkpointBrand]: true }>;

function copyState(state: DocumentState): DocumentState {
	return {
		title: state.title,
		layout: { ...state.layout },
		blocks: state.blocks.map((block) => ({ ...block }))
	};
}
export class NewsletterEditor {
	#documentID: string;
	#state: DocumentState = {
		title: 'Release notes',
		layout: { columns: 1 },
		blocks: [
			{ text: 'Welcome', accent: false },
			{ text: 'Changelog', accent: true }
		]
	};
	#connection: Connection = 'online';
	#preview: string | null = null;
	#saved = new WeakMap<Checkpoint, DocumentState>();
	constructor(documentID = 'newsletter-a') {
		this.#documentID = documentID;
	}
	capture(): Checkpoint {
		const token = Object.freeze({}) as Checkpoint;
		this.#saved.set(token, copyState(this.#state));
		return token;
	}
	restore(token: Checkpoint): void {
		const saved = this.#saved.get(token);
		if (!saved) throw new Error('foreign-checkpoint');
		this.#state = copyState(saved); // Copy again: future edits must not change the checkpoint.
		this.#preview = null; // The current connection and document identity are not restored.
	}
	edit(title: string, columns: number, firstText: string, accent: boolean): void {
		if (title.length === 0) throw new Error('empty-title');
		if (!Number.isInteger(columns) || columns < 1 || columns > 3)
			throw new Error('invalid-columns');
		if (firstText.length === 0) throw new Error('empty-block');
		this.#state.title = title;
		this.#state.layout.columns = columns;
		this.#state.blocks[0].text = firstText;
		this.#state.blocks[0].accent = accent;
		this.#preview = null;
	}
	setConnection(connection: Connection): void {
		this.#connection = connection;
	}
	renderPreview(): void {
		this.#preview = contentSummary(this.#state);
	}
	view(): EditorView {
		return {
			documentID: this.#documentID,
			state: copyState(this.#state),
			connection: this.#connection,
			preview: this.#preview
		};
	}
	captureShallowForComparison(): Checkpoint {
		const token = Object.freeze({}) as Checkpoint;
		this.#saved.set(token, { ...this.#state });
		return token; // Wrong for mutable nested data: layout and blocks remain shared.
	}
}

export class CheckpointHistory {
	#editor: NewsletterEditor;
	#limit: number;
	#capture: () => Checkpoint;
	#entries: { label: string; token: Checkpoint }[] = [];
	constructor(editor: NewsletterEditor, limit = 3, capture = () => editor.capture()) {
		if (!Number.isInteger(limit) || limit < 1 || limit > 5) throw new Error('invalid-capacity');
		this.#editor = editor;
		this.#limit = limit;
		this.#capture = capture;
	}
	save(label: string): void {
		if (label.length === 0) throw new Error('empty-label');
		const token = this.#capture();
		this.#entries.push({ label, token });
		if (this.#entries.length > this.#limit) this.#entries.shift();
	}
	restore(index: number): void {
		if (!Number.isInteger(index) || index < 0 || index >= this.#entries.length)
			throw new Error('missing-checkpoint');
		this.#editor.restore(this.#entries[index].token);
	}
	labels(): string[] {
		return this.#entries.map((entry) => entry.label);
	}
	clear(): void {
		this.#entries = [];
	}
}

export function contentSummary(state: DocumentState): string {
	return `${state.title}/${state.layout.columns}/${state.blocks[0].text}/${state.blocks[0].accent ? 1 : 0}`;
}
export function summary(editor: NewsletterEditor, history: CheckpointHistory): string {
	const view = editor.view();
	return `${contentSummary(view.state)}|${view.connection}|${view.preview ?? '-'}|${history.labels().join(',') || '-'}`;
}
export function runExample(): void {
	const editor = new NewsletterEditor();
	const history = new CheckpointHistory(editor, 3);
	history.save('Before redesign');
	editor.edit('Launch edition', 2, 'Shipping today', true);
	editor.setConnection('offline');
	editor.renderPreview();
	console.log(summary(editor, history));
	history.restore(0);
	console.log(summary(editor, history));
}

runExample();

Go source

editor.go

package main

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

// Nonzero size matters: distinct zero-sized Go allocations may compare equal.
type ownerTag struct{ marker byte }

type BasicCheckpoint struct {
	owner *ownerTag
	title string
}
type BasicEditor struct {
	Title string
	owner *ownerTag
}

func NewBasicEditor() *BasicEditor              { return &BasicEditor{"Release notes", &ownerTag{}} }
func (e *BasicEditor) Capture() BasicCheckpoint { return BasicCheckpoint{e.owner, e.Title} }
func (e *BasicEditor) Restore(saved BasicCheckpoint) error {
	if saved.owner == nil || saved.owner != e.owner {
		return errors.New("foreign-checkpoint")
	}
	e.Title = saved.title
	return nil
}


type Block struct {
	Text   string
	Accent bool
}
type Layout struct{ Columns int }
type DocumentState struct {
	Title  string
	Layout Layout
	Blocks []Block
}
type EditorView struct {
	DocumentID string
	State      DocumentState
	Connection string
	Preview    *string
}
type checkpointData struct {
	owner *ownerTag
	state DocumentState
}
type Checkpoint struct{ data *checkpointData } // Private payload; history uses only the token.

func copyState(state DocumentState) DocumentState {
	return DocumentState{Title: state.Title, Layout: state.Layout, Blocks: append([]Block{}, state.Blocks...)}
}

type NewsletterEditor struct {
	documentID string
	owner      *ownerTag
	state      DocumentState
	connection string
	preview    *string
}

func NewEditor(documentID string) *NewsletterEditor {
	return &NewsletterEditor{
		documentID: documentID,
		owner:      &ownerTag{},
		state: DocumentState{
			Title:  "Release notes",
			Layout: Layout{Columns: 1},
			Blocks: []Block{{Text: "Welcome"}, {Text: "Changelog", Accent: true}},
		},
		connection: "online",
	}
}
func (e *NewsletterEditor) Capture() Checkpoint {
	return Checkpoint{&checkpointData{e.owner, copyState(e.state)}}
}
func (e *NewsletterEditor) Restore(token Checkpoint) error {
	if token.data == nil || token.data.owner != e.owner {
		return errors.New("foreign-checkpoint")
	}
	e.state = copyState(token.data.state) // Future edits cannot mutate the saved checkpoint.
	e.preview = nil                       // Keep the current connection and document ID.
	return nil
}
func (e *NewsletterEditor) Edit(title string, columns float64, text string, accent bool) error {
	if title == "" {
		return errors.New("empty-title")
	}
	if math.IsNaN(columns) || math.IsInf(columns, 0) || math.Trunc(columns) != columns || columns < 1 || columns > 3 {
		return errors.New("invalid-columns")
	}
	if text == "" {
		return errors.New("empty-block")
	}
	e.state.Title = title
	e.state.Layout.Columns = int(columns)
	e.state.Blocks[0] = Block{text, accent}
	e.preview = nil
	return nil
}
func (e *NewsletterEditor) SetConnection(online bool) {
	if online {
		e.connection = "online"
	} else {
		e.connection = "offline"
	}
}
func (e *NewsletterEditor) RenderPreview() { value := contentSummary(e.state); e.preview = &value }
func (e *NewsletterEditor) View() EditorView {
	var preview *string
	if e.preview != nil {
		value := *e.preview
		preview = &value
	}
	return EditorView{DocumentID: e.documentID, State: copyState(e.state), Connection: e.connection, Preview: preview}
}

type entry struct {
	label string
	token Checkpoint
}
type CheckpointHistory struct {
	editor  *NewsletterEditor
	limit   int
	entries []entry
}

func NewHistory(editor *NewsletterEditor, limit int) (*CheckpointHistory, error) {
	if limit < 1 || limit > 5 {
		return nil, errors.New("invalid-capacity")
	}
	return &CheckpointHistory{editor: editor, limit: limit}, nil
}
func (h *CheckpointHistory) Save(label string) error {
	if label == "" {
		return errors.New("empty-label")
	}
	h.entries = append(h.entries, entry{label, h.editor.Capture()})
	if len(h.entries) > h.limit {
		copy(h.entries, h.entries[1:])
		h.entries[len(h.entries)-1] = entry{}
		h.entries = h.entries[:len(h.entries)-1]
	}
	return nil
}
func (h *CheckpointHistory) Restore(index int) error {
	if index < 0 || index >= len(h.entries) {
		return errors.New("missing-checkpoint")
	}
	return h.editor.Restore(h.entries[index].token)
}
func (h *CheckpointHistory) Labels() []string {
	result := make([]string, len(h.entries))
	for i, e := range h.entries {
		result[i] = e.label
	}
	return result
}
func (h *CheckpointHistory) Clear() { h.entries = nil }


func contentSummary(state DocumentState) string {
	accent := 0
	if state.Blocks[0].Accent {
		accent = 1
	}
	return fmt.Sprintf("%s/%d/%s/%d", state.Title, state.Layout.Columns, state.Blocks[0].Text, accent)
}
func summary(editor *NewsletterEditor, history *CheckpointHistory) string {
	view := editor.View()
	preview := "-"
	if view.Preview != nil {
		preview = *view.Preview
	}
	labels := strings.Join(history.Labels(), ",")
	if labels == "" {
		labels = "-"
	}
	return fmt.Sprintf("%s|%s|%s|%s", contentSummary(view.State), view.Connection, preview, labels)
}

func runExample() error {
	editor := NewEditor("newsletter-a")
	history, err := NewHistory(editor, 3)
	if err != nil {
		return err
	}
	if err := history.Save("Before redesign"); err != nil {
		return err
	}
	if err := editor.Edit("Launch edition", 2, "Shipping today", true); err != nil {
		return err
	}
	editor.SetConnection(false)
	editor.RenderPreview()
	fmt.Println(summary(editor, history))
	if err := history.Restore(0); err != nil {
		return err
	}
	fmt.Println(summary(editor, history))
	return nil
}

func main() {
	if err := runExample(); err != nil {
		panic(err)
	}
}

Python source

editor.py

"""Capture and restore a newsletter editor's state with named checkpoints."""

from __future__ import annotations

from dataclasses import dataclass
import math
from typing import Callable


class BasicEditor:
    def __init__(self) -> None:
        self.title = "Release notes"
        self._saved: dict[object, str] = {}

    def capture(self) -> object:
        token = object()
        self._saved[token] = self.title
        return token

    def restore(self, token: object) -> None:
        if token not in self._saved:
            raise ValueError("foreign-checkpoint")
        self.title = self._saved[token]




@dataclass(slots=True)
class Block:
    text: str
    accent: bool = False


@dataclass(slots=True)
class Layout:
    columns: int


@dataclass(slots=True)
class DocumentState:
    title: str
    layout: Layout
    blocks: list[Block]


@dataclass(slots=True)
class EditorView:
    document_id: str
    state: DocumentState
    connection: str
    preview: str | None


def copy_state(state: DocumentState) -> DocumentState:
    return DocumentState(
        state.title,
        Layout(state.layout.columns),
        [Block(block.text, block.accent) for block in state.blocks],
    )


class Checkpoint:
    """A token whose payload is private by Python convention."""

    __slots__ = ("_owner", "_state")

    def __init__(self, owner: object, state: DocumentState) -> None:
        self._owner = owner
        self._state = state


class NewsletterEditor:
    def __init__(self, document_id: str = "newsletter-a") -> None:
        self._document_id = document_id
        self._owner = object()
        self._state = DocumentState(
            "Release notes",
            Layout(1),
            [Block("Welcome"), Block("Changelog", True)],
        )
        self._connection = "online"
        self._preview: str | None = None

    def capture(self) -> Checkpoint:
        return Checkpoint(self._owner, copy_state(self._state))

    def restore(self, token: Checkpoint) -> None:
        if not isinstance(token, Checkpoint) or token._owner is not self._owner:
            raise ValueError("foreign-checkpoint")
        self._state = copy_state(token._state)
        self._preview = None

    def edit(self, title: str, columns: float, text: str, accent: bool) -> None:
        if len(title) == 0:
            raise ValueError("empty-title")
        if (
            isinstance(columns, bool)
            or not isinstance(columns, (int, float))
            or not math.isfinite(float(columns))
            or not float(columns).is_integer()
            or not 1 <= columns <= 3
        ):
            raise ValueError("invalid-columns")
        if len(text) == 0:
            raise ValueError("empty-block")
        self._state.title = title
        self._state.layout.columns = int(columns)
        self._state.blocks[0] = Block(text, accent)
        self._preview = None

    def set_connection(self, connection: str) -> None:
        if connection not in ("online", "offline"):
            raise ValueError("invalid-connection")
        self._connection = connection

    def render_preview(self) -> None:
        self._preview = content_summary(self._state)

    def view(self) -> EditorView:
        return EditorView(
            self._document_id,
            copy_state(self._state),
            self._connection,
            self._preview,
        )


@dataclass(slots=True)
class Entry:
    label: str
    token: Checkpoint


class CheckpointHistory:
    def __init__(
        self,
        editor: NewsletterEditor,
        limit: int = 3,
        capture: Callable[[], Checkpoint] | None = None,
    ) -> None:
        if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 5:
            raise ValueError("invalid-capacity")
        self._editor = editor
        self._limit = limit
        self._capture = capture or editor.capture
        self._entries: list[Entry] = []

    def save(self, label: str) -> None:
        if len(label) == 0:
            raise ValueError("empty-label")
        self._entries.append(Entry(label, self._capture()))
        if len(self._entries) > self._limit:
            self._entries.pop(0)

    def restore(self, index: int) -> None:
        if (
            isinstance(index, bool)
            or not isinstance(index, (int, float))
            or not math.isfinite(float(index))
            or not float(index).is_integer()
            or not 0 <= index < len(self._entries)
        ):
            raise ValueError("missing-checkpoint")
        self._editor.restore(self._entries[int(index)].token)

    def labels(self) -> list[str]:
        return [entry.label for entry in self._entries]

    def clear(self) -> None:
        self._entries.clear()


def content_summary(state: DocumentState) -> str:
    return f"{state.title}/{state.layout.columns}/{state.blocks[0].text}/{int(state.blocks[0].accent)}"


def summary(editor: NewsletterEditor, history: CheckpointHistory) -> str:
    view = editor.view()
    return (
        f"{content_summary(view.state)}|{view.connection}|"
        f"{view.preview or '-'}|{','.join(history.labels()) or '-'}"
    )




def run_example() -> None:
    editor = NewsletterEditor()
    history = CheckpointHistory(editor)
    history.save("Before redesign")
    editor.edit("Launch edition", 2, "Shipping today", True)
    editor.set_connection("offline")
    editor.render_preview()
    print(summary(editor, history))
    history.restore(0)
    print(summary(editor, history))




if __name__ == "__main__":
    run_example()

Java source

MementoExample.java

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

final class BasicEditor {
    private String title = "Release notes";

    static final class Checkpoint {
        private final Object owner;
        private final String title;

        private Checkpoint(Object owner, String title) {
            this.owner = owner;
            this.title = title;
        }
    }

    private final Object owner = new Object();

    Checkpoint capture() {
        return new Checkpoint(owner, title);
    }

    void restore(Checkpoint token) {
        if (token == null || token.owner != owner) throw new IllegalArgumentException("foreign-checkpoint");
        title = token.title;
    }

    String title() {
        return title;
    }
}

record Block(String text, boolean accent) {}

record Layout(int columns) {}

record DocumentState(String title, Layout layout, List<Block> blocks) {}

record EditorView(String documentId, DocumentState state, String connection, String preview) {}

final class NewsletterEditor {
    static final class Checkpoint {
        private final Object owner;
        private final DocumentState state;

        private Checkpoint(Object owner, DocumentState state) {
            this.owner = owner;
            this.state = state;
        }
    }

    private final String documentId;
    private final Object owner = new Object();
    private DocumentState state;
    private String connection = "online";
    private String preview;

    NewsletterEditor() {
        this("newsletter-a");
    }

    NewsletterEditor(String documentId) {
        this.documentId = documentId;
        state = new DocumentState(
                "Release notes",
                new Layout(1),
                List.of(new Block("Welcome", false), new Block("Changelog", true)));
    }

    Checkpoint capture() {
        return new Checkpoint(owner, copyState(state));
    }

    void restore(Checkpoint token) {
        if (token == null || token.owner != owner) {
            throw new IllegalArgumentException("foreign-checkpoint");
        }
        state = copyState(token.state);
        preview = null;
    }

    void edit(String title, double columns, String text, boolean accent) {
        if (title.isEmpty()) throw new IllegalArgumentException("empty-title");
        if (!Double.isFinite(columns) || columns != Math.rint(columns) || columns < 1 || columns > 3) {
            throw new IllegalArgumentException("invalid-columns");
        }
        if (text.isEmpty()) throw new IllegalArgumentException("empty-block");
        List<Block> blocks = new ArrayList<>(state.blocks());
        blocks.set(0, new Block(text, accent));
        state = new DocumentState(title, new Layout((int) columns), List.copyOf(blocks));
        preview = null;
    }

    void setConnection(String connection) {
        if (!connection.equals("online") && !connection.equals("offline")) {
            throw new IllegalArgumentException("invalid-connection");
        }
        this.connection = connection;
    }

    void renderPreview() {
        preview = MementoFormatting.contentSummary(state);
    }

    EditorView view() {
        return new EditorView(documentId, copyState(state), connection, preview);
    }

    private static DocumentState copyState(DocumentState source) {
        return new DocumentState(source.title(), new Layout(source.layout().columns()), List.copyOf(source.blocks()));
    }
}

record Entry(String label, NewsletterEditor.Checkpoint token) {}

final class CheckpointHistory {
    private final NewsletterEditor editor;
    private final int limit;
    private final List<Entry> entries = new ArrayList<>();

    CheckpointHistory(NewsletterEditor editor, int limit) {
        if (limit < 1 || limit > 5) throw new IllegalArgumentException("invalid-capacity");
        this.editor = editor;
        this.limit = limit;
    }

    void save(String label) {
        if (label.isEmpty()) throw new IllegalArgumentException("empty-label");
        entries.add(new Entry(label, editor.capture()));
        if (entries.size() > limit) entries.remove(0);
    }

    void restore(int index) {
        if (index < 0 || index >= entries.size()) {
            throw new IllegalArgumentException("missing-checkpoint");
        }
        editor.restore(entries.get(index).token());
    }

    List<String> labels() {
        return List.copyOf(entries.stream().map(Entry::label).toList());
    }

    void clear() {
        entries.clear();
    }
}

final class MementoFormatting {
    private MementoFormatting() {}

    static String contentSummary(DocumentState state) {
        return "%s/%d/%s/%d".formatted(
                state.title(),
                state.layout().columns(),
                state.blocks().get(0).text(),
                state.blocks().get(0).accent() ? 1 : 0);
    }

    static String summary(NewsletterEditor editor, CheckpointHistory history) {
        EditorView view = editor.view();
        return "%s|%s|%s|%s".formatted(
                contentSummary(view.state()),
                view.connection(),
                view.preview() == null ? "-" : view.preview(),
                String.join(",", history.labels()).isEmpty() ? "-" : String.join(",", history.labels()));
    }
}


public final class MementoExample {
    private MementoExample() {}

    static List<String> runExample() {
        NewsletterEditor editor = new NewsletterEditor();
        CheckpointHistory history = new CheckpointHistory(editor, 3);
        history.save("Before redesign");
        editor.edit("Launch edition", 2, "Shipping today", true);
        editor.setConnection("offline");
        editor.renderPreview();
        List<String> output = new ArrayList<>();
        output.add(MementoFormatting.summary(editor, history));
        history.restore(0);
        output.add(MementoFormatting.summary(editor, history));
        return output;
    }

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

Rust source

editor.rs

mod document {
    use std::rc::Rc;
    pub struct BasicCheckpoint {
        owner: Rc<()>,
        title: String,
    }
    pub struct BasicEditor {
        pub title: String,
        owner: Rc<()>,
    }
    impl BasicEditor {
        pub fn new() -> Self {
            Self {
                title: "Release notes".into(),
                owner: Rc::new(()),
            }
        }
        pub fn capture(&self) -> BasicCheckpoint {
            BasicCheckpoint {
                owner: Rc::clone(&self.owner),
                title: self.title.clone(),
            }
        }
        pub fn restore(&mut self, saved: &BasicCheckpoint) -> Result<(), String> {
            if !Rc::ptr_eq(&self.owner, &saved.owner) {
                return Err("foreign-checkpoint".into());
            }
            self.title = saved.title.clone();
            Ok(())
        }
    }
    #[derive(Clone, Debug, PartialEq)]
    pub struct Block {
        pub text: String,
        pub accent: bool,
    }
    #[derive(Clone, Debug, PartialEq)]
    pub struct Layout {
        pub columns: i32,
    }
    #[derive(Clone, Debug, PartialEq)]
    pub struct DocumentState {
        pub title: String,
        pub layout: Layout,
        pub blocks: Vec<Block>,
    }
    #[derive(Clone, Debug, PartialEq)]
    pub struct EditorView {
        pub document_id: String,
        pub state: DocumentState,
        pub online: bool,
        pub preview: Option<String>,
    }
    pub struct Checkpoint {
        owner: Rc<()>,
        state: DocumentState,
    } // Private within this module.
    pub struct NewsletterEditor {
        document_id: String,
        owner: Rc<()>,
        state: DocumentState,
        online: bool,
        preview: Option<String>,
    }
    impl NewsletterEditor {
        pub fn new(document_id: &str) -> Self {
            Self {
                document_id: document_id.into(),
                owner: Rc::new(()),
                state: DocumentState {
                    title: "Release notes".into(),
                    layout: Layout { columns: 1 },
                    blocks: vec![
                        Block {
                            text: "Welcome".into(),
                            accent: false,
                        },
                        Block {
                            text: "Changelog".into(),
                            accent: true,
                        },
                    ],
                },
                online: true,
                preview: None,
            }
        }
        pub fn capture(&self) -> Checkpoint {
            Checkpoint {
                owner: Rc::clone(&self.owner),
                state: self.state.clone(),
            }
        }
        pub fn restore(&mut self, token: &Checkpoint) -> Result<(), String> {
            if !Rc::ptr_eq(&self.owner, &token.owner) {
                return Err("foreign-checkpoint".into());
            }
            self.state = token.state.clone();
            self.preview = None;
            Ok(())
        }
        pub fn edit(
            &mut self,
            title: &str,
            columns: f64,
            text: &str,
            accent: bool,
        ) -> Result<(), String> {
            if title.is_empty() {
                return Err("empty-title".into());
            }
            if !columns.is_finite() || columns.fract() != 0.0 || !(1.0..=3.0).contains(&columns) {
                return Err("invalid-columns".into());
            }
            if text.is_empty() {
                return Err("empty-block".into());
            }
            self.state.title = title.into();
            self.state.layout.columns = columns as i32;
            self.state.blocks[0] = Block {
                text: text.into(),
                accent,
            };
            self.preview = None;
            Ok(())
        }
        pub fn set_connection(&mut self, online: bool) {
            self.online = online;
        }
        pub fn render_preview(&mut self) {
            self.preview = Some(content_summary(&self.state));
        }
        pub fn view(&self) -> EditorView {
            EditorView {
                document_id: self.document_id.clone(),
                state: self.state.clone(),
                online: self.online,
                preview: self.preview.clone(),
            }
        }
    }
    pub fn content_summary(state: &DocumentState) -> String {
        format!(
            "{}/{}/{}/{}",
            state.title,
            state.layout.columns,
            state.blocks[0].text,
            if state.blocks[0].accent { 1 } else { 0 }
        )
    }
}
use document::{content_summary, BasicEditor, Checkpoint, NewsletterEditor};
struct Entry {
    label: String,
    token: Checkpoint,
}
struct CheckpointHistory {
    limit: usize,
    entries: Vec<Entry>,
}
impl CheckpointHistory {
    fn new(limit: usize) -> Result<Self, String> {
        if !(1..=5).contains(&limit) {
            return Err("invalid-capacity".into());
        }
        Ok(Self {
            limit,
            entries: vec![],
        })
    }
    fn save(&mut self, editor: &NewsletterEditor, label: &str) -> Result<(), String> {
        if label.is_empty() {
            return Err("empty-label".into());
        }
        self.entries.push(Entry {
            label: label.into(),
            token: editor.capture(),
        });
        if self.entries.len() > self.limit {
            self.entries.remove(0);
        }
        Ok(())
    }
    fn restore(&self, editor: &mut NewsletterEditor, index: usize) -> Result<(), String> {
        let entry = self.entries.get(index).ok_or("missing-checkpoint")?;
        editor.restore(&entry.token)
    }
    fn labels(&self) -> Vec<String> {
        self.entries
            .iter()
            .map(|entry| entry.label.clone())
            .collect()
    }
    fn clear(&mut self) {
        self.entries.clear();
    }
}
fn summary(editor: &NewsletterEditor, history: &CheckpointHistory) -> String {
    let view = editor.view();
    let labels = history.labels().join(",");
    format!(
        "{}|{}|{}|{}",
        content_summary(&view.state),
        if view.online { "online" } else { "offline" },
        view.preview.as_deref().unwrap_or("-"),
        if labels.is_empty() { "-" } else { &labels }
    )
}
fn run_example() -> Result<(), String> {
    let mut editor = NewsletterEditor::new("newsletter-a");
    let mut history = CheckpointHistory::new(3)?;
    history.save(&editor, "Before redesign")?;
    editor.edit("Launch edition", 2.0, "Shipping today", true)?;
    editor.set_connection(false);
    editor.render_preview();
    println!("{}", summary(&editor, &history));
    history.restore(&mut editor, 0)?;
    println!("{}", summary(&editor, &history));
    history.clear();
    Ok(())
}
fn main() -> Result<(), String> {
    run_example()?;
    let mut basic = BasicEditor::new();
    let saved = basic.capture();
    basic.title = "Changed".into();
    basic.restore(&saved)?;
    println!("basic: {}", basic.title);
    Ok(())
}

At the call site, “Before redesign” captures Release notes, one column, and Welcome. After a redesign, the connection goes offline and a preview is rendered. Restoring the checkpoint brings back the original content, leaves the connection offline, and clears the preview. The checkpoint remains available for another restore.

The shared contract and its boundariesValidation, membership, and retention

Titles, first-block text, and checkpoint labels must be nonempty. They are preserved exactly, including spaces and Unicode; the model does not trim them or impose a text-length policy. Columns must be finite whole numbers from 1 to 3. The editor checks the title, columns, then block text before changing any field. An invalid edit leaves the preview intact. Every accepted edit clears it, even if the new values equal the current ones.

Capture has no effect on the live content or preview. Restore validates the checkpoint’s owner before changing state. Two editors with the same document ID still have different checkpoint membership. A missing history entry or foreign checkpoint leaves the document and history unchanged.

History keeps between one and five checkpoints, oldest first. Save appends a checkpoint and releases the oldest entry if needed. Restore neither consumes the checkpoint nor deletes later entries. Duplicate labels are allowed because entries are distinct. Clear releases the collection without altering the document. These are named checkpoints, rather than a linear undo/redo history.

Reading the TypeScriptPrivate state behind an empty token

Each editor has a runtime-private #saved WeakMap. A frozen empty object acts as the checkpoint key. The branded TypeScript type discourages accidental substitution, while membership in this editor’s map performs the actual runtime check. The token contains no public document fields.

copyState copies the layout object, the blocks array, and every block record. It runs at capture and again at restore. Those records contain only a string and a boolean today. The deliberately shallow capture skips that separation so the browser can execute the mistake being discussed.

A WeakMap does not keep its keys alive. History’s entries do retain their tokens; removing an entry can make its saved state collectible when no other holder retains the token. Collection timing is unspecified. A token cannot be serialized to recover the map’s private payload.

Reading the GoA package boundary and copied slice storage

A checkpoint wraps private data containing an owner tag and saved state. Unexported fields protect the representation across a package boundary. The copyable file places everything in package main; its caretaker follows that boundary by convention. A library should put the editor and checkpoint in their own package when it needs the compiler to enforce the separation from callers.

The layout struct copies by value, but the block slice needs a new backing array. Its string and boolean elements then copy independently. The owner tag has nonzero size so pointer identity does not rely on the special rules for zero-sized allocations. Restore checks membership and copies the saved content before exposing it to future edits.

History zeroes an evicted entry before shrinking the slice, releasing its token reference from the retained backing array. Inspection returns copies of the blocks, labels, and optional preview value.

Reading the PythonDataclasses and defensive copies

Python models the document with mutable dataclasses and gives each editor an owner object. copy_state reconstructs the nested dataclasses at capture, restore, and view. The checkpoint payload uses underscore-prefixed fields: Python makes that an API convention rather than a compiler-enforced privacy boundary.

The history object stores only the checkpoint reference and label, evicts the oldest entry with pop(0), and returns a new label list. The editor keeps the owner check and the second copy, so a later edit cannot rewrite a retained checkpoint.

03 / Follow the values

A saved reference can quietly become the present.

Save Original, then choose Try redesign. Take the simulated connection offline and render a preview. Before restoring Original, predict which content fields should return and which runtime fields should stay current.

With shallow capture, the old title comes back but the layout and blocks remain changed. Switch to Independent memento, which resets the document, and repeat. Then edit after a restore and restore the same checkpoint again: the saved version should still be intact.

Keep a way back before trying a change.

Save Original, try the redesign, take the simulated connection offline, and render a preview. Predict what restoring Original should change.

Capture rule

Keep latest

Changing either setting starts a fresh document. This limit counts checkpoints, not bytes.

Current document · originator

newsletter-a

Release notes

1 column

Welcome

Plain

Changelog

Emphasized

Outside the checkpoint

Connection: online

Preview: not rendered

Retained checkpoints · caretaker

0 / 3 retained

No checkpoint yet. Capture the state you want to return to.

History stores labels and tokens. Only the editor understands the saved document fields.

Simulated connection

Save a checkpoint before trying the redesign.

Try a checkpoint from another editor

This creates a second editor with the same document ID and tries its checkpoint here. Membership belongs to the editor instance, not to matching ID text.

Fixed example: Original contains Release notes, one column, and Welcome. After a redesign, restoring the shallow capture brings back the title but keeps two columns and Shipping today. An independent memento restores all original content. Both keep the current connection offline and clear the preview. Interactive controls require JavaScript.

The browser runs the displayed TypeScript editor; the Python, Java, Go, and Rust files are checked natively against the same contract. Shallow mode is the intentional TypeScript failure. The comparison after Restore reads a separate record of what was on screen at capture, never the token.

The deliberate shallow-capture mistakeTypeScript comparison only

editor.ts · shallow comparison

captureShallowForComparison(): Checkpoint {
	const token = Object.freeze({}) as Checkpoint;
	this.#saved.set(token, { ...this.#state });
	return token; // Wrong for mutable nested data: layout and blocks remain shared.
}

The spread makes a new outer record, but its layout and blocks still refer to the live objects. Updating the title assigns a separate top-level string. Updating the columns or a block mutates objects the checkpoint still shares. A later deep copy during Restore can only copy the state that remains; it cannot recover the values already overwritten.

Copying only during Capture has a different failure. If Restore installs the checkpoint’s mutable objects directly, the next edit can corrupt the saved version. Independent working state is needed on both sides of the boundary. Immutable state can satisfy that requirement through a retained version instead.

In Go, plain assignment would copy the value-only layout but share the slice storage; the implementations keep their nested state independent.

04 / Try a decision

The second restoration is part of the promise.

A checkpoint may be retained while several working versions come and go. Trace the references after Restore as carefully as you traced them at Capture.

Reason through the alternatives

Copy on capture, then install the saved mutable objects directly on restore. Capture protects the checkpoint from the first round of edits. Directly installing those saved objects makes the next edit mutate the checkpoint itself. A second restore can no longer recover the original values.

Let the editor isolate saved mutable state at capture and again at restore. The editor keeps the checkpoint independent from each editable working state. History needs only the opaque token and metadata. Restoring it again returns the same content; runtime connection status stays current and the cached preview is cleared.

Give history every internal field and have it reconstruct the editor. This can recreate the values today, but history now knows the editor’s layout and block schema. A new field creates another place that must understand restoration. The Memento boundary keeps that knowledge with the object whose state is being restored.

Describe what Cancel should restore in your own editor.

Which fields are restorable content? Which are current runtime state? Who owns capture, restore, and the decision to keep or release a checkpoint?

This note is local to the page. It is not saved or automatically assessed.

05 / Give it a real job

The edit session chooses when. The editor chooses what.

When a local redesign dialog opens, its controller asks the editor for a checkpoint. Preview controls apply edits through the editor. Cancel restores the checkpoint; Apply accepts the current content and releases that temporary checkpoint. Our lab retains named checkpoints so you can compare several versions, but the same capture/restore responsibility works with a single dialog-owned token.

The caretaker chooses retention and ordering. It can display “Before redesign” without knowing how columns or blocks are represented. Now add a nested style range to each block. The editor’s state, copy rule, and tests must change. History’s Save and Restore operations still hand around the same checkpoint type.

Capture before the operation you want to cancel. Capturing when Cancel is clicked only remembers the already changed document. If a multi-step edit can fail halfway through, decide whether the controller must restore on that failure too, or whether the editor can prepare and validate a complete replacement before committing it.

Build UIs?Every SvelteKit page snapshot is a checkpoint the router keeps for you. Dragging a card on a task board is where you choose what to capture.

Where it already is in your components

You probably already follow this rule if a SvelteKit page keeps a half-written draft: whatever the page’s snapshot captures has to be plain JSON. Capture a Set of chosen recipients and Back still brings it back, but reload the page and the restore breaks. The reason is that SvelteKit runs a Memento for you.

A +page.svelte can export a snapshot with capture and restore. The page is the originator: it decides that the reply text and the chosen recipients belong in the checkpoint. SvelteKit is the caretaker. Just before you navigate away, it calls capture and files the value under that history entry without looking inside. When you return with Back or Forward, it hands the value to restore. Following a link to the same page makes a new history entry, so that visit starts empty.

The caretaker keeps the checkpoint in two forms. During the visit it holds the object in memory, and in our Chromium run Back handed restore the very object capture had returned. When the tab is hidden or unloads, SvelteKit 2.70.3 writes every snapshot to sessionStorage with JSON.stringify, and a reload parses them back. That copy is why the docs say the data “must be serializable as JSON.” After a reload, a captured Set came back as {}, a Date as a string, and an undefined field not at all, and the restore loop threw “TypeError: saved.cc is not iterable.” So the page turns its state into plain data in capture and rebuilds its own types in restore, just as our editor copies on both sides of a checkpoint.

src/routes/tickets/[id]/+page.svelte

<script lang="ts">
	import type { Snapshot } from '@sveltejs/kit';
	import { SvelteSet } from 'svelte/reactivity';

	const teammates = ['Ana', 'Kofi', 'Mei'];
	let reply = $state('');
	const cc = new SvelteSet<string>();

	// Back hands restore the object capture returned. A reload reads it back from
	// sessionStorage as JSON, where a Set becomes {}, so capture keeps plain data.
	export const snapshot: Snapshot<{ reply: string; cc: string[] }> = {
		capture: () => ({ reply, cc: [...cc] }),
		restore: (saved) => {
			reply = saved.reply;
			cc.clear();
			for (const name of saved.cc) cc.add(name);
		}
	};
</script>

<textarea bind:value={reply} aria-label="Reply"></textarea>
{#each teammates as name (name)}
	<label>
		<input
			type="checkbox"
			checked={cc.has(name)}
			onchange={(event) => (event.currentTarget.checked ? cc.add(name) : cc.delete(name))}
		/>
		Copy {name}
	</label>
{/each}

When you have to own it

Now you’re building a task board. Dragging a card to another column moves it on screen at once and sends the change to the server. If the server refuses, the card has to go back. That is a checkpoint you own: capture before the optimistic move, restore when the request fails.

In React the capture looks free. The React tutorial names the benefit of replacing state instead of changing it: “Avoiding direct data mutation lets you keep previous versions of the data intact, and reuse them later.” So const before = board is a snapshot only while every update copies. When a move used splice and push on the current arrays, our rollback left the card where the failed request had put it. In Svelte the board is a deep $state proxy that you do change in place, so const before = board follows every later edit, and $state.snapshot(board) is the copy that stays put.

The harder decision is what the checkpoint holds. Drag card A, then card B while A’s request is still pending. If B’s request succeeds and A’s fails, restoring the whole board from before A’s move sends B back too, although the server accepted it. In our React run, whole-board rollback put both cards back in To do, while a checkpoint holding only A’s column and position returned A and left B where it was. Capture what this one move changed, and restore it onto the current board with a functional update.

Where local restoration stopsPersistence, side effects, and session lifetime

A checkpoint here is valid only for its creating editor instance. Reopening the same persisted document creates a new owner. Long-lived checkpoints need an explicit serialized schema, version compatibility, validation, and migration rules; a runtime token is not a durable format.

A request already in flight keeps running after a restore; its completion may need a generation or version check before updating the view.

Clear history when the document session ends. The retention count bounds only this caretaker’s entries; another caller can still retain a captured token. Releasing a reference does not guarantee reclamation, let alone secure erasure.

06 / Already in your toolbox

Look for the state boundary in a familiar API.

Each of these APIs draws its own line around what gets saved and who can read it.

Canvas · `save` and `restore`

The drawing context retains and restores drawing state such as transforms, clipping, and styles. The bitmap is outside that state, and the current path is separate too. Restoring a drawing state does not erase pixels you drew. It is a concrete reminder to name what a snapshot includes.

Read the canvas state contract ↗

CodeMirror · immutable editor state

CodeMirror’s state and document structures are immutable; updates produce new states. An old state stays a version that later edits cannot mutate. That state is publicly readable, so the protection comes from immutability rather than an opaque token.

Read the state model ↗

.NET · `IEditableObject`

The interface names BeginEdit, CancelEdit, and EndEdit. Cancel discards changes since editing began. That gives application controls a restoration boundary while the object owns its editing behavior, including how it remembers the earlier values.

Read the edit-session contract ↗

07 / When it earns its place

Choose the representation around the work you need to preserve.

Memento helps when restoration involves internal state that callers should not reconstruct: editor checkpoints, reversible local operations, or a model with an explicit Cancel boundary. Keep a direct draft or a few old scalar values when those already express the whole requirement clearly.

This example copies all document content at Capture and Restore. Work grows with the content being copied, and retained copies consume space. For a large editor or frequent checkpoints, consider immutable versions with structural sharing, grouped changes, deltas, or periodic snapshots. Measure the workload you actually have.

Inverse operations can be smaller and more precise when an edit has a reliable inverse. A full checkpoint is convenient when many internal fields change together. Commands can retain mementos for their undo behavior, but Memento alone does not decide gesture grouping, redo branching, or how to merge concurrent edits.

Opacity is an interface decisionMetadata, immutable values, and security

Useful checkpoint metadata can be public: a label, creation time, or a version identifier. That does not require exposing every restorable field. The boundary matters when it keeps consumers from depending on the editor’s internal schema.

A publicly readable immutable value can also be a good snapshot. Encapsulation limits accidental coupling; whether a user may restore a document is a separate authorization check.

08 / Take the idea with you

Say who remembers, who keeps, and who restores.

Try explaining the design without its name: “The editor captures enough content to return to it later. History retains a labeled handle. When the user selects it, the editor restores the content while keeping current runtime state outside that boundary.” Then name a future field that would make your restoration rule incomplete.

Connections to follow nextRelated lessons

Prototype creates another instance from existing state. This Memento example restores an earlier state into the same editor. Their copy mechanics can overlap while their identity and lifecycle promises differ.

Command represents an action. It can retain a memento captured before execution when restoring state is a suitable way to undo that action. Stack supplies one possible history ordering; the editor still owns what a checkpoint means.

Copying, identity & equality explains why an equal-looking value can still share mutable state. Memento makes that distinction part of a restoration contract.