@decaf-ts/core/lib/persistence/Dispatch.d.ts

Core persistence module for the decaf framework

import { OperationKeys, BulkCrudOperationKeys } from "@decaf-ts/db-decorators";
import { ModelConstructor } from "@decaf-ts/decorator-validation";
import { Observer } from "../interfaces";
import { Adapter } from "./Adapter";
import { AdapterDispatch, EventIds } from "./types";
import { LoggedClass } from "@decaf-ts/logging";
/**
 * @description Dispatches database operation events to observers
 * @summary The Dispatch class implements the Observable interface and is responsible for intercepting
 * database operations from an Adapter and notifying observers when changes occur. It uses proxies to
 * wrap the adapter's CRUD methods and automatically trigger observer updates after operations complete.
 * @template Y - The native database driver type
 * @param {void} - No constructor parameters
 * @class Dispatch
 * @example
 * ```typescript
 * // Creating and using a Dispatch instance
 * const dispatch = new Dispatch<PostgresDriver>();
 *
 * // Connect it to an adapter
 * const adapter = new PostgresAdapter(connection);
 * dispatch.observe(adapter);
 *
 * // Now any CRUD operations on the adapter will automatically
 * // trigger observer notifications
 * await adapter.create('users', 123, userModel);
 * // Observers will be notified about the creation
 *
 * // When done, you can disconnect
 * dispatch.unObserve(adapter);
 * ```
 */
export declare class Dispatch extends LoggedClass implements AdapterDispatch {
    /**
     * @description The adapter being observed
     * @summary Reference to the database adapter whose operations are being monitored
     */
    protected adapter?: Adapter<any, any, any, any, any>;
    /**
     * @description List of model constructors
     * @summary Array of model constructors that are registered with the adapter
     */
    protected models: ModelConstructor<any>[];
    /**
     * @description Creates a new Dispatch instance
     * @summary Initializes a new Dispatch instance without any adapter
     */
    constructor();
    /**
     * @description Initializes the dispatch by proxying adapter methods
     * @summary Sets up proxies on the adapter's CRUD methods to intercept operations and notify observers.
     * This method is called automatically when an adapter is observed.
     * @return {Promise<void>} A promise that resolves when initialization is complete
     * @mermaid
     * sequenceDiagram
     *   participant Dispatch
     *   participant Adapter
     *   participant Proxy
     *
     *   Dispatch->>Dispatch: initialize()
     *   Dispatch->>Dispatch: Check if adapter exists
     *   alt No adapter
     *     Dispatch-->>Dispatch: Throw InternalError
     *   end
     *
     *   loop For each CRUD method
     *     Dispatch->>Adapter: Check if method exists
     *     alt Method doesn't exist
     *       Dispatch-->>Dispatch: Throw InternalError
     *     end
     *
     *     Dispatch->>Adapter: Get property descriptor
     *     loop While descriptor not found
     *       Dispatch->>Adapter: Check prototype chain
     *     end
     *
     *     alt Descriptor not found or not writable
     *       Dispatch->>Dispatch: Log error and continue
     *     else Descriptor found and writable
     *       Dispatch->>Proxy: Create proxy for method
     *       Dispatch->>Adapter: Replace method with proxy
     *     end
     *   end
     */
    protected initialize(): Promise<void>;
    /**
     * @description Closes the dispatch
     * @summary Performs any necessary cleanup when the dispatch is no longer needed
     * @return {Promise<void>} A promise that resolves when closing is complete
     */
    close(): Promise<void>;
    /**
     * @description Starts observing an adapter
     * @summary Connects this dispatch to an adapter to monitor its operations
     * @param {Adapter<any, any, any, any>} observer - The adapter to observe
     * @return {void}
     */
    observe(observer: Adapter<any, any, any, any>): void;
    /**
     * @description Stops observing an adapter
     * @summary Disconnects this dispatch from an adapter
     * @param {Observer} observer - The adapter to stop observing
     * @return {void}
     */
    unObserve(observer: Observer): void;
    /**
     * @description Updates observers about a database event
     * @summary Notifies observers about a change in the database
     * @param {string} table - The name of the table where the change occurred
     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of operation that occurred
     * @param {EventIds} id - The identifier(s) of the affected record(s)
     * @return {Promise<void>} A promise that resolves when all observers have been notified
     */
    updateObservers(table: string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds): Promise<void>;
}