@decaf-ts/for-fabric 0.9.0 → 0.11.0

package/lib/types/client/FabricClientAdapter.d.mts

@@ -0,0 +1,404 @@
+import "../shared/overrides";
+import { type MangoQuery, type ViewResponse } from "@decaf-ts/for-couchdb";
+import { Client } from "@grpc/grpc-js";
+import { Model, type ModelConstructor, type Serializer } from "@decaf-ts/decorator-validation";
+import { type PeerConfig, type SegregatedModel } from "../shared/types.js";
+import { Gateway, Network, Contract as Contrakt, GatewayError } from "@hyperledger/fabric-gateway";
+import { BaseError, OperationKeys, type PrimaryKeyType } from "@decaf-ts/db-decorators";
+import { Context, Adapter, type AdapterFlags, Repository, Statement, type PreparedStatement, Paginator, MaybeContextualArg, ContextualArgs, type PreparedModel, AllOperationKeys } from "@decaf-ts/core";
+import { FabricClientDispatch } from "./FabricClientDispatch.js";
+import { type Constructor } from "@decaf-ts/decoration";
+import { FabricClientFlags } from "./types.js";
+/**
+ * @description Adapter for interacting with Hyperledger Fabric networks
+ * @summary The FabricAdapter extends CouchDBAdapter to provide a seamless interface for interacting with Hyperledger Fabric networks.
+ * It handles connection management, transaction submission, and CRUD operations against Fabric chaincode.
+ * @template PeerConfig - Configuration type for connecting to a Fabric peer
+ * @template FabricFlags - Flags specific to Fabric operations
+ * @template Context<FabricFlags> - Context type containing Fabric-specific flags
+ * @param config - Configuration for connecting to a Fabric peer
+ * @param alias - Optional alias for the adapter instance
+ * @class FabricClientAdapter
+ * @example
+ * ```typescript
+ * // Create a new FabricAdapter instance
+ * const config: PeerConfig = {
+ *   mspId: 'Org1MSP',
+ *   peerEndpoint: 'localhost:7051',
+ *   channelName: 'mychannel',
+ *   chaincodeName: 'mycc',
+ *   contractName: 'mycontract',
+ *   tlsCertPath: '/path/to/tls/cert',
+ *   certDirectoryPath: '/path/to/cert/dir',
+ *   keyDirectoryPath: '/path/to/key/dir'
+ * };
+ *
+ * const adapter = new FabricAdapter(config, 'org1-adapter');
+ *
+ * // Use the adapter to interact with the Fabric network
+ * const result = await adapter.read('users', 'user1', mySerializer);
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant FabricAdapter
+ *   participant Gateway
+ *   participant Network
+ *   participant Contract
+ *   participant Chaincode
+ *
+ *   Client->>FabricAdapter: create(tableName, id, model, transient, serializer)
+ *   FabricAdapter->>FabricAdapter: submitTransaction(OperationKeys.CREATE, [serializedModel], transient)
+ *   FabricAdapter->>Gateway: connect()
+ *   Gateway->>Network: getNetwork(channelName)
+ *   Network->>Contract: getContract(chaincodeName, contractName)
+ *   FabricAdapter->>Contract: submit(api, proposalOptions)
+ *   Contract->>Chaincode: invoke
+ *   Chaincode-->>Contract: response
+ *   Contract-->>FabricAdapter: result
+ *   FabricAdapter->>FabricAdapter: decode(result)
+ *   FabricAdapter->>FabricAdapter: serializer.deserialize(decodedResult)
+ *   FabricAdapter-->>Client: deserializedResult
+ */
+export declare class FabricClientAdapter extends Adapter<PeerConfig, Client, MangoQuery, Context<FabricClientFlags>> {
+    /**
+     * @description Static text decoder for converting Uint8Array to string
+     */
+    private static decoder;
+    private static serializer;
+    protected static log: import("@decaf-ts/logging").Logger;
+    protected readonly serializer: Serializer<any>;
+    /**
+     * @description Creates a new FabricAdapter instance
+     * @summary Initializes a new adapter for interacting with a Hyperledger Fabric network
+     * @param {PeerConfig} config - Configuration for connecting to a Fabric peer
+     * @param {string} [alias] - Optional alias for the adapter instance
+     */
+    constructor(config: PeerConfig, alias?: string);
+    Statement<M extends Model>(overrides?: Partial<AdapterFlags>): Statement<M, FabricClientAdapter, any, MangoQuery>;
+    Paginator<M extends Model>(query: PreparedStatement<any> | MangoQuery, size: number, clazz: Constructor<M>): Paginator<M, any, MangoQuery>;
+    protected flags<M extends Model>(operation: OperationKeys | string, model: Constructor<M> | Constructor<M>[] | undefined, flags: Partial<FabricClientFlags>, ...args: any[]): Promise<FabricClientFlags>;
+    context<M extends Model>(operation: ((...args: any[]) => any) | AllOperationKeys, overrides: Partial<FabricClientFlags>, model: Constructor<M> | Constructor<M>[], ...args: MaybeContextualArg<Context<any>>): Promise<Context<FabricClientFlags>>;
+    /**
+     * @description Decodes a Uint8Array to a string
+     * @summary Converts binary data received from Fabric to a string using UTF-8 encoding
+     * @param {Uint8Array} data - The binary data to decode
+     * @return {string} The decoded string
+     */
+    decode(data: Uint8Array): string;
+    repository<R extends Repository<any, Adapter<PeerConfig, Client, MangoQuery, Context<FabricClientFlags>>>>(): Constructor<R>;
+    protected createPrefix<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: MaybeContextualArg<Context<FabricClientFlags>>): [Constructor<M>, PrimaryKeyType, Record<string, any>, ...any[], Context];
+    /**
+     * @description Prepares multiple records for creation
+     * @summary Adds necessary CouchDB fields to multiple records before creation
+     * @param {string} tableName - The name of the table
+     * @param {string[]|number[]} ids - The IDs of the records
+     * @param models - The models to prepare
+     * @return A tuple containing the tableName, ids, and prepared records
+     * @throws {InternalError} If ids and models arrays have different lengths
+     */
+    protected createAllPrefix<M extends Model>(clazz: Constructor<M>, ids: string[] | number[], models: Record<string, any>[], ...args: MaybeContextualArg<Context<FabricClientFlags>>): any[];
+    protected updateAllPrefix<M extends Model>(clazz: Constructor<M>, ids: PrimaryKeyType[], models: Record<string, any>[], ...args: MaybeContextualArg<Context<FabricClientFlags>>): any[];
+    /**
+     * @description Creates multiple records in a single transaction
+     * @summary Submits a transaction to create multiple records in the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {string[] | number[]} ids - Array of record identifiers
+     * @param {Array<Record<string, any>>} models - Array of record data
+     * @param {Record<string, any>} transient - Transient data for the transaction
+     * @return {Promise<Array<Record<string, any>>>} Promise resolving to the created records
+     */
+    createAll<M extends Model>(clazz: Constructor<M>, ids: PrimaryKeyType[], models: Record<string, any>[], ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Reads multiple records in a single transaction
+     * @summary Submits a transaction to read multiple records from the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {string[] | number[]} ids - Array of record identifiers to read
+     * @return {Promise<Array<Record<string, any>>>} Promise resolving to the retrieved records
+     */
+    readAll<M extends Model>(clazz: Constructor<M>, ids: PrimaryKeyType[], ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Updates multiple records in a single transaction
+     * @summary Submits a transaction to update multiple records in the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {string[] | number[]} ids - Array of record identifiers
+     * @param {Array<Record<string, any>>} models - Array of updated record data
+     * @param {Record<string, any>} transient - Transient data for the transaction
+     * @return {Promise<Array<Record<string, any>>>} Promise resolving to the updated records
+     */
+    updateAll<M extends Model>(clazz: Constructor<M>, ids: PrimaryKeyType[], models: Record<string, any>[], ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Deletes multiple records in a single transaction
+     * @summary Submits a transaction to delete multiple records from the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {Array<string | number | bigint>} ids - Array of record identifiers to delete
+     * @param {Serializer<any>} serializer - Serializer for the model data
+     * @return {Promise<Array<Record<string, any>>>} Promise resolving to the deleted records
+     */
+    deleteAll<M extends Model>(clazz: Constructor<M>, ids: PrimaryKeyType[], ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Prepares a model for persistence
+     * @summary Converts a model instance into a format suitable for database storage,
+     * handling column mapping and separating transient properties
+     * @template M - The model type
+     * @param {M} model - The model instance to prepare
+     * @param pk - The primary key property name
+     * @return The prepared data
+     */
+    prepare<M extends Model>(model: M, ...args: ContextualArgs<Context<FabricClientFlags>>): SegregatedModel<M> & PreparedModel;
+    revert<M extends Model>(obj: Record<string, any>, clazz: Constructor<M>, id: PrimaryKeyType, transient?: Record<string, any>, ...args: ContextualArgs<Context<FabricClientFlags>>): M;
+    private shouldRebuildWithTransient;
+    private resolveOperation;
+    private shouldRefreshAfterWrite;
+    private getEndorsingOrganizations;
+    private shouldForceGatewayHydration;
+    /**
+     * @description Creates a single record
+     * @summary Submits a transaction to create a record in the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The record identifier
+     * @param {Record<string, any>} model - The record data
+     * @param {Record<string, any>} transient - Transient data for the transaction
+     * @return {Promise<Record<string, any>>} Promise resolving to the created record
+     */
+    create<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, transient?: Record<string, any>, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>>;
+    healthcheck<M extends Model>(clazz: Constructor<M>, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>>;
+    /**
+     * @description Reads a single record
+     * @summary Evaluates a transaction to read a record from the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The record identifier
+     * @return {Promise<Record<string, any>>} Promise resolving to the retrieved record
+     */
+    read<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>>;
+    updatePrefix<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: MaybeContextualArg<Context<FabricClientFlags>>): any[];
+    /**
+     * @description Updates a single record
+     * @summary Submits a transaction to update a record in the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The record identifier
+     * @param {Record<string, any>} model - The updated record data
+     * @param {Record<string, any>} transient - Transient data for the transaction
+     * @return {Promise<Record<string, any>>} Promise resolving to the updated record
+     */
+    update<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, transient?: Record<string, any>, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>>;
+    /**
+     * @description Deletes a single record
+     * @summary Submits a transaction to delete a record from the Fabric ledger
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The record identifier to delete
+     * @return {Promise<Record<string, any>>} Promise resolving to the deleted record
+     */
+    delete<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<Record<string, any>>;
+    /**
+     * @description Executes a raw query against the Fabric ledger
+     * @summary Evaluates a transaction to perform a query using Mango Query syntax
+     * @template V - The return type
+     * @param {MangoQuery} rawInput - The Mango Query to execute
+     * @param {boolean} process - Whether to process the result
+     * @return {Promise<V>} Promise resolving to the query result
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client
+     *   participant FabricAdapter
+     *   participant Contract
+     *   participant Chaincode
+     *
+     *   Client->>FabricAdapter: raw(rawInput, process)
+     *   FabricAdapter->>FabricAdapter: JSON.stringify(rawInput)
+     *   FabricAdapter->>FabricAdapter: evaluateTransaction("query", [input])
+     *   FabricAdapter->>Contract: evaluate("query", proposalOptions)
+     *   Contract->>Chaincode: invoke
+     *   Chaincode-->>Contract: response
+     *   Contract-->>FabricAdapter: result
+     *   FabricAdapter->>FabricAdapter: JSON.parse(decode(result))
+     *   FabricAdapter->>FabricAdapter: Process result based on type
+     *   FabricAdapter-->>Client: processed result
+     */
+    raw<V, D extends boolean>(rawInput: MangoQuery, docsOnly: D | undefined, clazz: ModelConstructor<any>, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<V>;
+    /**
+     * @description Executes a CouchDB view query against the Fabric chaincode
+     * @summary Evaluates a transaction to query a design document view
+     * @template R - The view response type
+     * @param {string} ddoc - Design document name
+     * @param {string} viewName - View name
+     * @param {Record<string, any>} options - View query options
+     * @param {...ContextualArgs<Context<FabricClientFlags>>} args - Optional contextual arguments
+     * @return {Promise<ViewResponse<R>>} The view response
+     */
+    view<R>(ddoc: string, viewName: string, options: Record<string, any>, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<ViewResponse<R>>;
+    /**
+     * @description Gets or creates a gRPC client for the Fabric peer
+     * @summary Returns a cached client or creates a new one if none exists
+     * @return {Promise<Client>} Promise resolving to the gRPC client
+     */
+    getClient(): Client;
+    /**
+     * @description Gets a Gateway instance for the Fabric network
+     * @summary Creates a new Gateway instance using the current client
+     * @return {Promise<Gateway>} Promise resolving to the Gateway instance
+     */
+    protected Gateway(ctx: Context<FabricClientFlags>): Promise<Gateway>;
+    private getContractName;
+    /**
+     * @description Gets a Contract instance for the Fabric chaincode
+     * @summary Creates a new Contract instance using the current Gateway
+     * @return {Promise<Contrakt>} Promise resolving to the Contract instance
+     */
+    protected Contract(ctx: Context<FabricClientFlags>, contractName?: string): Promise<Contrakt>;
+    /**
+     * @description Executes a transaction on the Fabric network
+     * @summary Submits or evaluates a transaction on the Fabric chaincode
+     * @param {string} api - The chaincode function to call
+     * @param {boolean} submit - Whether to submit (true) or evaluate (false) the transaction
+     * @param {any[]} [args] - Arguments to pass to the chaincode function
+     * @param {Record<string, string>} [transientData] - Transient data for the transaction
+     * @param {Array<string>} [endorsingOrganizations] - Organizations that must endorse the transaction
+     * @return {Promise<Uint8Array>} Promise resolving to the transaction result
+     * @mermaid
+     * sequenceDiagram
+     *   participant FabricAdapter
+     *   participant Gateway
+     *   participant Contract
+     *   participant Chaincode
+     *
+     *   FabricAdapter->>Gateway: connect()
+     *   FabricAdapter->>Contract: getContract()
+     *   alt submit transaction
+     *     FabricAdapter->>Contract: submit(api, proposalOptions)
+     *   else evaluate transaction
+     *     FabricAdapter->>Contract: evaluate(api, proposalOptions)
+     *   end
+     *   Contract->>Chaincode: invoke
+     *   Chaincode-->>Contract: response
+     *   Contract-->>FabricAdapter: result
+     *   FabricAdapter->>Gateway: close()
+     */
+    protected transaction(ctx: Context<FabricClientFlags>, api: string, submit?: boolean, args?: any[], transientData?: Record<string, string>, endorsingOrganizations?: string[], className?: string): Promise<Uint8Array>;
+    private shouldUseLegacyGateway;
+    private prepareLegacyArgs;
+    private buildLegacyTransient;
+    private resolveLegacyMspCount;
+    private pickLegacyCandidates;
+    private buildLegacyPeerConfigs;
+    private submitLegacyWithExplicitEndorsers;
+    private normalizeLegacyPeers;
+    private resolveLegacyIdentityMaterial;
+    private buildLegacyConnectionProfile;
+    private shouldTreatPeersAsLocalhost;
+    private isLocalEndpoint;
+    private extractHost;
+    private ensureGrpcUrl;
+    private readPemInput;
+    /**
+     * @description Parses an error into a BaseError
+     * @summary Converts any error into a standardized BaseError
+     * @param {Error | string} err - The error to parse
+     * @param {string} [reason] - Optional reason for the error
+     * @return {BaseError} The parsed error
+     */
+    parseError<E extends BaseError>(err: Error | string): E;
+    /**
+     * @description Submits a transaction to the Fabric network
+     * @summary Executes a transaction that modifies the ledger state
+     * @param {string} api - The chaincode function to call
+     * @param {any[]} [args] - Arguments to pass to the chaincode function
+     * @param {Record<string, string>} [transientData] - Transient data for the transaction
+     * @param {Array<string>} [endorsingOrganizations] - Organizations that must endorse the transaction
+     * @return {Promise<Uint8Array>} Promise resolving to the transaction result
+     */
+    submitTransaction(ctx: Context<FabricClientFlags>, api: string, args?: any[], transientData?: Record<string, string>, endorsingOrganizations?: Array<string>, className?: string): Promise<Uint8Array>;
+    /**
+     * @description Evaluates a transaction on the Fabric network
+     * @summary Executes a transaction that does not modify the ledger state
+     * @param {string} api - The chaincode function to call
+     * @param {any[]} [args] - Arguments to pass to the chaincode function
+     * @param {Record<string, string>} [transientData] - Transient data for the transaction
+     * @param {Array<string>} [endorsingOrganizations] - Organizations that must endorse the transaction
+     * @return {Promise<Uint8Array>} Promise resolving to the transaction result
+     */
+    evaluateTransaction(ctx: Context<FabricClientFlags>, api: string, args?: any[], transientData?: Record<string, string>, endorsingOrganizations?: Array<string>, className?: string): Promise<Uint8Array>;
+    migrate(reference: string, ...args: MaybeContextualArg<Context<FabricClientFlags>>): Promise<Uint8Array>;
+    /**
+     * @description Shuts down the connection to the Fabric network
+     * @summary Closes the active dispatch (which in turn closes any gateway
+     * event subscription) via the base class, then closes the gRPC client.
+     * Works correctly regardless of whether `syntheticEvents` is enabled.
+     * @return {Promise<void>} Promise that resolves when all connections are closed
+     */
+    shutdown(...args: MaybeContextualArg<Context<FabricClientFlags>>): Promise<void>;
+    /**
+     * @description Gets a Contract instance from a Gateway
+     * @summary Retrieves a chaincode contract from the specified network
+     * @param {Gateway} gateway - The Gateway instance
+     * @param {PeerConfig} config - The peer configuration
+     * @return {Contrakt} The Contract instance
+     */
+    static getContract(gateway: Gateway, config: PeerConfig, contractName?: string): Contrakt;
+    /**
+     * @description Gets a Network instance from a Gateway
+     * @summary Connects to a specific channel on the Fabric network
+     * @param {Gateway} gateway - The Gateway instance
+     * @param {string} channelName - The name of the channel to connect to
+     * @return {Network} The Network instance
+     */
+    static getNetwork(gateway: Gateway, channelName: string): Network;
+    /**
+     * @description Gets a Gateway instance for connecting to the Fabric network
+     * @summary Creates a Gateway using the provided configuration and client
+     * @param {PeerConfig} config - The peer configuration
+     * @param {Client} [client] - Optional gRPC client, will be created if not provided
+     * @return {Promise<Gateway>} Promise resolving to the Gateway instance
+     */
+    static getGateway(ctx: Context<FabricClientFlags>, config: PeerConfig, client?: Client): Promise<Gateway>;
+    /**
+     * @description Creates a gRPC client for connecting to a Fabric peer
+     * @summary Initializes a client with TLS credentials for secure communication
+     * @param {PeerConfig} config - The peer configuration
+     * @return {Client} Promise resolving to the gRPC client
+     */
+    static getClient(config: PeerConfig): Client;
+    /**
+     * @description Establishes a connection to the Fabric network
+     * @summary Creates a Gateway connection with identity and signer
+     * @param {Client} client - The gRPC client
+     * @param {PeerConfig} config - The peer configuration
+     * @return {Promise<Gateway>} Promise resolving to the connected Gateway
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant FabricAdapter
+     *   participant Identity
+     *   participant Signer
+     *   participant Gateway
+     *
+     *   Caller->>FabricAdapter: getConnection(client, config)
+     *   FabricAdapter->>Identity: getIdentity(mspId, certDirectoryPath)
+     *   Identity-->>FabricAdapter: identity
+     *   FabricAdapter->>Signer: getSigner(keyDirectoryPath)
+     *   Signer-->>FabricAdapter: signer
+     *   FabricAdapter->>FabricAdapter: Create ConnectOptions
+     *   FabricAdapter->>Gateway: connect(options)
+     *   Gateway-->>FabricAdapter: gateway
+     *   FabricAdapter-->>Caller: gateway
+     */
+    static getConnection(client: Client, config: PeerConfig, ctx: Context<FabricClientFlags>): Promise<Gateway>;
+    /**
+     * @description Creates a new Dispatch instance for the Fabric client.
+     * @summary This function is responsible for creating a new FabricClientDispatch instance that can be used to interact with the Fabric network.
+     * @returns {Dispatch} A new Dispatch instance configured for the Fabric client.
+     * @remarks The Dispatch instance is used to encapsulate the logic for interacting with the Fabric network, such as submitting transactions or querying data.
+     * @example
+     * const fabricDispatch = fabricClientAdapter.Dispatch();
+     * fabricDispatch.submitTransaction('createProduct', { name: 'Product A', price: 100 });
+     */
+    Dispatch(): FabricClientDispatch;
+    /**
+     * @description Parses an error into a BaseError
+     * @summary Converts any error into a standardized BaseError using the parent class implementation
+     * @param {Error | string} err - The error to parse
+     * @param {string} [reason] - Optional reason for the error
+     * @return {BaseError} The parsed error
+     */
+    protected static parseError<E extends BaseError>(err: Error | string | GatewayError): E;
+}

package/lib/types/client/FabricClientDispatch.d.cts

@@ -0,0 +1,133 @@
+import { Adapter, ContextualArgs, Dispatch, EventIds, Context } from "@decaf-ts/core";
+import { Client } from "@grpc/grpc-js";
+import { FabricClientAdapter } from "./FabricClientAdapter.cjs";
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { Constructor } from "@decaf-ts/decoration";
+import { FabricClientFlags } from "./types.cjs";
+/**
+ * @description Event dispatcher for Hyperledger Fabric chaincode events
+ * @summary Listens for and processes events emitted by Fabric chaincode, dispatching them to registered observers
+ * @template PeerConfig - Configuration type for connecting to a Fabric peer
+ * @param client - gRPC client for connecting to the Fabric network
+ * @class FabricClientDispatch
+ * @example
+ * ```typescript
+ * // Create a new FabricDispatch instance
+ * const client = await FabricAdapter.getClient(peerConfig);
+ * const dispatch = new FabricDispatch(client);
+ *
+ * // Configure the dispatch with peer configuration
+ * dispatch.configure(peerConfig);
+ *
+ * // Register an observer for a specific table and event
+ * dispatch.observe('users', 'create', (id) => {
+ *   console.log(`User created: ${id}`);
+ * });
+ *
+ * // Start listening for events
+ * await dispatch.start();
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant FabricDispatch
+ *   participant Gateway
+ *   participant Network
+ *   participant Chaincode
+ *
+ *   Client->>FabricDispatch: new FabricDispatch(client)
+ *   Client->>FabricDispatch: configure(peerConfig)
+ *   Client->>FabricDispatch: observe(table, event, callback)
+ *   Client->>FabricDispatch: start()
+ *   FabricDispatch->>FabricDispatch: initialize()
+ *   FabricDispatch->>Gateway: getGateway(config, client)
+ *   Gateway->>Network: getNetwork(channel)
+ *   Network->>Network: getChaincodeEvents(chaincodeName)
+ *   FabricDispatch->>FabricDispatch: handleEvents()
+ *   loop For each event
+ *     Chaincode-->>FabricDispatch: ChaincodeEvent
+ *     FabricDispatch->>FabricDispatch: parseEventName(eventName)
+ *     FabricDispatch->>FabricDispatch: parsePayload(payload)
+ *     FabricDispatch->>FabricDispatch: updateObservers(table, event, id)
+ *     FabricDispatch-->>Client: callback(id)
+ *   end
+ */
+export declare class FabricClientDispatch extends Dispatch<FabricClientAdapter> {
+    protected client: Client;
+    /**
+     * @description Event listening stack for chaincode events
+     */
+    private listeningStack?;
+    /**
+     * @description Text decoder for converting event payloads from bytes to strings
+     */
+    private decoder;
+    /**
+     * @description Creates a new FabricDispatch instance
+     * @summary Initializes a dispatcher for Fabric chaincode events
+     * @param {Client} client - gRPC client for connecting to the Fabric network
+     */
+    constructor(client: Client);
+    /**
+     * @description Closes the event listening connection
+     * @summary Stops listening for chaincode events and releases resources
+     * @return {Promise<void>} Promise that resolves when the connection is closed
+     */
+    close(...ctxArgs: ContextualArgs<Context<FabricClientFlags>>): Promise<void>;
+    /**
+     * @description Parses event payload from binary format
+     * @summary Converts a Uint8Array containing JSON to an object with an id property
+     * @param {Uint8Array} jsonBytes - The binary payload from the chaincode event
+     * @return {{ id: string }} The parsed payload containing the record ID
+     */
+    private parsePayload;
+    /**
+     * @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 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 {any} payload - The event payload
+     * @return {Promise<void>} A promise that resolves when all observers have been notified
+     */
+    updateObservers(model: Constructor<any> | string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<void>;
+    /**
+     * @description Processes incoming chaincode events
+     * @summary Listens for events from the chaincode and dispatches them to registered observers
+     * @return {Promise<void>} Promise that resolves when event handling stops
+     * @mermaid
+     * sequenceDiagram
+     *   participant FabricDispatch
+     *   participant EventStack
+     *   participant EventParser
+     *   participant Observers
+     *
+     *   FabricDispatch->>FabricDispatch: handleEvents()
+     *   FabricDispatch->>EventStack: for await (const evt of listeningStack)
+     *   EventStack-->>FabricDispatch: ChaincodeEvent
+     *   FabricDispatch->>EventParser: parseEventName(evt.eventName)
+     *   EventParser-->>FabricDispatch: { table, event, owner }
+     *   FabricDispatch->>FabricDispatch: Check if event is for this MSP
+     *   FabricDispatch->>FabricDispatch: parsePayload(evt.payload)
+     *   FabricDispatch->>Observers: updateObservers(table, event, payload.id)
+     *   Observers-->>FabricDispatch: Callbacks executed
+     */
+    protected handleEvents(ctxArg?: Context<FabricClientFlags>): Promise<void>;
+    /**
+     * @description Initializes the event listener
+     * @summary Sets up event dispatching for the observed adapter. When
+     * `syntheticEvents` is true (the default) no gateway connection is opened;
+     * instead every CRUD operation is wrapped with a Proxy that fires
+     * `updateObservers` for **all** models. When `syntheticEvents` is false the
+     * existing gateway-based chaincode-event subscription is established and the
+     * local Proxy fallback is limited to fully-segregated (transient) models only.
+     * @return {Promise<void>} Promise that resolves when initialization is complete
+     */
+    protected initialize(): Promise<void>;
+}

package/lib/types/client/FabricClientDispatch.d.mts

@@ -0,0 +1,133 @@
+import { Adapter, ContextualArgs, Dispatch, EventIds, Context } from "@decaf-ts/core";
+import { Client } from "@grpc/grpc-js";
+import { FabricClientAdapter } from "./FabricClientAdapter.js";
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { Constructor } from "@decaf-ts/decoration";
+import { FabricClientFlags } from "./types.js";
+/**
+ * @description Event dispatcher for Hyperledger Fabric chaincode events
+ * @summary Listens for and processes events emitted by Fabric chaincode, dispatching them to registered observers
+ * @template PeerConfig - Configuration type for connecting to a Fabric peer
+ * @param client - gRPC client for connecting to the Fabric network
+ * @class FabricClientDispatch
+ * @example
+ * ```typescript
+ * // Create a new FabricDispatch instance
+ * const client = await FabricAdapter.getClient(peerConfig);
+ * const dispatch = new FabricDispatch(client);
+ *
+ * // Configure the dispatch with peer configuration
+ * dispatch.configure(peerConfig);
+ *
+ * // Register an observer for a specific table and event
+ * dispatch.observe('users', 'create', (id) => {
+ *   console.log(`User created: ${id}`);
+ * });
+ *
+ * // Start listening for events
+ * await dispatch.start();
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant FabricDispatch
+ *   participant Gateway
+ *   participant Network
+ *   participant Chaincode
+ *
+ *   Client->>FabricDispatch: new FabricDispatch(client)
+ *   Client->>FabricDispatch: configure(peerConfig)
+ *   Client->>FabricDispatch: observe(table, event, callback)
+ *   Client->>FabricDispatch: start()
+ *   FabricDispatch->>FabricDispatch: initialize()
+ *   FabricDispatch->>Gateway: getGateway(config, client)
+ *   Gateway->>Network: getNetwork(channel)
+ *   Network->>Network: getChaincodeEvents(chaincodeName)
+ *   FabricDispatch->>FabricDispatch: handleEvents()
+ *   loop For each event
+ *     Chaincode-->>FabricDispatch: ChaincodeEvent
+ *     FabricDispatch->>FabricDispatch: parseEventName(eventName)
+ *     FabricDispatch->>FabricDispatch: parsePayload(payload)
+ *     FabricDispatch->>FabricDispatch: updateObservers(table, event, id)
+ *     FabricDispatch-->>Client: callback(id)
+ *   end
+ */
+export declare class FabricClientDispatch extends Dispatch<FabricClientAdapter> {
+    protected client: Client;
+    /**
+     * @description Event listening stack for chaincode events
+     */
+    private listeningStack?;
+    /**
+     * @description Text decoder for converting event payloads from bytes to strings
+     */
+    private decoder;
+    /**
+     * @description Creates a new FabricDispatch instance
+     * @summary Initializes a dispatcher for Fabric chaincode events
+     * @param {Client} client - gRPC client for connecting to the Fabric network
+     */
+    constructor(client: Client);
+    /**
+     * @description Closes the event listening connection
+     * @summary Stops listening for chaincode events and releases resources
+     * @return {Promise<void>} Promise that resolves when the connection is closed
+     */
+    close(...ctxArgs: ContextualArgs<Context<FabricClientFlags>>): Promise<void>;
+    /**
+     * @description Parses event payload from binary format
+     * @summary Converts a Uint8Array containing JSON to an object with an id property
+     * @param {Uint8Array} jsonBytes - The binary payload from the chaincode event
+     * @return {{ id: string }} The parsed payload containing the record ID
+     */
+    private parsePayload;
+    /**
+     * @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 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 {any} payload - The event payload
+     * @return {Promise<void>} A promise that resolves when all observers have been notified
+     */
+    updateObservers(model: Constructor<any> | string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: ContextualArgs<Context<FabricClientFlags>>): Promise<void>;
+    /**
+     * @description Processes incoming chaincode events
+     * @summary Listens for events from the chaincode and dispatches them to registered observers
+     * @return {Promise<void>} Promise that resolves when event handling stops
+     * @mermaid
+     * sequenceDiagram
+     *   participant FabricDispatch
+     *   participant EventStack
+     *   participant EventParser
+     *   participant Observers
+     *
+     *   FabricDispatch->>FabricDispatch: handleEvents()
+     *   FabricDispatch->>EventStack: for await (const evt of listeningStack)
+     *   EventStack-->>FabricDispatch: ChaincodeEvent
+     *   FabricDispatch->>EventParser: parseEventName(evt.eventName)
+     *   EventParser-->>FabricDispatch: { table, event, owner }
+     *   FabricDispatch->>FabricDispatch: Check if event is for this MSP
+     *   FabricDispatch->>FabricDispatch: parsePayload(evt.payload)
+     *   FabricDispatch->>Observers: updateObservers(table, event, payload.id)
+     *   Observers-->>FabricDispatch: Callbacks executed
+     */
+    protected handleEvents(ctxArg?: Context<FabricClientFlags>): Promise<void>;
+    /**
+     * @description Initializes the event listener
+     * @summary Sets up event dispatching for the observed adapter. When
+     * `syntheticEvents` is true (the default) no gateway connection is opened;
+     * instead every CRUD operation is wrapped with a Proxy that fires
+     * `updateObservers` for **all** models. When `syntheticEvents` is false the
+     * existing gateway-based chaincode-event subscription is established and the
+     * local Proxy fallback is limited to fully-segregated (transient) models only.
+     * @return {Promise<void>} Promise that resolves when initialization is complete
+     */
+    protected initialize(): Promise<void>;
+}