@decaf-ts/for-fabric 0.9.0 → 0.11.0

package/lib/types/contracts/ContractContext.d.cts

@@ -0,0 +1,89 @@
+import { Context } from "@decaf-ts/core";
+import { FabricContractFlags } from "./types.cjs";
+import { ChaincodeStub, ClientIdentity } from "fabric-shim-api";
+/**
+ * @description Context class for Fabric chaincode operations
+ * @summary Provides access to Fabric-specific context elements like stub, identity, and logger to be used by repositories and adapters during contract execution.
+ * @template F - Flags specific to Fabric contract operations
+ * @param {object} [args] - Optional initialization arguments passed to the base Context
+ * @return {void}
+ * @class FabricContractContext
+ * @example
+ * ```typescript
+ * // In a Fabric chaincode contract method
+ * const context = new FabricContractContext();
+ * // Optionally set values via the base Context API
+ * context.set('stub', ctx.stub);
+ * context.set('clientIdentity', ctx.clientIdentity);
+ * context.set('logger', contractLogger);
+ *
+ * // Access context properties
+ * const timestamp = context.timestamp;
+ * const creator = context.identity.getID();
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Contract
+ *   participant Context
+ *   participant Ledger
+ *   Contract->>Context: new FabricContractContext()
+ *   Contract->>Context: set('stub'|'clientIdentity'|'logger', ...)
+ *   Context-->>Contract: timestamp, identity, logger
+ *   Contract->>Ledger: Interact via stub
+ */
+export declare class FabricContractContext extends Context<FabricContractFlags> {
+    /**
+     * @description Creates a new FabricContractContext instance
+     * @summary Initializes the context with Fabric-specific flags
+     */
+    constructor(ctx?: FabricContractContext);
+    /**
+     * @description Gets the chaincode stub
+     * @summary Returns the ChaincodeStub instance for interacting with the ledger
+     * @return {ChaincodeStub} The chaincode stub
+     */
+    get stub(): ChaincodeStub;
+    /**
+     * @description Gets the transaction timestamp
+     * @summary Overrides the base timestamp getter to use the stub's timestamp
+     * @return {Date} The transaction timestamp
+     */
+    get timestamp(): Date;
+    /**
+     * @description Gets the client identity
+     * @summary Returns the ClientIdentity instance for the transaction submitter
+     * @return {ClientIdentity} The client identity
+     */
+    get identity(): ClientIdentity;
+    /**
+     * @description Stores segregation metadata per sequence name
+     * @summary Needed because the Sequence creates its own context (via logCtx),
+     * losing flags set by extractSegregatedCollections on the handler context.
+     * The adapter persists across operations, making it a reliable store.
+     */
+    setSequenceSegregation(seqName: string, fullySegregated: boolean, collections: string[]): void;
+    getSequenceSegregation(seqName: string): {
+        fullySegregated: boolean;
+        collections: string[];
+    } | undefined;
+    markFullySegregated(): void;
+    get isFullySegregated(): boolean;
+    writeTo(col: string, entry: string[]): void;
+    getSegregatedWrites(): Record<string, string[]> | undefined;
+    put(key: string, value: any): void;
+    readFrom(cols: string | string[]): void;
+    consumeReadCollections(): string[];
+    /**
+     * @description Gets the collections registered for writing
+     * @summary Returns collection names from segregateWrite, used by sequences to know where to replicate.
+     * @return {string[]} Array of collection names, empty if none registered
+     */
+    getWriteCollections(): string[];
+    /**
+     * @description Gets the collections registered for reading
+     * @summary Returns collection names from segregateRead.
+     * @return {string[]} Array of collection names, empty if none registered
+     */
+    getReadCollections(): string[];
+    toString(): string;
+}

package/lib/types/contracts/ContractContext.d.mts

