Oops.js: Advanced Undo/Redo Manager

Puter.com
·
Discord
·
Reddit
·
X (Twitter)

Oops.js

With Oops.js, you can implement undo/redo capabilities for your apps on par with industry-leading software like Figma, Photoshop, and Visual Studio Code. Whether you're building a simple text editor or a complex graphic design application, Oops.js offers the tools you need to create an intuitive yet powerful undo/redo functionality for your application.

Features

Oops.js provides a robust implementation of the command pattern, allowing you to easily add advanced undo and redo functionality to your projects with these powerful features:

- Command Pattern: Implements the command pattern for easy extensibility and operation encapsulation.
- Transaction Support: Allows grouping multiple commands into a single, atomic operation.
- Automatic Command Merging: Intelligently merges commands executed within a specified time window.
- Snapshot System: Creates and recovers from snapshots for enhanced error handling and state preservation.
- History Compression: Optimizes memory usage by compressing the command history when it exceeds a threshold.
- Event Notification System: Provides a robust event system for state change notifications.
- State Serialization: Enables serialization and deserialization of the entire undo/redo state for persistence.
- Configurable Parameters: Offers customizable stack size, snapshot interval, and compression threshold.
- Composite Commands: Supports complex operations through composite command structures.
- Error Recovery: Implements sophisticated error handling and recovery mechanisms.
- UI Integration: Easily integrates with UI components through canUndo and canRedo properties.
- Dual Execution Modes: Supports both object-based and string-based command execution for flexibility.

Installation

$3

To install Oops.js using npm, run the following command in your project directory:

``bash
npm install @heyputer/oops.js
`

Then, you can import it in your JavaScript file:

`js
import Oops from '@heyputer/oops.js';
`




$3

To use Oops.js directly in your HTML file via CDN, add the following script tag to your HTML:

`html

`

This will make the Oops class available globally in your JavaScript code.







$3

To build Oops.js from source, run the following commands:

`bash
git clone https://github.com/heyputer/oops.js.git
cd oops.js
npm install
npm run build
`





$3

`js
// Create an instance of Oops
const undoManager = new Oops();

// Define a simple command
class AddNumberCommand {
constructor(number) {
this.number = number;
this.previousTotal = 0;
}

execute() {
this.previousTotal = total;
total += this.number;
}

undo() {
total = this.previousTotal;
}
}

// Use the undo manager
let total = 0;

undoManager.execute(new AddNumberCommand(5));
console.log(total); // Output: 5

undoManager.execute(new AddNumberCommand(3));
console.log(total); // Output: 8

undoManager.undo();
console.log(total); // Output: 5

undoManager.redo();
console.log(total); // Output: 8
`




API Documentation

Oops Class

$3

`js
new Oops(options)
`

Creates a new instance of the Oops undo/redo manager.

- options (Object, optional):
- maxStackSize (Number): Maximum size of the undo/redo stacks. Default is Infinity.
- snapshotInterval (Number): Interval at which to create snapshots. Default is 10.
- compressThreshold (Number): Threshold for compressing history. Default is 100.
- mergeWindow (Number): Time window in milliseconds for merging commands. Default is 1000.




$3

##### execute(command, options)

Executes a command and optionally adds it to the undo stack.

- command (Command|string): The command to execute. Can be a Command object or a string identifier for a registered command.
- options (Object, optional):
- silent (boolean): If true, suppresses notification to listeners after execution. Default is false.
- undoable (boolean): If false, the command will not be added to the undo stack. Default is true.

Returns the result of the command execution, if any.

##### undo(steps)

Undoes a specified number of commands from the undo stack.

- steps (Number, optional): The number of commands to undo. Default is 1.

##### redo(steps)

Redoes a specified number of commands from the redo stack.

- steps (Number, optional): The number of commands to redo. Default is 1.

##### beginTransaction()

Begins a new transaction, allowing grouping of multiple commands.

##### commitTransaction()

Commits the current transaction, executing all commands in the transaction as a single unit.

##### abortTransaction()

Aborts the current transaction, undoing all commands in the transaction.

##### registerCommand(name, factory)

Registers a command factory with a given name.

- name (String): The name to associate with the command factory.
- factory (Function): A function that returns a new instance of the command.

##### addChangeListener(listener)

Adds a change listener to be notified of state changes.

- listener (Function): The listener function to be called on state changes.

##### removeChangeListener(listener)

Removes a previously added change listener.

- listener (Function): The listener function to be removed.

##### clear()

Clears all undo and redo history.

##### exportState()

Exports the current state of the undo/redo manager.
Returns an object representing the serialized state.

##### importState(state)

Imports a previously exported state into the undo/redo manager.

- state (Object): The state object to import.

##### serializeState()

Serializes the current state to a JSON string.
Returns a JSON string representing the current state.

##### deserializeState(jsonState)

Deserializes a JSON string and imports the state.

- jsonState (string): A JSON string representing a previously serialized state.




$3


##### canUndo
A boolean indicating whether there are any actions that can be undone.

##### canRedo
A boolean indicating whether there are any actions that can be redone.




CompositeCommand Class

The CompositeCommand class represents a command that consists of multiple sub-commands. It allows you to group several commands together and treat them as a single command.

$3

`js
new CompositeCommand(commands)
`

Creates a new instance of the CompositeCommand class.

- commands (Array): An array of Command objects to be executed as part of this composite command.




$3

##### execute()
Executes all the commands in the composite command in the order they were added.

##### undo()
Undoes all the commands in the composite command in reverse order.

##### serialize()

Serializes the CompositeCommand for storage or transmission.

Returns:

An object with the following structure:

- type (string): Always 'CompositeCommand'.
- data (Array): An array of serialized sub-commands.


##### static deserialize(data, deserializeCommand)
Static method to deserialize a CompositeCommand.

data (Array): An array of serialized sub-commands.
deserializeCommand (Function): A function to deserialize individual commands.

Returns:

A new CompositeCommand instance.

##### canMerge(other)
Checks if this CompositeCommand can be merged with another command.

other (Command): Another command to check for merge compatibility.

Returns:

false: CompositeCommands typically can't be merged.








LICENSE

Distributed under the MIT License. See LICENSE.txt` for more information.