@decaf-ts/for-nano/lib/types/NanoDispatch.d.cts

decaf-ts persistence adapter for CouchDB via nano

import { Adapter, Context, ContextualArgs, Dispatch } from "@decaf-ts/core";
import { DatabaseChangesResponse, DatabaseChangesResultItem, DocumentScope, RequestError } from "nano";
import { MangoQuery } from "@decaf-ts/for-couchdb";
import { NanoConfig, NanoFlags } from "./types.d.cts";
/**
 * @description Dispatcher for Nano database change events
 * @summary Handles the subscription to and processing of database change events from a Nano database,
 * notifying observers when documents are created, updated, or deleted
 * @template DocumentScope - The Nano document scope type
 * @param {number} [timeout=5000] - Timeout in milliseconds for change feed requests
 * @class NanoDispatch
 * @example
 * ```typescript
 * // Create a dispatcher for a Nano database
 * const db = server.db.use('my_database');
 * const adapter = new NanoAdapter(db);
 * const dispatch = new NanoDispatch();
 *
 * // The dispatcher will automatically subscribe to changes
 * // and notify observers when documents change
 * ```
 * @mermaid
 * classDiagram
 *   class Dispatch {
 *     +initialize()
 *     +updateObservers()
 *   }
 *   class NanoDispatch {
 *     -observerLastUpdate?: string
 *     -attemptCounter: number
 *     -timeout: number
 *     +constructor(timeout)
 *     #changeHandler()
 *     #initialize()
 *   }
 *   Dispatch <|-- NanoDispatch
 */
export declare class NanoDispatch extends Dispatch<Adapter<NanoConfig, DocumentScope<any>, MangoQuery, Context<NanoFlags>>> {
    private timeout;
    private observerLastUpdate?;
    private attemptCounter;
    private active;
    private changeFeed?;
    constructor(timeout?: number);
    /**
     * @description Closes the dispatcher
     * @summary Stops the dispatcher and cleans up any active subscriptions or resources
     * @return {Promise<void>} A promise that resolves when the dispatcher has been closed
     */
    close(...args: ContextualArgs<Context<NanoFlags>>): Promise<void>;
    /**
     * @description Processes database change events
     * @summary Handles the response from the Nano changes feed, processes the changes,
     * and notifies observers about document changes
     * @param {RequestError | null} error - Error object if the request failed
     * @param response - The changes response from Nano
     * @param {any} [headers] - Response headers (unused)
     * @return {Promise<void>} A promise that resolves when all changes have been processed
     * @mermaid
     * sequenceDiagram
     *   participant D as NanoDispatch
     *   participant L as Logger
     *   participant O as Observers
     *   Note over D: Receive changes from Nano
     *   alt Error in response
     *     D->>L: Log error
     *     D-->>D: Return early
     *   end
     *   alt Response is string
     *     D->>D: Parse JSON from string
     *   end
     *   D->>D: Process changes
     *   D->>D: Group changes by table and operation
     *   loop For each table
     *     loop For each operation
     *       D->>O: updateObservers(table, operation, ids)
     *       D->>D: Update observerLastUpdate
     *       D->>L: Log successful dispatch
     *     end
     *   end
     */
    protected changeHandler(error: RequestError | null, response: (DatabaseChangesResponse | DatabaseChangesResultItem)[] | string, headers?: any, ctxArg?: Context<NanoFlags>): Promise<void>;
    /**
     * @description Initializes the dispatcher and subscribes to database changes
     * @summary Sets up the continuous changes feed subscription to the Nano database
     * and handles reconnection attempts if the connection fails
     * @return {Promise<void>} A promise that resolves when the subscription is established
     * @mermaid
     * sequenceDiagram
     *   participant D as NanoDispatch
     *   participant S as subscribeToCouch
     *   participant DB as Nano Database
     *   participant L as Logger
     *   D->>S: Call subscribeToCouch
     *   S->>S: Check adapter and native
     *   alt No adapter or native
     *     S-->>S: throw InternalError
     *   end
     *   S->>DB: changes(options, changeHandler)
     *   alt Success
     *     DB-->>S: Subscription established
     *     S-->>D: Promise resolves
     *     D->>L: Log successful subscription
     *   else Error
     *     DB-->>S: Error
     *     S->>S: Increment attemptCounter
     *     alt attemptCounter > 3
     *       S->>L: Log error
     *       S-->>D: Promise rejects
     *     else attemptCounter <= 3
     *       S->>L: Log retry
     *       S->>S: Wait timeout
     *       S->>S: Recursive call to subscribeToCouch
     *     end
     *   end
     */
    protected initialize(): Promise<void>;
    private disposeChangeFeed;
}