@@ -0,0 +1,89 @@
+import { Context } from "@decaf-ts/core";
+import { FabricContractFlags } from "./types.js";
+import { ChaincodeStub, ClientIdentity } from "fabric-shim-api";
+/**
+ * @description Context class for Fabric chaincode operations
+ * @summary Provides access to Fabric-specific context elements like stub, identity, and logger to be used by repositories and adapters during contract execution.
+ * @template F - Flags specific to Fabric contract operations
+ * @param {object} [args] - Optional initialization arguments passed to the base Context
+ * @return {void}
+ * @class FabricContractContext
+ * @example
+ * ```typescript
+ * // In a Fabric chaincode contract method
+ * const context = new FabricContractContext();
+ * // Optionally set values via the base Context API
+ * context.set('stub', ctx.stub);
+ * context.set('clientIdentity', ctx.clientIdentity);
+ * context.set('logger', contractLogger);
+ *
+ * // Access context properties
+ * const timestamp = context.timestamp;
+ * const creator = context.identity.getID();
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Contract
+ *   participant Context
+ *   participant Ledger
+ *   Contract->>Context: new FabricContractContext()
+ *   Contract->>Context: set('stub'|'clientIdentity'|'logger', ...)
+ *   Context-->>Contract: timestamp, identity, logger
+ *   Contract->>Ledger: Interact via stub
+ */
+export declare class FabricContractContext extends Context<FabricContractFlags> {
+    /**
+     * @description Creates a new FabricContractContext instance
+     * @summary Initializes the context with Fabric-specific flags
+     */
+    constructor(ctx?: FabricContractContext);
+    /**
+     * @description Gets the chaincode stub
+     * @summary Returns the ChaincodeStub instance for interacting with the ledger
+     * @return {ChaincodeStub} The chaincode stub
+     */
+    get stub(): ChaincodeStub;
+    /**
+     * @description Gets the transaction timestamp
+     * @summary Overrides the base timestamp getter to use the stub's timestamp
+     * @return {Date} The transaction timestamp
+     */
+    get timestamp(): Date;
+    /**
+     * @description Gets the client identity
+     * @summary Returns the ClientIdentity instance for the transaction submitter
+     * @return {ClientIdentity} The client identity
+     */
+    get identity(): ClientIdentity;
+    /**
+     * @description Stores segregation metadata per sequence name
+     * @summary Needed because the Sequence creates its own context (via logCtx),
+     * losing flags set by extractSegregatedCollections on the handler context.
+     * The adapter persists across operations, making it a reliable store.
+     */
+    setSequenceSegregation(seqName: string, fullySegregated: boolean, collections: string[]): void;
+    getSequenceSegregation(seqName: string): {
+        fullySegregated: boolean;
+        collections: string[];
+    } | undefined;
+    markFullySegregated(): void;
+    get isFullySegregated(): boolean;
+    writeTo(col: string, entry: string[]): void;
+    getSegregatedWrites(): Record<string, string[]> | undefined;
+    put(key: string, value: any): void;
+    readFrom(cols: string | string[]): void;
+    consumeReadCollections(): string[];
+    /**
+     * @description Gets the collections registered for writing
+     * @summary Returns collection names from segregateWrite, used by sequences to know where to replicate.
+     * @return {string[]} Array of collection names, empty if none registered
+     */
+    getWriteCollections(): string[];
+    /**
+     * @description Gets the collections registered for reading
+     * @summary Returns collection names from segregateRead.
+     * @return {string[]} Array of collection names, empty if none registered
+     */
+    getReadCollections(): string[];
+    toString(): string;
+}

package/lib/types/contracts/FabricContractDispatch.d.cts

@@ -0,0 +1,7 @@
+import { Dispatch, MaybeContextualArg } from "@decaf-ts/core";
+import { type FabricContractAdapter } from "./ContractAdapter.cjs";
+import { FabricContractContext } from "./ContractContext.cjs";
+export declare class FabricContractDispatch extends Dispatch<FabricContractAdapter> {
+    constructor();
+    protected initialize(...args: MaybeContextualArg<FabricContractContext>): Promise<void>;
+}

package/lib/types/contracts/FabricContractDispatch.d.mts

@@ -0,0 +1,7 @@
+import { Dispatch, MaybeContextualArg } from "@decaf-ts/core";
+import { type FabricContractAdapter } from "./ContractAdapter.js";
+import { FabricContractContext } from "./ContractContext.js";
+export declare class FabricContractDispatch extends Dispatch<FabricContractAdapter> {
+    constructor();
+    protected initialize(...args: MaybeContextualArg<FabricContractContext>): Promise<void>;
+}

package/lib/types/contracts/FabricContractPaginator.d.cts

