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

Generic implementation of the observer pattern

import { Events } from './events';
import { ObserverHistory } from './observer-history';
/**
 * The ObserverSync class is used to construct an interface for synchronizing changes from Observer
 * to other services.
 */
export type ObserverSync = Events & {
    write: (...args: any[]) => void;
    enabled: boolean;
};
/**
 * The Observer class is used to observe and manage changes to an object. It allows for tracking
 * modifications to nested properties, emitting events on changes, and maintaining state
 * consistency. This is particularly useful in applications where state management and change
 * tracking are critical, such as in data-driven interfaces or collaborative applications.
 *
 * @example
 * const data = {
 *   name: 'John',
 *   age: 30,
 *   address: {
 *     city: 'New York',
 *     zip: '10001'
 *   }
 * };
 *
 * const observer = new Observer(data);
 *
 * observer.on('name:set', (newValue, oldValue) => {
 *   console.log(`Name changed from ${oldValue} to ${newValue}`);
 * });
 *
 * observer.set('name', 'Jane'); // Logs: Name changed from John to Jane
 */
declare class Observer extends Events {
    private _destroyed;
    private _path;
    private _keys;
    private _data;
    private _pathsWithDuplicates;
    private _parent;
    private _parentPath;
    private _parentField;
    private _parentKey;
    private _latestFn;
    private _silent;
    history: ObserverHistory;
    sync: ObserverSync;
    schema: any;
    /**
     * Creates a new Observer instance.
     *
     * @param data - The initial data to observe.
     * @param options - Additional options for the observer.
     */
    constructor(data?: object, options?: {
        parent?: Observer;
        parentPath?: string;
        parentField?: any;
        parentKey?: any;
        latestFn?: Function;
        pathsWithDuplicates?: string[];
    });
    private static _splitPathsCache;
    private static _splitPath;
    silence(): [boolean, boolean];
    silenceRestore(state: [boolean, boolean]): void;
    private _prepare;
    /**
     * @param path - Path to the property in the object.
     * @param value - Value to set.
     * @param silent - If true, the change will not be recorded in history.
     * @param remote - State value passed to the set event used to disable remote event emission.
     * @param force - If true, the value will be set even if it is the same as the current value.
     * @returns Returns true if the value was successfully set and false otherwise.
     */
    set(path: string, value: any, silent?: boolean, remote?: boolean, force?: boolean): boolean;
    /**
     * Query whether the object has the specified property.
     *
     * @param path - Path to the value.
     * @returns Returns true if the value is present and false otherwise.
     */
    has(path: string): boolean;
    /**
     * @param path - Path to the value.
     * @param raw - Retrieve the observer object without converting it to JSON.
     * @returns The value at the specified path.
     */
    get(path: string, raw?: boolean): any;
    getRaw(path: string): any;
    private _equals;
    /**
     * @param path - Path to the value.
     * @param silent - If true, the change will not be recorded in history.
     * @param remote - State value passed to the set event used to disable remote event emission.
     * @returns Returns true if the value was successfully unset and false otherwise.
     */
    unset(path: string, silent?: boolean, remote?: boolean): boolean;
    /**
     * @param path - Path to the value.
     * @param ind - Index of the value.
     * @param silent - If true, the remove event will not be emitted.
     * @param remote - State value passed to the set event used to disable remote event emission.
     * @returns Returns true if the value was successfully removed and false otherwise.
     */
    remove(path: string, ind: number, silent?: boolean, remote?: boolean): boolean;
    /**
     * @param path - Path to the value.
     * @param value - Value to remove.
     * @param silent - If true, the remove event will not be emitted.
     * @param remote - State value passed to the set event used to disable remote event emission.
     * @returns Returns true if the value was successfully removed and false otherwise.
     */
    removeValue(path: string, value: any, silent?: boolean, remote?: boolean): boolean;
    /**
     * @param path - Path to the value.
     * @param value - Value to insert.
     * @param ind - Index to insert the value at.
     * @param silent - If true, the insert event will not be emitted.
     * @param remote - State value passed to the set event used to disable remote event emission.
     * @returns Returns true if the value was successfully inserted and false otherwise.
     */
    insert(path: string, value: any, ind?: number, silent?: boolean, remote?: boolean): boolean;
    private _doInsert;
    /**
     * @param path - Path to the value.
     * @param indOld - Index of the value to move.
     * @param indNew - Index to move the value to.
     * @param silent - If true, the move event will not be emitted.
     * @param remote - State value passed to the set event used to disable remote event emission.
     * @returns Returns true if the value was successfully moved and false otherwise.
     */
    move(path: string, indOld: number, indNew: number, silent?: boolean, remote?: boolean): boolean;
    patch(data: Record<string, any>, removeMissingKeys?: boolean): void;
    /**
     * @param target - The object to JSONify.
     * @returns The current state of the object tracked by the observer.
     */
    json(target?: any): Record<string, any>;
    forEach(fn: Function, target?: any, path?: string): void;
    /**
     * Returns the latest observer instance. This is important when
     * dealing with undo / redo where the observer might have been deleted
     * and/or possibly re-created.
     *
     * @returns The latest instance of the observer.
     */
    latest(): Observer;
    /**
     * Destroys the observer instance.
     */
    destroy(): void;
    set latestFn(value: Function);
    get latestFn(): Function;
}
export { Observer };