@decaf-ts/for-fabric 0.0.2

package/lib/esm/client/FabricClientAdapter.d.ts

@@ -0,0 +1,381 @@
+import { CouchDBAdapter, type MangoQuery } from "@decaf-ts/for-couchdb";
+import { Client } from "@grpc/grpc-js";
+import { type Constructor, Model, type Serializer } from "@decaf-ts/decorator-validation";
+import { Logger } from "@decaf-ts/logging";
+import { FabricFlags, PeerConfig } from "../shared/types";
+import { Gateway, Network, Contract as Contrakt } from "@hyperledger/fabric-gateway";
+import { BaseError, Context } from "@decaf-ts/db-decorators";
+import { Adapter, Dispatch, Repository } from "@decaf-ts/core";
+/**
+ * @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 CouchDBAdapter<PeerConfig, Client, FabricFlags, Context<FabricFlags>> {
+    /**
+     * @description Static text decoder for converting Uint8Array to string
+     */
+    private static decoder;
+    private static serializer;
+    /**
+     * @description Static logger instance for the FabricAdapter class
+     */
+    private static log;
+    /**
+     * @description Gets the logger instance for this adapter
+     * @summary Returns the static logger instance for the FabricAdapter class
+     * @return {Logger} The logger instance
+     */
+    protected get log(): 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);
+    /**
+     * @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<M extends Model<true | false>>(): Constructor<Repository<M, MangoQuery, Adapter<PeerConfig, Client, MangoQuery, FabricFlags, Context<FabricFlags>>, FabricFlags, Context<FabricFlags>>>;
+    /**
+     * @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(tableName: string, ids: string[] | number[], models: Record<string, any>[], transient: Record<string, any>): 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(tableName: string, ids: string[] | number[]): 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(tableName: string, ids: string[] | number[], models: Record<string, any>[], transient: Record<string, any>): 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(tableName: string, ids: (string | number | bigint)[]): 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, pk: keyof M): {
+        record: Record<string, any>;
+        id: string;
+        transient?: Record<string, any>;
+    };
+    /**
+     * @description Converts database data back into a model instance
+     * @summary Reconstructs a model instance from database data, handling column mapping
+     * and reattaching transient properties
+     * @template M - The model type
+     * @param obj - The database record
+     * @param {string|Constructor<M>} clazz - The model class or name
+     * @param pk - The primary key property name
+     * @param {string|number|bigint} id - The primary key value
+     * @param [transient] - Transient properties to reattach
+     * @return {M} The reconstructed model instance
+     */
+    revert<M extends Model>(obj: Record<string, any>, clazz: string | Constructor<M>, pk: keyof M, id: string | number | bigint, transient?: Record<string, any>): M;
+    /**
+     * @description Creates an index for a model
+     * @summary This method is not implemented for Fabric and will throw an error
+     * @template M - Type extending Model
+     * @param {Constructor<M>} models - The model constructor
+     * @return {Promise<void>} Promise that will throw an error
+     */
+    protected index<M>(models: Constructor<M>): Promise<void>;
+    /**
+     * @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(tableName: string, id: string | number, model: Record<string, any>, transient: Record<string, any>): 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(tableName: string, id: string | number): Promise<Record<string, 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(tableName: string, id: string | number, model: Record<string, any>, transient: Record<string, any>): 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(tableName: string, id: string | number): 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>(rawInput: MangoQuery, process: boolean): Promise<V>;
+    /**
+     * @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(): Promise<Gateway>;
+    /**
+     * @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(): 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(api: string, submit?: boolean, args?: any[], transientData?: Record<string, string>, endorsingOrganizations?: Array<string>): Promise<Uint8Array>;
+    /**
+     * @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(err: Error | string, reason?: string): BaseError;
+    /**
+     * @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(api: string, args?: any[], transientData?: Record<string, string>, endorsingOrganizations?: Array<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(api: string, args?: any[], transientData?: Record<string, string>, endorsingOrganizations?: Array<string>): Promise<Uint8Array>;
+    /**
+     * @description Closes the connection to the Fabric network
+     * @summary Closes the gRPC client if it exists
+     * @return {Promise<void>} Promise that resolves when the client is closed
+     */
+    close(): 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): 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(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): 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(): Dispatch;
+    /**
+     * @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(err: Error | string, reason?: string): BaseError;
+}