@decaf-ts/for-fabric 0.0.2

package/lib/esm/contracts/ContractAdapter.d.ts

@@ -0,0 +1,296 @@
+import { CouchDBAdapter, MangoQuery } from "@decaf-ts/for-couchdb";
+import { Constructor, Model } from "@decaf-ts/decorator-validation";
+import { FabricContractFlags } from "./types";
+import { FabricContractContext } from "./ContractContext";
+import { Context, OperationKeys } from "@decaf-ts/db-decorators";
+import { Context as Ctx } from "fabric-contract-api";
+import { Logger } from "@decaf-ts/logging";
+import { ContractLogger } from "./logging";
+import { RelationsMetadata, Repository, Sequence, SequenceOptions, Adapter } from "@decaf-ts/core";
+import { FabricContractRepository } from "./FabricContractRepository";
+import { ChaincodeStub, Iterators, StateQueryResponse } from "fabric-shim-api";
+import { FabricStatement } from "./FabricContractStatement";
+import { SimpleDeterministicSerializer } from "../shared/SimpleDeterministicSerializer";
+/**
+ * @description Sets the creator or updater field in a model based on the user in the context
+ * @summary Callback function used in decorators to automatically set the created_by or updated_by fields
+ * with the username from the context when a document is created or updated
+ * @template M - Type extending Model
+ * @template R - Type extending NanoRepository<M>
+ * @template V - Type extending RelationsMetadata
+ * @param {R} this - The repository instance
+ * @param {FabricContractContext} context - The operation context containing user information
+ * @param {V} data - The relation metadata
+ * @param {string} key - The property key to set with the username
+ * @param {M} model - The model instance being created or updated
+ * @return {Promise<void>} A promise that resolves when the operation is complete
+ * @function createdByOnFabricCreateUpdate
+ * @memberOf module:fabric.contracts
+ * @mermaid
+ * sequenceDiagram
+ *   participant F as createdByOnNanoCreateUpdate
+ *   participant C as Context
+ *   participant M as Model
+ *   F->>C: get("user")
+ *   C-->>F: user object
+ *   F->>M: set key to user.name
+ *   Note over F: If no user in context
+ *   F-->>F: throw UnsupportedError
+ */
+export declare function createdByOnFabricCreateUpdate<M extends Model, R extends FabricContractRepository<M>, V extends RelationsMetadata>(this: R, context: Context<FabricContractFlags>, data: V, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Primary key auto-assignment callback for Fabric models
+ * @summary Generates and assigns a primary key value to the specified model property using a Fabric-backed sequence when the model is created. If the sequence name is not provided in options, it is derived from the model via sequenceNameForModel. The assigned key is defined as non-writable and enumerable.
+ * @template M - Type extending Model for the target instance
+ * @template R - Type extending FabricContractRepository for repository context
+ * @template V - Type extending SequenceOptions to configure sequence behavior
+ * @template F - Type extending FabricContractFlags for contextual flags
+ * @param {R} this - The repository instance invoking the callback
+ * @param {FabricContractContext} context - Fabric contract context containing invocation metadata
+ * @param {V} data - Sequence options used to configure or locate the sequence
+ * @param {string} key - The primary key property name to assign on the model
+ * @param {M} model - The model instance to receive the generated primary key
+ * @return {Promise<void>} Resolves when the key is assigned or when no action is required
+ * @function pkFabricOnCreate
+ * @memberOf module:for-fabric.contracts
+ * @mermaid
+ * sequenceDiagram
+ *   participant R as Repository
+ *   participant C as Context<F>
+ *   participant S as FabricContractDBSequence
+ *   participant M as Model
+ *   R->>R: derive sequence name if missing
+ *   R->>S: adapter.Sequence(options)
+ *   S-->>R: sequence instance
+ *   R->>S: next(context)
+ *   S-->>R: next value
+ *   R->>M: define non-writable primary key
+ */
+export declare function pkFabricOnCreate<M extends Model, R extends FabricContractRepository<M>, V extends SequenceOptions, F extends FabricContractFlags>(this: R, context: Context<F>, data: V, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Adapter for Hyperledger Fabric chaincode state database operations
+ * @summary Provides a CouchDB-like interface for interacting with the Fabric state database from within a chaincode contract
+ * @template void - No configuration needed for contract adapter
+ * @template FabricContractFlags - Flags specific to Fabric contract operations
+ * @template FabricContractContext - Context type for Fabric contract operations
+ * @class FabricContractAdapter
+ * @example
+ * ```typescript
+ * // In a Fabric chaincode contract class
+ * import { FabricContractAdapter } from '@decaf-ts/for-fabric';
+ *
+ * export class MyContract extends Contract {
+ *   private adapter = new FabricContractAdapter();
+ *
+ *   @Transaction()
+ *   async createAsset(ctx: Context, id: string, data: string): Promise<void> {
+ *     const model = { id, data, timestamp: Date.now() };
+ *     await this.adapter.create('assets', id, model, {}, { stub: ctx.stub });
+ *   }
+ * }
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Contract
+ *   participant FabricContractAdapter
+ *   participant Stub
+ *   participant StateDB
+ *
+ *   Contract->>FabricContractAdapter: create(tableName, id, model, transient, ctx)
+ *   FabricContractAdapter->>FabricContractAdapter: Serialize model to JSON
+ *   FabricContractAdapter->>Stub: putState(id, serializedData)
+ *   Stub->>StateDB: Write data
+ *   StateDB-->>Stub: Success
+ *   Stub-->>FabricContractAdapter: Success
+ *   FabricContractAdapter-->>Contract: model
+ */
+export declare class FabricContractAdapter extends CouchDBAdapter<any, void, FabricContractFlags, FabricContractContext> {
+    protected getClient(): void;
+    /**
+     * @description Text decoder for converting binary data to strings
+     */
+    private static textDecoder;
+    protected static readonly serializer: SimpleDeterministicSerializer<Model<false>>;
+    /**
+     * @description Creates a logger for a specific chaincode context
+     * @summary Returns a ContractLogger instance configured for the current context
+     * @param {Ctx} ctx - The Fabric chaincode context
+     * @return {ContractLogger} The logger instance
+     */
+    logFor(ctx: Ctx): ContractLogger;
+    /**
+     * @description Context constructor for this adapter
+     * @summary Overrides the base Context constructor with FabricContractContext
+     */
+    Context: typeof FabricContractContext;
+    /**
+     * @description Gets the repository constructor for this adapter
+     * @summary Returns the FabricContractRepository constructor for creating repositories
+     * @template M - Type extending Model
+     * @return {Constructor<Repository<M, MangoQuery, FabricContractAdapter, FabricContractFlags, FabricContractContext>>} The repository constructor
+     */
+    repository<M extends Model>(): Constructor<Repository<M, MangoQuery, Adapter<any, any, MangoQuery, FabricContractFlags, FabricContractContext>, FabricContractFlags, FabricContractContext>>;
+    /**
+     * @description Creates a new FabricContractAdapter instance
+     * @summary Initializes an adapter for interacting with the Fabric state database
+     * @param {void} scope - Not used in this adapter
+     * @param {string} [alias] - Optional alias for the adapter instance
+     */
+    constructor(scope: void, alias?: string);
+    for(config: Partial<any>, ...args: any): typeof this;
+    /**
+     * @description Creates a record in the state database
+     * @summary Serializes a model and stores it in the Fabric state database
+     * @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 (not used in this implementation)
+     * @param {...any[]} args - Additional arguments, including the chaincode stub and logger
+     * @return {Promise<Record<string, any>>} Promise resolving to the created record
+     */
+    create(tableName: string, id: string | number, model: Record<string, any>, ...args: any[]): Promise<Record<string, any>>;
+    /**
+     * @description Reads a record from the state database
+     * @summary Retrieves and deserializes a record from the Fabric state database
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The record identifier
+     * @param {...any[]} args - Additional arguments, including the chaincode stub and logger
+     * @return {Promise<Record<string, any>>} Promise resolving to the retrieved record
+     */
+    read(tableName: string, id: string | number, ...args: any[]): Promise<Record<string, any>>;
+    /**
+     * @description Updates a record in the state database
+     * @summary Serializes a model and updates it in the Fabric state database
+     * @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 (not used in this implementation)
+     * @param {...any[]} args - Additional arguments, including the chaincode stub and logger
+     * @return {Promise<Record<string, any>>} Promise resolving to the updated record
+     */
+    update(tableName: string, id: string | number, model: Record<string, any>, ...args: any[]): Promise<Record<string, any>>;
+    /**
+     * @description Deletes a record from the state database
+     * @summary Retrieves a record and then removes it from the Fabric state database
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The record identifier to delete
+     * @param {...any[]} args - Additional arguments, including the chaincode stub and logger
+     * @return {Promise<Record<string, any>>} Promise resolving to the deleted record
+     */
+    delete(tableName: string, id: string | number, ...args: any[]): Promise<Record<string, any>>;
+    protected deleteState(stub: ChaincodeStub, tableName: string, id: string, ...args: any[]): Promise<void>;
+    protected putState(stub: ChaincodeStub, id: string, model: Record<string, any>, ...args: any[]): Promise<Record<string, any>>;
+    protected readState(stub: ChaincodeStub, tableName: string, id: string, ...args: any[]): Promise<any[]>;
+    protected queryResult(stub: ChaincodeStub, rawInput: any, ...args: any[]): Promise<Iterators.StateQueryIterator>;
+    protected queryResultPaginated(stub: ChaincodeStub, rawInput: any, limit?: number, skip?: number, ...args: any[]): Promise<StateQueryResponse<Iterators.StateQueryIterator>>;
+    protected mergeModels(results: Record<string, any>[]): Record<string, any>;
+    /**
+     * @description Decodes binary data to string
+     * @summary Converts a Uint8Array to a string using UTF-8 encoding
+     * @param {Uint8Array} buffer - The binary data to decode
+     * @return {string} The decoded string
+     */
+    protected decode(buffer: Uint8Array): string;
+    /**
+     * @description Creates operation flags for Fabric contract operations
+     * @summary Merges default flags with Fabric-specific context information
+     * @template M - Type extending Model
+     * @param {OperationKeys} operation - The operation being performed
+     * @param {Constructor<M>} model - The model constructor
+     * @param {Partial<FabricContractFlags>} flags - Partial flags to merge with defaults
+     * @param {Ctx} ctx - The Fabric chaincode context
+     * @return {FabricContractFlags} The merged flags
+     */
+    protected flags<M extends Model>(operation: OperationKeys, model: Constructor<M>, flags: Partial<FabricContractFlags>, ctx: Ctx, ...args: any[]): Promise<FabricContractFlags>;
+    /**
+     * @description Creates an index for a model
+     * @summary This method is not implemented for Fabric contracts and returns a resolved promise
+     * @template M - Type extending Model
+     * @param {Constructor<M>} models - The model constructor
+     * @return {Promise<void>} Promise that resolves immediately
+     */
+    protected index<M>(models: Constructor<M>): Promise<void>;
+    /**
+     * @description Processes results from a state query iterator
+     * @summary Iterates through query results and converts them to a structured format
+     * @param {Logger} log - Logger instance for debugging
+     * @param {Iterators.StateQueryIterator} iterator - The state query iterator
+     * @param {boolean} [isHistory=false] - Whether this is a history query
+     * @return {Promise<any[]>} Promise resolving to an array of processed results
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant ResultIterator
+     *   participant Iterator
+     *
+     *   Caller->>ResultIterator: resultIterator(log, iterator, isHistory)
+     *   loop Until done
+     *     ResultIterator->>Iterator: next()
+     *     Iterator-->>ResultIterator: { value, done }
+     *     alt Has value
+     *       ResultIterator->>ResultIterator: Process value based on isHistory
+     *       ResultIterator->>ResultIterator: Add to results array
+     *     end
+     *   end
+     *   ResultIterator->>Iterator: close()
+     *   ResultIterator-->>Caller: allResults
+     */
+    protected resultIterator(log: Logger, iterator: Iterators.StateQueryIterator, isHistory?: boolean): Promise<any[]>;
+    /**
+     * @description Executes a raw query against the state database
+     * @summary Performs a rich query using CouchDB syntax against the Fabric state database
+     * @template R - The return type
+     * @param {MangoQuery} rawInput - The Mango Query to execute
+     * @param {boolean} docsOnly - Whether to return only documents (not used in this implementation)
+     * @param {...any[]} args - Additional arguments, including the chaincode stub and logger
+     * @return {Promise<R>} Promise resolving to the query results
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant FabricContractAdapter
+     *   participant Stub
+     *   participant StateDB
+     *
+     *   Caller->>FabricContractAdapter: raw(rawInput, docsOnly, ctx)
+     *   FabricContractAdapter->>FabricContractAdapter: Extract limit and skip
+     *   alt With pagination
+     *     FabricContractAdapter->>Stub: getQueryResultWithPagination(query, limit, skip)
+     *   else Without pagination
+     *     FabricContractAdapter->>Stub: getQueryResult(query)
+     *   end
+     *   Stub->>StateDB: Execute query
+     *   StateDB-->>Stub: Iterator
+     *   Stub-->>FabricContractAdapter: Iterator
+     *   FabricContractAdapter->>FabricContractAdapter: resultIterator(log, iterator)
+     *   FabricContractAdapter-->>Caller: results
+     */
+    raw<R>(rawInput: MangoQuery, docsOnly: boolean, ...args: any[]): Promise<R>;
+    Statement<M extends Model>(ctx?: FabricContractContext): FabricStatement<M, any>;
+    Sequence(options: SequenceOptions): Promise<Sequence>;
+    createAll(tableName: string, id: (string | number)[], model: Record<string, any>[], ...args: any[]): Promise<Record<string, any>[]>;
+    updateAll(tableName: string, id: string[] | number[], model: Record<string, any>[], ...args: any[]): Promise<Record<string, any>[]>;
+    /**
+     *
+     * @param model
+     * @param {string} pk
+     * @param args
+     */
+    prepare<M extends Model>(model: M, pk: keyof M, ...args: any[]): {
+        record: Record<string, any>;
+        id: string;
+        transient?: Record<string, any>;
+    };
+    revert<M extends Model>(obj: Record<string, any>, clazz: string | Constructor<M>, pk: keyof M, id: string | number, transient?: Record<string, any>): M;
+    createPrefix(tableName: string, id: string | number, model: Record<string, any>, ...args: any[]): (string | number | Record<string, any> | FabricContractContext)[];
+    updatePrefix(tableName: string, id: string | number, model: Record<string, any>, ...args: any[]): (string | number | Record<string, any>)[];
+    protected createAllPrefix(tableName: string, ids: string[] | number[], models: Record<string, any>[], ...args: any[]): (string | string[] | number[] | Record<string, any>[])[];
+    protected updateAllPrefix(tableName: string, ids: string[] | number[], models: Record<string, any>[], ...args: any[]): any[];
+    /**
+     * @description Static method for decoration overrides
+     * @summary Overrides/extends decaf decoration with Fabric-specific functionality
+     * @static
+     * @override
+     * @return {void}
+     */
+    static decoration(): void;
+}