chrono-forge/dist/store/EntityProxyManager.d.ts

A comprehensive framework for building resilient Temporal workflows, advanced state management, and real-time streaming activities in TypeScript. Designed for a seamless developer experience with powerful abstractions, dynamic orchestration, and full cont

import { StateManager } from './StateManager';
/**
 * EntityProxyManager provides a reactive interface to entity data with automatic state updates
 * and relationship handling, using proxy-state-tree for the proxy implementation.
 *
 * This class manages the creation and caching of entity proxies, handles mutations to those
 * proxies, and ensures that changes are properly propagated to the state management system.
 * It also handles complex relationship updates between entities.
 */
export declare class EntityProxyManager {
    /**
     * The main proxy-state-tree instance that manages all entity proxies
     * and tracks mutations to those proxies.
     */
    private static proxyStateTree;
    /**
     * Cache of entity proxies to avoid recreating proxies for the same entity.
     * Keys are in the format `${entityName}::${entityId}`.
     */
    private static readonly entityCache;
    /**
     * Map of entity cache keys to their StateManager instances.
     * Used to dispatch state updates when entities are modified.
     * Keys are in the format `${entityName}::${entityId}`.
     */
    private static readonly entityStateManagers;
    /**
     * Initializes the proxy-state-tree instance.
     * This should be called once at application startup before any entity proxies are created.
     * If the proxy-state-tree instance already exists, this method does nothing.
     */
    static initialize(): void;
    /**
     * Creates a proxy for an entity or returns a cached instance if one already exists.
     * The proxy allows tracking mutations to the entity and automatically updating the state.
     *
     * @param entityName - The type name of the entity (e.g., 'user', 'task')
     * @param entityId - The unique identifier of the entity
     * @param data - The entity data to be proxied
     * @param stateManager - The StateManager instance responsible for this entity
     * @returns A proxy object that wraps the entity data and tracks mutations
     */
    static createEntityProxy(entityName: string, entityId: string, data: any, stateManager: StateManager): any;
    /**
     * Handles mutations to an entity by determining the type of mutation and dispatching
     * the appropriate state updates. This method is called automatically when a property
     * of an entity proxy is modified.
     *
     * @param entityName - The type name of the entity being mutated
     * @param entityId - The unique identifier of the entity being mutated
     * @param mutation - The mutation object from proxy-state-tree containing details about the change
     */
    private static handleEntityMutation;
    /**
     * Processes a mutation that affects nested entities within a relationship field.
     * This method determines which related entity was modified and updates it appropriately.
     *
     * @param entityName - The parent entity type name
     * @param entityId - The parent entity ID
     * @param fieldName - The relationship field name that contains the nested entity
     * @param nestedPath - The path parts after the relationship field, identifying the nested property
     * @param currentValue - The current value of the relationship field
     * @param stateManager - The StateManager instance for the parent entity
     * @param relation - The relationship metadata describing the connection between entities
     * @param mutation - The original mutation object containing details about the change
     */
    private static processNestedMutation;
    /**
     * Updates a nested entity based on a mutation. This method is called when a property
     * within a related entity is modified through a relationship.
     *
     * This method handles various types of nested updates, including:
     * - Direct field updates within the nested entity
     * - Array operations (push, pop, etc.) on array fields
     * - Updates to deeply nested properties within objects
     * - Updates to nested relationships
     *
     * It creates appropriate partial update actions based on the type of mutation
     * and dispatches them to the state manager.
     *
     * @param entityName - The entity type name of the nested entity
     * @param entityId - The entity ID of the nested entity
     * @param nestedPath - The remaining path within the nested entity to the modified property
     * @param stateManager - The StateManager instance
     * @param mutation - The original mutation object containing details about the change
     */
    private static updateNestedEntity;
    /**
     * Handles mutations to relationship fields by updating both the parent entity
     * and any related entities as needed. This method processes different relationship types
     * (one-to-one, one-to-many) and handles adding, removing, and updating related entities.
     *
     * It tracks which entities were added or removed from the relationship and dispatches
     * the appropriate actions to update the state, including potentially deleting entities
     * that are no longer referenced.
     *
     * @param entityName - The entity type name of the parent entity
     * @param entityId - The entity ID of the parent entity
     * @param fieldName - The name of the relationship field that was modified
     * @param newValue - The new value of the relationship field
     * @param stateManager - The StateManager instance
     */
    private static handleRelationshipMutation;
    /**
     * Updates an entity field in the state by dispatching the appropriate action.
     * This method handles different update strategies based on the type of value.
     *
     * @param entityName - The entity type name
     * @param entityId - The entity ID
     * @param fieldName - The name of the field to update
     * @param newValue - The new value for the field
     * @param stateManager - The StateManager instance
     */
    private static updateEntityField;
    /**
     * Determines if a mutation represents an array method operation like push, pop, etc.
     *
     * Array method mutations require special handling because they modify an existing array
     * rather than replacing it entirely. This method helps identify when such special
     * handling is needed throughout the proxy manager.
     *
     * The supported array methods are: push, pop, shift, unshift, splice, sort, and reverse.
     *
     * @param mutation - The mutation object to check
     * @returns True if the mutation is an array method operation, false otherwise
     */
    private static isArrayMethodMutation;
    /**
     * Clears the entire entity cache and state manager mappings.
     * This should be called when the application state is reset or when
     * all entities need to be recreated.
     *
     * Clearing the cache forces new proxies to be created the next time entities
     * are accessed, which ensures that the proxies reflect the current state.
     * This is particularly important after major state changes like loading
     * a new dataset or resetting the application.
     */
    static clearCache(): void;
    /**
     * Removes a specific entity from the cache.
     * This should be called when an entity is deleted or when its proxy
     * needs to be recreated from scratch.
     *
     * Removing an entity from the cache ensures that the next time it's accessed,
     * a new proxy will be created with the current state. This is important after
     * operations that significantly change an entity's structure or relationships.
     *
     * @param entityName - The entity type name
     * @param entityId - The entity ID
     */
    static removeFromCache(entityName: string, entityId: string): void;
}