@@ -0,0 +1,105 @@
+import { MaybeContextualArg } from "@decaf-ts/core";
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+import { FabricContractAdapter } from "./ContractAdapter.cjs";
+import { CouchDBPaginator, MangoQuery } from "@decaf-ts/for-couchdb";
+/**
+ * @description Paginator for CouchDB query results
+ * @summary Implements pagination for CouchDB queries using bookmarks for efficient navigation through result sets
+ * @template M - The model type that extends Model
+ * @template R - The result type
+ * @param {FabricCo<any, any, any>} adapter - The CouchDB adapter
+ * @param {MangoQuery} query - The Mango query to paginate
+ * @param {number} size - The page size
+ * @param {Constructor<M>} clazz - The model constructor
+ * @class CouchDBPaginator
+ * @example
+ * // Example of using CouchDBPaginator
+ * const adapter = new MyCouchDBAdapter(scope);
+ * const query = { selector: { type: "user" } };
+ * const paginator = new CouchDBPaginator(adapter, query, 10, User);
+ *
+ * // Get the first page
+ * const page1 = await paginator.page(1);
+ *
+ * // Get the next page
+ * const page2 = await paginator.page(2);
+ */
+export declare class FabricContractPaginator<M extends Model> extends CouchDBPaginator<M> {
+    /**
+     * @description Creates a new CouchDBPaginator instance
+     * @summary Initializes a paginator for CouchDB query results
+     * @param {CouchDBAdapter<any, any, any, any>} adapter - The CouchDB adapter
+     * @param {MangoQuery} query - The Mango query to paginate
+     * @param {number} size - The page size
+     * @param {Constructor<M>} clazz - The model constructor
+     */
+    constructor(adapter: FabricContractAdapter, query: MangoQuery, size: number, clazz: Constructor<M>);
+    /**
+     * @description Prepares a query for pagination
+     * @summary Modifies the raw query to include pagination parameters
+     * @param {MangoQuery} rawStatement - The original Mango query
+     * @return {MangoQuery} The prepared query with pagination parameters
+     */
+    protected prepare(rawStatement: MangoQuery): MangoQuery;
+    /**
+     * @description Retrieves a specific page of results
+     * @summary Executes the query with pagination and processes the results
+     * @param {number} [page=1] - The page number to retrieve
+     * @return {Promise<R[]>} A promise that resolves to an array of results
+     * @throws {PagingError} If trying to access a page other than the first without a bookmark, or if no class is defined
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client
+     *   participant CouchDBPaginator
+     *   participant Adapter
+     *   participant CouchDB
+     *
+     *   Client->>CouchDBPaginator: page(pageNumber)
+     *   Note over CouchDBPaginator: Clone statement
+     *   CouchDBPaginator->>CouchDBPaginator: validatePage(page)
+     *
+     *   alt page !== 1
+     *     CouchDBPaginator->>CouchDBPaginator: Check bookmark
+     *     alt No bookmark
+     *       CouchDBPaginator-->>Client: Throw PagingError
+     *     else Has bookmark
+     *       CouchDBPaginator->>CouchDBPaginator: Add bookmark to statement
+     *     end
+     *   end
+     *
+     *   CouchDBPaginator->>Adapter: raw(statement, false)
+     *   Adapter->>CouchDB: Execute query
+     *   CouchDB-->>Adapter: Return results
+     *   Adapter-->>CouchDBPaginator: Return MangoResponse
+     *
+     *   Note over CouchDBPaginator: Process results
+     *
+     *   alt Has warning
+     *     CouchDBPaginator->>CouchDBPaginator: Log warning
+     *   end
+     *
+     *   CouchDBPaginator->>CouchDBPaginator: Check for clazz
+     *
+     *   alt No clazz
+     *     CouchDBPaginator-->>Client: Throw PagingError
+     *   else Has clazz
+     *     CouchDBPaginator->>CouchDBPaginator: Find primary key
+     *
+     *     alt Has fields in statement
+     *       CouchDBPaginator->>CouchDBPaginator: Use docs directly
+     *     else No fields
+     *       CouchDBPaginator->>CouchDBPaginator: Process each document
+     *       loop For each document
+     *         CouchDBPaginator->>CouchDBPaginator: Extract original ID
+     *         CouchDBPaginator->>Adapter: revert(doc, clazz, pkDef.id, parsedId)
+     *       end
+     *     end
+     *
+     *     CouchDBPaginator->>CouchDBPaginator: Store bookmark
+     *     CouchDBPaginator->>CouchDBPaginator: Update currentPage
+     *     CouchDBPaginator-->>Client: Return results
+     *   end
+     */
+    page(page?: number, bookmark?: any, ...args: MaybeContextualArg<any>): Promise<M[]>;
+}

