@playcanvas/observer/types/history.d.ts

Generic implementation of the observer pattern

import { Events } from './events';
/**
 * Represents an action in the history.
 */
export type HistoryAction = {
    /**
     * The action name.
     */
    name: string;
    /**
     * The undo function.
     */
    undo: () => void;
    /**
     * The redo function.
     */
    redo: () => void;
    /**
     * Whether to combine with the previous action with the same name.
     * The effect of combining is merely changing the redo function to be the redo function of this action.
     * The original undo function is not modified.
     */
    combine: boolean;
};
/**
 * Manages history actions for undo/redo operations. This class keeps track of actions that can be
 * undone and redone, allowing for complex state management in applications such as editors, games,
 * or any interactive applications where state changes need to be reversible.
 *
 * @example
 * const history = new History();
 *
 * // Define an action
 * const action = {
 *   name: 'draw',
 *   undo: () => { console.log('Undo draw'); },
 *   redo: () => { console.log('Redo draw'); }
 * };
 *
 * // Add the action to history
 * history.add(action);
 *
 * // Perform undo
 * history.undo();
 *
 * // Perform redo
 * history.redo();
 */
declare class History extends Events {
    private _executing;
    private _actions;
    private _currentActionIndex;
    private _canUndo;
    private _canRedo;
    /**
     * Adds a new history action to the stack. If the action has a combine flag and matches the
     * current action's name, the redo function of the current action is updated. If actions have
     * been undone before adding this new action, it removes all actions that come after the
     * current action to maintain a consistent history.
     *
     * @param action - The action to add.
     * @returns Returns `true` if the action is successfully added, `false` otherwise.
     */
    add(action: HistoryAction): boolean;
    /**
     * Adds a new history action and immediately executes its redo function.
     *
     * @param action - The action.
     * @returns A promise that resolves once the redo function has been executed.
     */
    addAndExecute(action: HistoryAction): Promise<void>;
    /**
     * Undoes the last history action. This method retrieves the current action from the history
     * stack and executes the action's undo function.
     *
     * @returns A promise that resolves once the undo function has been executed.
     */
    undo(): Promise<void>;
    /**
     * Redoes the next history action. This retrieves the next action from the history stack and
     * executes the action's redo function.
     *
     * @returns A promise that resolves once the redo function has been executed.
     */
    redo(): Promise<void>;
    /**
     * Clears all history actions.
     */
    clear(): void;
    /**
     * The current history action.
     */
    get currentAction(): HistoryAction;
    /**
     * The last action committed to the history.
     */
    get lastAction(): HistoryAction;
    /**
     * Sets whether we can undo at this time.
     */
    set canUndo(value: boolean);
    /**
     * Gets whether we can undo at this time.
     */
    get canUndo(): boolean;
    /**
     * Sets whether we can redo at this time.
     */
    set canRedo(value: boolean);
    /**
     * Gets whether we can redo at this time.
     */
    get canRedo(): boolean;
    /**
     * Sets the number of async actions currently executing.
     */
    set executing(value: number);
    /**
     * Gets the number of async actions currently executing.
     */
    get executing(): number;
}
export { History };