Repository files navigation

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

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.

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 throughcanUndo andcanRedo properties.
• Dual Execution Modes: Supports both object-based and string-based command execution for flexibility.

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

npm install @heyputer/oops.js

Then, you can import it in your JavaScript file:

importOopsfrom'@heyputer/oops.js';

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

<scriptsrc="https://cdn.jsdelivr.net/npm/@heyputer/oops.js@latest/dist/oops.min.js"></script>

This will make theOops class available globally in your JavaScript code.

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

git clone https://github.com/heyputer/oops.js.gitcd oops.jsnpm installnpm run build

// Create an instance of OopsconstundoManager=newOops();// Define a simple commandclassAddNumberCommand{constructor(number){this.number=number;this.previousTotal=0;}execute(){this.previousTotal=total;total+=this.number;}undo(){total=this.previousTotal;}}// Use the undo managerlettotal=0;undoManager.execute(newAddNumberCommand(5));console.log(total);// Output: 5undoManager.execute(newAddNumberCommand(3));console.log(total);// Output: 8undoManager.undo();console.log(total);// Output: 5undoManager.redo();console.log(total);// Output: 8

newOops(options)

Creates a new instance of theOops 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.

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 isfalse.
  • undoable (boolean): If false, the command will not be added to the undo stack. Default istrue.

Returns the result of the command execution, if any.

Undoes a specified number of commands from the undo stack.

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

Redoes a specified number of commands from the redo stack.

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

Begins a new transaction, allowing grouping of multiple commands.

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

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

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.

Adds a change listener to be notified of state changes.

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

Removes a previously added change listener.

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

Clears all undo and redo history.

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

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

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

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

Deserializes a JSON string and imports the state.

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

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

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

TheCompositeCommand 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.

newCompositeCommand(commands)

Creates a new instance of theCompositeCommand class.

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

Executes all the commands in the composite command in the order they were added.

Undoes all the commands in the composite command in reverse order.

Serializes theCompositeCommand for storage or transmission.

Returns:

An object with the following structure:

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

Static method to deserialize aCompositeCommand.

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

Returns:

A newCompositeCommand instance.

Checks if thisCompositeCommand can be merged with another command.

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

Returns:

false: CompositeCommands typically can't be merged.

Distributed under the MIT License. SeeLICENSE.txt for more information.