package/lib/types/contracts/FabricContractPaginator.d.mts

@@ -0,0 +1,105 @@
+import { MaybeContextualArg } from "@decaf-ts/core";
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+import { FabricContractAdapter } from "./ContractAdapter.js";
+import { CouchDBPaginator, MangoQuery } from "@decaf-ts/for-couchdb";
+/**
+ * @description Paginator for CouchDB query results
+ * @summary Implements pagination for CouchDB queries using bookmarks for efficient navigation through result sets
+ * @template M - The model type that extends Model
+ * @template R - The result type
+ * @param {FabricCo<any, any, any>} adapter - The CouchDB adapter
+ * @param {MangoQuery} query - The Mango query to paginate
+ * @param {number} size - The page size
+ * @param {Constructor<M>} clazz - The model constructor
+ * @class CouchDBPaginator
+ * @example
+ * // Example of using CouchDBPaginator
+ * const adapter = new MyCouchDBAdapter(scope);
+ * const query = { selector: { type: "user" } };
+ * const paginator = new CouchDBPaginator(adapter, query, 10, User);
+ *
+ * // Get the first page
+ * const page1 = await paginator.page(1);
+ *
+ * // Get the next page
+ * const page2 = await paginator.page(2);
+ */
+export declare class FabricContractPaginator<M extends Model> extends CouchDBPaginator<M> {
+    /**
+     * @description Creates a new CouchDBPaginator instance
+     * @summary Initializes a paginator for CouchDB query results
+     * @param {CouchDBAdapter<any, any, any, any>} adapter - The CouchDB adapter
+     * @param {MangoQuery} query - The Mango query to paginate
+     * @param {number} size - The page size
+     * @param {Constructor<M>} clazz - The model constructor
+     */
+    constructor(adapter: FabricContractAdapter, query: MangoQuery, size: number, clazz: Constructor<M>);
+    /**
+     * @description Prepares a query for pagination
+     * @summary Modifies the raw query to include pagination parameters
+     * @param {MangoQuery} rawStatement - The original Mango query
+     * @return {MangoQuery} The prepared query with pagination parameters
+     */
+    protected prepare(rawStatement: MangoQuery): MangoQuery;
+    /**
+     * @description Retrieves a specific page of results
+     * @summary Executes the query with pagination and processes the results
+     * @param {number} [page=1] - The page number to retrieve
+     * @return {Promise<R[]>} A promise that resolves to an array of results
+     * @throws {PagingError} If trying to access a page other than the first without a bookmark, or if no class is defined
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client
+     *   participant CouchDBPaginator
+     *   participant Adapter
+     *   participant CouchDB
+     *
+     *   Client->>CouchDBPaginator: page(pageNumber)
+     *   Note over CouchDBPaginator: Clone statement
+     *   CouchDBPaginator->>CouchDBPaginator: validatePage(page)
+     *
+     *   alt page !== 1
+     *     CouchDBPaginator->>CouchDBPaginator: Check bookmark
+     *     alt No bookmark
+     *       CouchDBPaginator-->>Client: Throw PagingError
+     *     else Has bookmark
+     *       CouchDBPaginator->>CouchDBPaginator: Add bookmark to statement
+     *     end
+     *   end
+     *
+     *   CouchDBPaginator->>Adapter: raw(statement, false)
+     *   Adapter->>CouchDB: Execute query
+     *   CouchDB-->>Adapter: Return results
+     *   Adapter-->>CouchDBPaginator: Return MangoResponse
+     *
+     *   Note over CouchDBPaginator: Process results
+     *
+     *   alt Has warning
+     *     CouchDBPaginator->>CouchDBPaginator: Log warning
+     *   end
+     *
+     *   CouchDBPaginator->>CouchDBPaginator: Check for clazz
+     *
+     *   alt No clazz
+     *     CouchDBPaginator-->>Client: Throw PagingError
+     *   else Has clazz
+     *     CouchDBPaginator->>CouchDBPaginator: Find primary key
+     *
+     *     alt Has fields in statement
+     *       CouchDBPaginator->>CouchDBPaginator: Use docs directly
+     *     else No fields
+     *       CouchDBPaginator->>CouchDBPaginator: Process each document
+     *       loop For each document
+     *         CouchDBPaginator->>CouchDBPaginator: Extract original ID
+     *         CouchDBPaginator->>Adapter: revert(doc, clazz, pkDef.id, parsedId)
+     *       end
+     *     end
+     *
+     *     CouchDBPaginator->>CouchDBPaginator: Store bookmark
+     *     CouchDBPaginator->>CouchDBPaginator: Update currentPage
+     *     CouchDBPaginator-->>Client: Return results
+     *   end
+     */
+    page(page?: number, bookmark?: any, ...args: MaybeContextualArg<any>): Promise<M[]>;
+}

