Building Undo/Redo Stacks for JSON Editing

Implementing undo and redo functionality is a crucial feature for providing a good user experience in any editor, including those for JSON data. It allows users to revert mistakes and reapply changes, instilling confidence and improving workflow efficiency. This article explores how to build robust undo and redo stacks specifically tailored for JSON editing interfaces.

Why Undo/Redo is Essential

Imagine editing a complex JSON configuration file and accidentally deleting a critical section. Without undo, recovering from this error might mean manual retyping or losing work. Undo/redo capabilities provide a safety net, making the editor more forgiving and user-friendly. For JSON editors, which often involve intricate nested structures, this is particularly important.

Core Concepts: Stacks and State

The classic approach to implementing undo/redo relies on two stacks: an undo stack and a redo stack.

The core challenge is deciding what to store on these stacks: should you store the full state of the JSON document after each change, or just the operation that was performed (like adding a key, changing a value, etc.)?

Choosing What to Stack: State vs. Operations

// Conceptual Representation
undoStack = [ state_0, state_1, state_2, ... ]; // Full JSON states

// Conceptual Representation
undoStack = [ operation_0, operation_1, operation_2, ... ]; // Operations to undo
// operation_0 might be { type: 'add', path: '/a/b', value: 'oldValue' }

For JSON editing, a hybrid approach or using a library that handles JSON diffing/patching (like `json-patch` or `deep-diff`) can simplify the operations approach. Libraries often represent operations as a sequence of instructions (like JSON Patch) that can be applied forward (redo) and backward (undo).

Implementing the Stacks

State Management

You'll need a way to manage the current state of the JSON data and the two stacks. In React/Next.js, this could be done using `useState`, `useReducer`, or a state management library like Redux or Zustand. `useReducer` is often a good fit as actions naturally map to state transitions and can include the undo/redo logic.

Handling User Actions

Whenever a user makes a change to the JSON (e.g., edits a value, adds an item to an array, deletes a key):

1. Calculate the change (either the new full state or the operation/diff).
2. Push the 'undo' information (previous state or inverse operation) onto the undo stack.
3. Clear the redo stack. Once a new action is performed, the old 'future' path is lost.
4. Update the current JSON state.

Handling Undo

When the user triggers undo (e.g., clicks an undo button, presses Ctrl+Z):

1. Check if the undo stack is empty. If so, nothing to undo.
2. Pop the top item from the undo stack.
3. Push the 'redo' information (current state or the operation just undone) onto the redo stack.
4. Apply the popped 'undo' item: either revert to the previous state (full state approach) or apply the inverse operation (operations approach).
5. Update the current JSON state.

Handling Redo

When the user triggers redo (e.g., clicks a redo button, presses Ctrl+Y):

1. Check if the redo stack is empty. If so, nothing to redo.
2. Pop the top item from the redo stack.
3. Push the 'undo' information (current state or the operation just redone) onto the undo stack.
4. Apply the popped 'redo' item: either move forward to the next state (full state approach) or reapply the original operation (operations approach).
5. Update the current JSON state.

Example: Simplified State-Based Approach

Here's a conceptual simplified example using React's `useState` (though `useReducer` would be more idiomatic for complex logic). This uses the full-state approach for simplicity.

import React, { useState, useEffect } from 'react';

// Assume initialJson is your starting JSON object
const initialJson = { name: "Example", version: 1 };

function JsonEditorWithUndo() {
  // Current editable JSON state
  const [currentJson, setCurrentJson] = useState(initialJson);
  // Stack to store previous states for undo
  const [undoStack, setUndoStack] = useState([initialJson]);
  // Stack to store future states for redo
  const [redoStack, setRedoStack] = useState([]);
  // Keep track of the current position in the undo stack (optional, but simplifies)
  const [currentHistoryIndex, setCurrentHistoryIndex] = useState(0);

  // Function to call when the JSON changes
  const handleJsonChange = (newJson) => {
    // Only add to history if the new state is different
    if (JSON.stringify(newJson) !== JSON.stringify(currentJson)) {
      // Slice the undo stack to remove history after the current point
      const newUndoStack = undoStack.slice(0, currentHistoryIndex + 1);
      const nextIndex = newUndoStack.length;

      setUndoStack([...newUndoStack, newJson]);
      setCurrentHistoryIndex(nextIndex);
      setCurrentJson(newJson);
      setRedoStack([]); // Clear redo stack on new action
    } else {
       // If state is the same, just update current, don't add history
       setCurrentJson(newJson);
    }
  };

  // Function to perform undo
  const handleUndo = () => {
    if (currentHistoryIndex > 0) {
      const previousIndex = currentHistoryIndex - 1;
      const stateToUndo = undoStack[currentHistoryIndex]; // State before undo
      const previousState = undoStack[previousIndex];    // State to revert to

      // Push the state we are leaving onto the redo stack
      setRedoStack([stateToUndo, ...redoStack]);

      setCurrentJson(previousState);
      setCurrentHistoryIndex(previousIndex);
    }
  };

  // Function to perform redo
  const handleRedo = () => {
    if (redoStack.length > 0) {
      const nextState = redoStack[0]; // State to redo
      const newRedoStack = redoStack.slice(1);

      // Push the state we are leaving onto the undo stack
      setUndoStack([...undoStack.slice(0, currentHistoryIndex + 1), currentJson]);

      setCurrentJson(nextState);
      setRedoStack(newRedoStack);
      setCurrentHistoryIndex(currentHistoryIndex + 1); // Move index forward
    }
  };

  // Example usage:
  // Imagine an editor component calls handleJsonChange(updatedJson)
  // Buttons would call handleUndo() and handleRedo()

  return (
    <div>
      <button onClick={handleUndo} disabled={currentHistoryIndex === 0}>
        Undo
      </button>
      <button onClick={handleRedo} disabled={redoStack.length === 0}>
        Redo
      </button>
      <pre>{JSON.stringify(currentJson, null, 2)}</pre>
      {/* Your actual JSON editor component would go here,
          receiving currentJson and calling handleJsonChange */}
    </div>
  );
}

Considerations and Edge Cases

Conclusion

Building undo/redo functionality for a JSON editor involves managing the document's state history using stacks. The choice between storing full states or operations (diffs/patches) depends on the document size, memory constraints, and complexity tolerance. While storing full states is simpler to implement, the operations approach is generally more efficient for larger documents and offers more flexibility. By carefully designing your state management and action handling, you can provide users with a robust and reliable editing experience, complete with essential undo and redo capabilities.