fluidstate/extras/reactive-plugin.d.ts

Library for fine-grained reactivity state management

/**
 * Defines the structure for a reactive plugin, which can hook into the lifecycle
 * of changes within reactive objects.
 * Plugins can execute custom logic before and/or after changes are applied.
 */
export type ReactivePlugin = {
    /**
     * A function that is called before changes are applied to a reactive object.
     * @param changes An array of changes that are about to be applied.
     */
    beforeChange?: (changes: ReactiveChange[]) => void;
    /**
     * A function that is called after changes have been applied to a reactive object.
     * @param changes An array of changes that were just applied.
     */
    afterChange?: (changes: ReactiveChange[]) => void;
};
export declare const beforeChange: (changes: ReactiveChange[], plugins?: ReactivePlugin[]) => void;
export declare const afterChange: (changes: ReactiveChange[], plugins?: ReactivePlugin[]) => void;
/**
 * Enumerates the types of reactive data structures that can undergo changes
 * tracked by reactive plugins.
 */
export declare enum ReactiveChangeType {
    /** Indicates a change occurred within a reactive array. */
    Array = 0,
    /** Indicates a change occurred within a reactive set. */
    Set = 1,
    /** Indicates a change occurred within a reactive map. */
    Map = 2,
    /** Indicates a change occurred within a reactive object. */
    Object = 3
}
/**
 * Represents a discriminated union of all possible change types that can occur
 * in different reactive data structures (Array, Map, Set, Object).
 * Each change object includes the type of the reactive structure, a reference to it,
 * and the specific change details.
 */
export type ReactiveChange = {
    type: ReactiveChangeType.Array;
    array: unknown[];
    arrayChange: ArrayChange;
} | {
    type: ReactiveChangeType.Map;
    map: Map<unknown, unknown>;
    mapChange: MapChange;
} | {
    type: ReactiveChangeType.Set;
    set: Set<unknown>;
    setChange: SetChange;
} | {
    type: ReactiveChangeType.Object;
    object: object;
    objectChange: ObjectChange;
};
/**
 * Enumerates the types of modifications that can occur within a reactive array.
 */
export declare enum ArrayChangeType {
    /** Indicates a new value was added to the end of the array (e.g., via `push`). */
    PushValue = 0,
    /** Indicates a value at a specific index in the array was modified. */
    SetValue = 1,
    /** Indicates a value was removed from the end of the array (e.g., via `pop`). */
    PopValue = 2
}
/**
 * Represents a discriminated union of specific changes that can happen to a reactive array.
 */
export type ArrayChange = {
    type: ArrayChangeType.PushValue;
    /** The index at which the new value was added. */
    index: number;
    /** The value that was added to the array. */
    nextValue: unknown;
} | {
    type: ArrayChangeType.PopValue;
    /** The index from which the value was removed (typically the last element). */
    index: number;
    /** The value that was removed from the array. */
    previousValue: unknown;
} | {
    type: ArrayChangeType.SetValue;
    /** The index of the array element that was changed. */
    index: number;
    /** The value of the element before the change. */
    previousValue: unknown;
    /** The new value of the element after the change. */
    nextValue: unknown;
};
/**
 * Enumerates the types of modifications that can occur within a reactive map.
 */
export declare enum MapChangeType {
    /** Indicates a key-value pair was added or an existing key's value was updated. */
    SetValue = 0,
    /** Indicates a key-value pair was removed from the map. */
    DeleteValue = 1
}
/**
 * Represents a discriminated union of specific changes that can happen to a reactive map.
 */
export type MapChange = {
    type: MapChangeType.SetValue;
    /** The key whose value was set or updated. */
    key: unknown;
    /** The previous value associated with the key, if any. `undefined` if the key was new. */
    previousValue: unknown;
    /** The new value associated with the key. */
    nextValue: unknown;
} | {
    type: MapChangeType.DeleteValue;
    /** The key that was removed from the map. */
    key: unknown;
    /** The value associated with the key before it was removed. */
    previousValue: unknown;
};
/**
 * Enumerates the types of modifications that can occur within a reactive set.
 */
export declare enum SetChangeType {
    /** Indicates a new value was added to the set. */
    AddValue = 0,
    /** Indicates a value was removed from the set. */
    DeleteValue = 1
}
/**
 * Represents a discriminated union of specific changes that can happen to a reactive set.
 */
export type SetChange = {
    type: SetChangeType.AddValue;
    /** The value that was added to the set. */
    nextValue: unknown;
} | {
    type: SetChangeType.DeleteValue;
    /** The value that was removed from the set. */
    previousValue: unknown;
};
/**
 * Enumerates the types of modifications that can occur on the properties of a reactive object.
 */
export declare enum ObjectChangeType {
    /** Indicates a property's value was set or a new property was added. */
    SetProperty = 0,
    /** Indicates a property was deleted from the object. */
    DeleteProperty = 1
}
/**
 * Represents a discriminated union of specific changes that can happen to the properties of a reactive object.
 */
export type ObjectChange = {
    type: ObjectChangeType.SetProperty;
    /** The name of the property that was changed or added. */
    property: string | symbol;
    /** The value of the property before the change. `undefined` if the property was new. */
    previousValue: unknown;
    /** The new value of the property. */
    nextValue: unknown;
} | {
    type: ObjectChangeType.DeleteProperty;
    /** The name of the property that was deleted. */
    property: string | symbol;
    /** The value of the property before it was deleted. */
    previousValue: unknown;
};