package/lib/types/contracts/FabricContractRepository.d.cts

@@ -0,0 +1,119 @@
+import "./overrides";
+import { Repository, ObserverHandler, EventIds, ContextualArgs, MaybeContextualArg, OrderDirection, SerializedPage, DirectionLimitOffset, MethodOrOperation, ContextualizedArgs } from "@decaf-ts/core";
+import { FabricContractContext } from "./ContractContext.cjs";
+import { Model } from "@decaf-ts/decorator-validation";
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { Constructor } from "@decaf-ts/decoration";
+import { FabricContractAdapter } from "./ContractAdapter.cjs";
+import { FabricContractFlags } from "./types.cjs";
+/**
+ * @description Repository for Hyperledger Fabric chaincode models
+ * @summary Provides CRUD operations for models within Fabric chaincode contracts
+ * @template M - Type extending Model
+ * @template MangoQuery - Query type for CouchDB-like queries
+ * @template FabricContractAdapter - Adapter type for Fabric contract operations
+ * @template FabricContractFlags - Flags specific to Fabric contract operations
+ * @template FabricContractContext - Context type for Fabric contract operations
+ *
+ * @param {FabricContractAdapter} [adapter] - The adapter for interacting with the state database
+ * @param {Constructor<M>} [clazz] - The model constructor
+ * @param {Array<OperationKeys | BulkCrudOperationKeys | string>} [trackedEvents] - Events to track for observer notifications
+ *
+ * @class FabricContractRepository
+ * @example
+ * ```typescript
+ * // In a Fabric chaincode contract class
+ * import { FabricContractRepository, FabricContractAdapter } from '@decaf-ts/for-fabric';
+ *
+ * @table('assets')
+ * class Asset extends Model {
+ *   @id()
+ *   id: string;
+ *
+ *   @property()
+ *   data: string;
+ * }
+ *
+ * export class MyContract extends Contract {
+ *   private adapter = new FabricContractAdapter();
+ *   private repository: FabricContractRepository<Asset>;
+ *
+ *   constructor() {
+ *     super('MyContract');
+ *     this.repository = new FabricContractRepository<Asset>(this.adapter, Asset);
+ *   }
+ *
+ *   @Transaction()
+ *   async createAsset(ctx: Context, id: string, data: string): Promise<void> {
+ *     const asset = new Asset();
+ *     asset.id = id;
+ *     asset.data = data;
+ *
+ *     await this.repository.create(asset, { stub: ctx.stub });
+ *   }
+ * }
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Contract
+ *   participant Repository
+ *   participant Adapter
+ *   participant StateDB
+ *
+ *   Contract->>Repository: create(model, ctx)
+ *   Repository->>Adapter: prepare(model, pk)
+ *   Repository->>Adapter: create(tableName, id, record, transient, ctx)
+ *   Adapter->>StateDB: putState(id, serializedData)
+ *   StateDB-->>Adapter: Success
+ *   Adapter-->>Repository: record
+ *   Repository->>Adapter: revert(record, class, pk, id, transient)
+ *   Adapter-->>Repository: model
+ *   Repository-->>Contract: model
+ */
+export declare class FabricContractRepository<M extends Model> extends Repository<M, FabricContractAdapter> {
+    protected omittedEvents?: (OperationKeys | BulkCrudOperationKeys | string)[] | undefined;
+    protected _overrides: Partial<(import("@decaf-ts/db-decorators").ContextFlags<any> & Pick<import("@decaf-ts/db-decorators").RepositoryFlags<any>, "operation" | "correlationId" | "ignoreDevSafeGuards" | "parentContext" | "childContexts"> & {
+        pending?: Record<string, string[]>;
+        transactionLock?: import("@decaf-ts/core").ContextLock;
+    }) | import("@decaf-ts/core").AdapterFlags> & {
+        ignoreValidation: boolean;
+        ignoreHandlers: boolean;
+        allowRawStatements: boolean;
+        forcePrepareSimpleQueries: boolean;
+        forcePrepareComplexQueries: boolean;
+        rebuildWithTransient: boolean;
+    };
+    constructor(adapter?: FabricContractAdapter, clazz?: Constructor<M>, omittedEvents?: (OperationKeys | BulkCrudOperationKeys | string)[] | undefined);
+    create(model: M, ...args: MaybeContextualArg<FabricContractContext>): Promise<M>;
+    createAll(models: M[], ...args: MaybeContextualArg<FabricContractContext>): Promise<M[]>;
+    update(model: M, ...args: MaybeContextualArg<FabricContractContext>): Promise<M>;
+    updateAll(models: M[], ...args: MaybeContextualArg<FabricContractContext>): Promise<M[]>;
+    listBy(key: keyof M, order: OrderDirection, ...args: MaybeContextualArg<FabricContractContext>): Promise<M[]>;
+    paginateBy(key: keyof M, order: OrderDirection, ref?: Omit<DirectionLimitOffset, "direction">, ...args: MaybeContextualArg<FabricContractContext>): Promise<SerializedPage<M>>;
+    statement(name: string, ...args: MaybeContextualArg<FabricContractContext>): Promise<any>;
+    /**
+     * @description Gets the observer handler for this repository
+     * @summary Returns a FabricContractRepositoryObservableHandler instance
+     * @return {ObserverHandler} The observer handler
+     */
+    ObserverHandler(): ObserverHandler;
+    /**
+     * @description Updates observers based on tracked events
+     * @summary Filters events based on trackedEvents and delegates to the parent method
+     * @param {string} table - The table/collection name
+     * @param {OperationKeys | BulkCrudOperationKeys | string} event - The event type
+     * @param {EventIds} id - The event identifier
+     * @param {FabricContractContext} ctx - The Fabric contract context
+     * @param {...any[]} args - Additional arguments
+     * @return {Promise<void>} Promise that resolves when observers are updated
+     */
+    updateObservers(table: Constructor<M> | string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: ContextualArgs<FabricContractContext>): Promise<void>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD): ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: false): ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: true): Promise<ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: true, overrides?: Partial<FabricContractFlags>): Promise<ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: false, overrides?: Partial<FabricContractFlags>): ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>;
+    private cleanContextualizedArgs;
+    private applyCleanContext;
+    private cleanContext;
+}

package/lib/types/contracts/FabricContractRepository.d.mts

@@ -0,0 +1,119 @@
+import "./overrides";
+import { Repository, ObserverHandler, EventIds, ContextualArgs, MaybeContextualArg, OrderDirection, SerializedPage, DirectionLimitOffset, MethodOrOperation, ContextualizedArgs } from "@decaf-ts/core";
+import { FabricContractContext } from "./ContractContext.js";
+import { Model } from "@decaf-ts/decorator-validation";
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { Constructor } from "@decaf-ts/decoration";
+import { FabricContractAdapter } from "./ContractAdapter.js";
+import { FabricContractFlags } from "./types.js";
+/**
+ * @description Repository for Hyperledger Fabric chaincode models
+ * @summary Provides CRUD operations for models within Fabric chaincode contracts
+ * @template M - Type extending Model
+ * @template MangoQuery - Query type for CouchDB-like queries
+ * @template FabricContractAdapter - Adapter type for Fabric contract operations
+ * @template FabricContractFlags - Flags specific to Fabric contract operations
+ * @template FabricContractContext - Context type for Fabric contract operations
+ *
+ * @param {FabricContractAdapter} [adapter] - The adapter for interacting with the state database
+ * @param {Constructor<M>} [clazz] - The model constructor
+ * @param {Array<OperationKeys | BulkCrudOperationKeys | string>} [trackedEvents] - Events to track for observer notifications
+ *
+ * @class FabricContractRepository
+ * @example
+ * ```typescript
+ * // In a Fabric chaincode contract class
+ * import { FabricContractRepository, FabricContractAdapter } from '@decaf-ts/for-fabric';
+ *
+ * @table('assets')
+ * class Asset extends Model {
+ *   @id()
+ *   id: string;
+ *
+ *   @property()
+ *   data: string;
+ * }
+ *
+ * export class MyContract extends Contract {
+ *   private adapter = new FabricContractAdapter();
+ *   private repository: FabricContractRepository<Asset>;
+ *
+ *   constructor() {
+ *     super('MyContract');
+ *     this.repository = new FabricContractRepository<Asset>(this.adapter, Asset);
+ *   }
+ *
+ *   @Transaction()
+ *   async createAsset(ctx: Context, id: string, data: string): Promise<void> {
+ *     const asset = new Asset();
+ *     asset.id = id;
+ *     asset.data = data;
+ *
+ *     await this.repository.create(asset, { stub: ctx.stub });
+ *   }
+ * }
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Contract
+ *   participant Repository
+ *   participant Adapter
+ *   participant StateDB
+ *
+ *   Contract->>Repository: create(model, ctx)
+ *   Repository->>Adapter: prepare(model, pk)
+ *   Repository->>Adapter: create(tableName, id, record, transient, ctx)
+ *   Adapter->>StateDB: putState(id, serializedData)
+ *   StateDB-->>Adapter: Success
+ *   Adapter-->>Repository: record
+ *   Repository->>Adapter: revert(record, class, pk, id, transient)
+ *   Adapter-->>Repository: model
+ *   Repository-->>Contract: model
+ */
+export declare class FabricContractRepository<M extends Model> extends Repository<M, FabricContractAdapter> {
+    protected omittedEvents?: (OperationKeys | BulkCrudOperationKeys | string)[] | undefined;
+    protected _overrides: Partial<(import("@decaf-ts/db-decorators").ContextFlags<any> & Pick<import("@decaf-ts/db-decorators").RepositoryFlags<any>, "operation" | "correlationId" | "ignoreDevSafeGuards" | "parentContext" | "childContexts"> & {
+        pending?: Record<string, string[]>;
+        transactionLock?: import("@decaf-ts/core").ContextLock;
+    }) | import("@decaf-ts/core").AdapterFlags> & {
+        ignoreValidation: boolean;
+        ignoreHandlers: boolean;
+        allowRawStatements: boolean;
+        forcePrepareSimpleQueries: boolean;
+        forcePrepareComplexQueries: boolean;
+        rebuildWithTransient: boolean;
+    };
+    constructor(adapter?: FabricContractAdapter, clazz?: Constructor<M>, omittedEvents?: (OperationKeys | BulkCrudOperationKeys | string)[] | undefined);
+    create(model: M, ...args: MaybeContextualArg<FabricContractContext>): Promise<M>;
+    createAll(models: M[], ...args: MaybeContextualArg<FabricContractContext>): Promise<M[]>;
+    update(model: M, ...args: MaybeContextualArg<FabricContractContext>): Promise<M>;
+    updateAll(models: M[], ...args: MaybeContextualArg<FabricContractContext>): Promise<M[]>;
+    listBy(key: keyof M, order: OrderDirection, ...args: MaybeContextualArg<FabricContractContext>): Promise<M[]>;
+    paginateBy(key: keyof M, order: OrderDirection, ref?: Omit<DirectionLimitOffset, "direction">, ...args: MaybeContextualArg<FabricContractContext>): Promise<SerializedPage<M>>;
+    statement(name: string, ...args: MaybeContextualArg<FabricContractContext>): Promise<any>;
+    /**
+     * @description Gets the observer handler for this repository
+     * @summary Returns a FabricContractRepositoryObservableHandler instance
+     * @return {ObserverHandler} The observer handler
+     */
+    ObserverHandler(): ObserverHandler;
+    /**
+     * @description Updates observers based on tracked events
+     * @summary Filters events based on trackedEvents and delegates to the parent method
+     * @param {string} table - The table/collection name
+     * @param {OperationKeys | BulkCrudOperationKeys | string} event - The event type
+     * @param {EventIds} id - The event identifier
+     * @param {FabricContractContext} ctx - The Fabric contract context
+     * @param {...any[]} args - Additional arguments
+     * @return {Promise<void>} Promise that resolves when observers are updated
+     */
+    updateObservers(table: Constructor<M> | string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: ContextualArgs<FabricContractContext>): Promise<void>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD): ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: false): ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: true): Promise<ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: true, overrides?: Partial<FabricContractFlags>): Promise<ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: false, overrides?: Partial<FabricContractFlags>): ContextualizedArgs<FabricContractContext, ARGS, METHOD extends string ? true : false>;
+    private cleanContextualizedArgs;
+    private applyCleanContext;
+    private cleanContext;
+}