@decaf-ts/for-fabric 0.9.0 → 0.11.0

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

@@ -0,0 +1,62 @@
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { ContextualArgs, EventIds, ObserverHandler } from "@decaf-ts/core";
+import { FabricContractContext } from "./ContractContext.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Observer handler for Fabric chaincode events
+ * @summary Emits events on the Fabric ledger when repository operations occur
+ * @class FabricContractRepositoryObservableHandler
+ * @extends {ObserverHandler}
+ * @example
+ * ```typescript
+ * // In a Fabric chaincode contract
+ * import { FabricContractRepositoryObservableHandler } from '@decaf-ts/for-fabric';
+ *
+ * // Create a handler with default supported events
+ * const handler = new FabricContractRepositoryObservableHandler();
+ *
+ * // Emit an event
+ * await handler.updateObservers(
+ *   logger,
+ *   'assets',
+ *   OperationKeys.CREATE,
+ *   'asset1',
+ *   context
+ * );
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Repository
+ *   participant ObservableHandler
+ *   participant Stub
+ *   participant Ledger
+ *
+ *   Repository->>ObservableHandler: updateObservers(log, table, event, id, ctx)
+ *   ObservableHandler->>ObservableHandler: Check if event is supported
+ *   ObservableHandler->>ObservableHandler: generateFabricEventName(table, event, owner)
+ *   ObservableHandler->>Stub: setEvent(eventName, payload)
+ *   Stub->>Ledger: Record event
+ */
+export declare class FabricContractRepositoryObservableHandler extends ObserverHandler {
+    private supportedEvents;
+    /**
+     * @description Creates a new FabricContractRepositoryObservableHandler instance
+     * @summary Initializes the handler with a list of supported events
+     * @param {Array<OperationKeys | BulkCrudOperationKeys | string>} [supportedEvents] - Events that will trigger Fabric events
+     */
+    constructor(supportedEvents?: (OperationKeys | BulkCrudOperationKeys | string)[]);
+    /**
+     * @description Updates observers by emitting Fabric events
+     * @summary Emits events on the Fabric ledger for supported event types
+     * @param {Logger} log - Logger instance for debugging
+     * @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 {string} [owner] - Optional owner identifier for the event
+     * @param {object | string | undefined} [owner] - Optional payload for the event
+     *
+     * @return {Promise<void>} Promise that resolves when the event is emitted
+     */
+    updateObservers(clazz: string | Constructor<any>, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: ContextualArgs<FabricContractContext>): Promise<void>;
+}

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

@@ -0,0 +1,62 @@
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { ContextualArgs, EventIds, ObserverHandler } from "@decaf-ts/core";
+import { FabricContractContext } from "./ContractContext.js";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Observer handler for Fabric chaincode events
+ * @summary Emits events on the Fabric ledger when repository operations occur
+ * @class FabricContractRepositoryObservableHandler
+ * @extends {ObserverHandler}
+ * @example
+ * ```typescript
+ * // In a Fabric chaincode contract
+ * import { FabricContractRepositoryObservableHandler } from '@decaf-ts/for-fabric';
+ *
+ * // Create a handler with default supported events
+ * const handler = new FabricContractRepositoryObservableHandler();
+ *
+ * // Emit an event
+ * await handler.updateObservers(
+ *   logger,
+ *   'assets',
+ *   OperationKeys.CREATE,
+ *   'asset1',
+ *   context
+ * );
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Repository
+ *   participant ObservableHandler
+ *   participant Stub
+ *   participant Ledger
+ *
+ *   Repository->>ObservableHandler: updateObservers(log, table, event, id, ctx)
+ *   ObservableHandler->>ObservableHandler: Check if event is supported
+ *   ObservableHandler->>ObservableHandler: generateFabricEventName(table, event, owner)
+ *   ObservableHandler->>Stub: setEvent(eventName, payload)
+ *   Stub->>Ledger: Record event
+ */
+export declare class FabricContractRepositoryObservableHandler extends ObserverHandler {
+    private supportedEvents;
+    /**
+     * @description Creates a new FabricContractRepositoryObservableHandler instance
+     * @summary Initializes the handler with a list of supported events
+     * @param {Array<OperationKeys | BulkCrudOperationKeys | string>} [supportedEvents] - Events that will trigger Fabric events
+     */
+    constructor(supportedEvents?: (OperationKeys | BulkCrudOperationKeys | string)[]);
+    /**
+     * @description Updates observers by emitting Fabric events
+     * @summary Emits events on the Fabric ledger for supported event types
+     * @param {Logger} log - Logger instance for debugging
+     * @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 {string} [owner] - Optional owner identifier for the event
+     * @param {object | string | undefined} [owner] - Optional payload for the event
+     *
+     * @return {Promise<void>} Promise that resolves when the event is emitted
+     */
+    updateObservers(clazz: string | Constructor<any>, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: ContextualArgs<FabricContractContext>): Promise<void>;
+}

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

@@ -0,0 +1,87 @@
+import { Adapter, Context, MaybeContextualArg, Sequence, SequenceOptions } from "@decaf-ts/core";
+/**
+ * @description Abstract base class for sequence generation
+ * @summary Provides a framework for generating sequential values (like primary keys) in the persistence layer.
+ * Implementations of this class handle the specifics of how sequences are stored and incremented in different
+ * database systems.
+ * @param {SequenceOptions} options - Configuration options for the sequence generator
+ * @class Sequence
+ * @example
+ * ```typescript
+ * // Example implementation for a specific database
+ * class PostgresSequence extends Sequence {
+ *   constructor(options: SequenceOptions) {
+ *     super(options);
+ *   }
+ *
+ *   async next(): Promise<number> {
+ *     // Implementation to get next value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT nextval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].nextval);
+ *   }
+ *
+ *   async current(): Promise<number> {
+ *     // Implementation to get current value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT currval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].currval);
+ *   }
+ *
+ *   async range(count: number): Promise<number[]> {
+ *     // Implementation to get a range of values
+ *     const values: number[] = [];
+ *     for (let i = 0; i < count; i++) {
+ *       values.push(await this.next());
+ *     }
+ *     return values;
+ *   }
+ * }
+ *
+ * // Usage
+ * const sequence = new PostgresSequence({
+ *   name: 'user_id_seq',
+ *   executor: dbExecutor
+ * });
+ *
+ * const nextId = await sequence.next();
+ * ```
+ */
+export declare class FabricContractSequence extends Sequence {
+    /**
+     * @description Creates a new sequence instance
+     * @summary Protected constructor that initializes the sequence with the provided options
+     */
+    constructor(options: SequenceOptions, adapter: Adapter<any, any, any>);
+    /**
+     * @description Retrieves the current value of the sequence
+     * @summary Gets the current value of the sequence from storage. If the sequence
+     * doesn't exist yet, it returns the configured starting value.
+     * @return A promise that resolves to the current sequence value
+     */
+    current(...args: MaybeContextualArg<any>): Promise<string | number | bigint>;
+    /**
+     * @description Increments the sequence value
+     * @summary Increases the current sequence value by the specified amount and persists
+     * the new value to storage. This method handles both numeric and BigInt sequence types.
+     * @param {string | number | bigint} current - The current value of the sequence
+     * @param {number} [count] - Optional amount to increment by, defaults to the sequence's incrementBy value
+     * @return A promise that resolves to the new sequence value after incrementing
+     */
+    protected increment(count: number | undefined, ctx: Context<any>): Promise<string | number | bigint>;
+    /**
+     * @description Ensures the sequence exists and is at least a given value
+     * @summary Fabric needs to respect segregated/private/shared storage rules when creating
+     * sequences (for example for persistent @version(true) and @sequence()).
+     */
+    ensureAtLeast(value: string | number | bigint, ...args: MaybeContextualArg<any>): Promise<string | number | bigint>;
+    /**
+     * @description Replicates the sequence to all segregated collections
+     * @summary When a model uses privateData or sharedData decorators, its sequence must be
+     * replicated to all collections the model is stored in. This ensures clients with access
+     * to only one collection can still read the model's sequence, while clients without
+     * access to any collection won't see the sequence on the public chain.
+     * @param {Context<any>} ctx - The execution context
+     * @param {SequenceModel} seq - The sequence model to replicate
+     */
+    private writeSequenceToCollections;
+    private replicateToSegregatedCollections;
+}

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

@@ -0,0 +1,87 @@
+import { Adapter, Context, MaybeContextualArg, Sequence, SequenceOptions } from "@decaf-ts/core";
+/**
+ * @description Abstract base class for sequence generation
+ * @summary Provides a framework for generating sequential values (like primary keys) in the persistence layer.
+ * Implementations of this class handle the specifics of how sequences are stored and incremented in different
+ * database systems.
+ * @param {SequenceOptions} options - Configuration options for the sequence generator
+ * @class Sequence
+ * @example
+ * ```typescript
+ * // Example implementation for a specific database
+ * class PostgresSequence extends Sequence {
+ *   constructor(options: SequenceOptions) {
+ *     super(options);
+ *   }
+ *
+ *   async next(): Promise<number> {
+ *     // Implementation to get next value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT nextval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].nextval);
+ *   }
+ *
+ *   async current(): Promise<number> {
+ *     // Implementation to get current value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT currval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].currval);
+ *   }
+ *
+ *   async range(count: number): Promise<number[]> {
+ *     // Implementation to get a range of values
+ *     const values: number[] = [];
+ *     for (let i = 0; i < count; i++) {
+ *       values.push(await this.next());
+ *     }
+ *     return values;
+ *   }
+ * }
+ *
+ * // Usage
+ * const sequence = new PostgresSequence({
+ *   name: 'user_id_seq',
+ *   executor: dbExecutor
+ * });
+ *
+ * const nextId = await sequence.next();
+ * ```
+ */
+export declare class FabricContractSequence extends Sequence {
+    /**
+     * @description Creates a new sequence instance
+     * @summary Protected constructor that initializes the sequence with the provided options
+     */
+    constructor(options: SequenceOptions, adapter: Adapter<any, any, any>);
+    /**
+     * @description Retrieves the current value of the sequence
+     * @summary Gets the current value of the sequence from storage. If the sequence
+     * doesn't exist yet, it returns the configured starting value.
+     * @return A promise that resolves to the current sequence value
+     */
+    current(...args: MaybeContextualArg<any>): Promise<string | number | bigint>;
+    /**
+     * @description Increments the sequence value
+     * @summary Increases the current sequence value by the specified amount and persists
+     * the new value to storage. This method handles both numeric and BigInt sequence types.
+     * @param {string | number | bigint} current - The current value of the sequence
+     * @param {number} [count] - Optional amount to increment by, defaults to the sequence's incrementBy value
+     * @return A promise that resolves to the new sequence value after incrementing
+     */
+    protected increment(count: number | undefined, ctx: Context<any>): Promise<string | number | bigint>;
+    /**
+     * @description Ensures the sequence exists and is at least a given value
+     * @summary Fabric needs to respect segregated/private/shared storage rules when creating
+     * sequences (for example for persistent @version(true) and @sequence()).
+     */
+    ensureAtLeast(value: string | number | bigint, ...args: MaybeContextualArg<any>): Promise<string | number | bigint>;
+    /**
+     * @description Replicates the sequence to all segregated collections
+     * @summary When a model uses privateData or sharedData decorators, its sequence must be
+     * replicated to all collections the model is stored in. This ensures clients with access
+     * to only one collection can still read the model's sequence, while clients without
+     * access to any collection won't see the sequence on the public chain.
+     * @param {Context<any>} ctx - The execution context
+     * @param {SequenceModel} seq - The sequence model to replicate
+     */
+    private writeSequenceToCollections;
+    private replicateToSegregatedCollections;
+}

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

@@ -0,0 +1,36 @@
+import { CouchDBAdapter, MangoQuery } from "@decaf-ts/for-couchdb";
+import { Model } from "@decaf-ts/decorator-validation";
+import { FabricContractContext } from "./ContractContext.cjs";
+import { CouchDBStatement } from "@decaf-ts/for-couchdb";
+import { AdapterFlags, MaybeContextualArg } from "@decaf-ts/core";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Statement wrapper for executing Mango queries within Fabric contracts
+ * @summary Bridges CouchDB-style queries to Fabric via the FabricContractAdapter, handling identity and primary key projection when needed.
+ * @template M - Model type this statement operates on
+ * @template R - Result type returned by the statement
+ * @param {FabricContractAdapter} adapter - The Fabric contract adapter used for raw execution
+ * @param {FabricContractContext} ctx - The Fabric contract context carrying stub and identity
+ * @return {void}
+ * @class FabricStatement
+ * @example
+ * const stmt = new FabricStatement<MyModel, MyModel[]>(adapter, ctx);
+ * const result = await stmt.raw<MyModel[]>({ selector: { type: 'MyModel' } });
+ * @mermaid
+ * sequenceDiagram
+ *   participant App
+ *   participant Statement
+ *   participant Adapter
+ *   participant Ledger
+ *   App->>Statement: raw({ selector })
+ *   Statement->>Adapter: adapter.raw(mango, true, ctx)
+ *   Adapter->>Ledger: Evaluate query
+ *   Adapter-->>Statement: rows
+ *   Statement-->>App: models
+ */
+export declare class FabricStatement<M extends Model, R> extends CouchDBStatement<M, CouchDBAdapter<any, void, FabricContractContext>, R> {
+    constructor(adapter: CouchDBAdapter<any, void, FabricContractContext>, overrides?: Partial<AdapterFlags>);
+    protected executionPrefix(method: any, ...args: MaybeContextualArg<FabricContractContext>): Promise<[Constructor<M>, ...any[], any]>;
+    protected build(): MangoQuery;
+    execute(...args: MaybeContextualArg<FabricContractContext>): Promise<R>;
+}

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

@@ -0,0 +1,36 @@
+import { CouchDBAdapter, MangoQuery } from "@decaf-ts/for-couchdb";
+import { Model } from "@decaf-ts/decorator-validation";
+import { FabricContractContext } from "./ContractContext.js";
+import { CouchDBStatement } from "@decaf-ts/for-couchdb";
+import { AdapterFlags, MaybeContextualArg } from "@decaf-ts/core";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Statement wrapper for executing Mango queries within Fabric contracts
+ * @summary Bridges CouchDB-style queries to Fabric via the FabricContractAdapter, handling identity and primary key projection when needed.
+ * @template M - Model type this statement operates on
+ * @template R - Result type returned by the statement
+ * @param {FabricContractAdapter} adapter - The Fabric contract adapter used for raw execution
+ * @param {FabricContractContext} ctx - The Fabric contract context carrying stub and identity
+ * @return {void}
+ * @class FabricStatement
+ * @example
+ * const stmt = new FabricStatement<MyModel, MyModel[]>(adapter, ctx);
+ * const result = await stmt.raw<MyModel[]>({ selector: { type: 'MyModel' } });
+ * @mermaid
+ * sequenceDiagram
+ *   participant App
+ *   participant Statement
+ *   participant Adapter
+ *   participant Ledger
+ *   App->>Statement: raw({ selector })
+ *   Statement->>Adapter: adapter.raw(mango, true, ctx)
+ *   Adapter->>Ledger: Evaluate query
+ *   Adapter-->>Statement: rows
+ *   Statement-->>App: models
+ */
+export declare class FabricStatement<M extends Model, R> extends CouchDBStatement<M, CouchDBAdapter<any, void, FabricContractContext>, R> {
+    constructor(adapter: CouchDBAdapter<any, void, FabricContractContext>, overrides?: Partial<AdapterFlags>);
+    protected executionPrefix(method: any, ...args: MaybeContextualArg<FabricContractContext>): Promise<[Constructor<M>, ...any[], any]>;
+    protected build(): MangoQuery;
+    execute(...args: MaybeContextualArg<FabricContractContext>): Promise<R>;
+}

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

@@ -0,0 +1,22 @@
+import { Context as Ctx, Contract } from "fabric-contract-api";
+import { MaybeContextualArg, MethodOrOperation } from "@decaf-ts/core";
+import { FabricContextualizedArgs, FabricContractAdapter } from "./ContractAdapter.cjs";
+import { healthcheck } from "../shared/index.cjs";
+import { FabricContractContext } from "./ContractContext.cjs";
+export declare class MigrationContract extends Contract {
+    private _adapter?;
+    protected initialized: boolean;
+    constructor();
+    protected get adapter(): FabricContractAdapter;
+    migrate(context: Ctx, reference: string, migrationArgs?: string): Promise<void>;
+    protected getRegisteredMigrations(context: FabricContractContext): Array<{
+        class: any;
+        reference: string;
+        flavour: string;
+    }>;
+    protected init(ctx: Ctx | FabricContractContext): Promise<void>;
+    healthcheck(ctx: Ctx | FabricContractContext): Promise<string | healthcheck>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD): FabricContextualizedArgs<ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: false): FabricContextualizedArgs<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<FabricContextualizedArgs<ARGS, METHOD extends string ? true : false>>;
+}

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

@@ -0,0 +1,22 @@
+import { Context as Ctx, Contract } from "fabric-contract-api";
+import { MaybeContextualArg, MethodOrOperation } from "@decaf-ts/core";
+import { FabricContextualizedArgs, FabricContractAdapter } from "./ContractAdapter.js";
+import { healthcheck } from "../shared/index.js";
+import { FabricContractContext } from "./ContractContext.js";
+export declare class MigrationContract extends Contract {
+    private _adapter?;
+    protected initialized: boolean;
+    constructor();
+    protected get adapter(): FabricContractAdapter;
+    migrate(context: Ctx, reference: string, migrationArgs?: string): Promise<void>;
+    protected getRegisteredMigrations(context: FabricContractContext): Array<{
+        class: any;
+        reference: string;
+        flavour: string;
+    }>;
+    protected init(ctx: Ctx | FabricContractContext): Promise<void>;
+    healthcheck(ctx: Ctx | FabricContractContext): Promise<string | healthcheck>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD): FabricContextualizedArgs<ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<FabricContractContext, ARGS>, operation: METHOD, allowCreate: false): FabricContextualizedArgs<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<FabricContextualizedArgs<ARGS, METHOD extends string ? true : false>>;
+}

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

@@ -0,0 +1,15 @@
+import { BaseModel } from "@decaf-ts/core";
+import { type ModelArg } from "@decaf-ts/decorator-validation";
+export declare class CustomizableSequence extends BaseModel {
+    /**
+     * @description The unique identifier for the sequence
+     * @summary Primary key for the sequence record
+     */
+    id: string;
+    /**
+     * @description The current value of the sequence
+     * @summary Current sequence value that can be incremented
+     */
+    current: string | number;
+    constructor(seq?: ModelArg<CustomizableSequence>);
+}

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

@@ -0,0 +1,15 @@
+import { BaseModel } from "@decaf-ts/core";
+import { type ModelArg } from "@decaf-ts/decorator-validation";
+export declare class CustomizableSequence extends BaseModel {
+    /**
+     * @description The unique identifier for the sequence
+     * @summary Primary key for the sequence record
+     */
+    id: string;
+    /**
+     * @description The current value of the sequence
+     * @summary Current sequence value that can be incremented
+     */
+    current: string | number;
+    constructor(seq?: ModelArg<CustomizableSequence>);
+}

package/lib/types/contracts/auth/decorators.d.cts

@@ -0,0 +1,6 @@
+import { AuthHandler, AuthorizationError } from "@decaf-ts/core";
+export declare function hlfAllowIf(handler: AuthHandler, ...argz: any[]): (obj: object, propertyKey?: any, descriptor?: any) => void;
+export declare function mspHandler(...args: any[]): AuthorizationError | undefined;
+export declare function namespaceHandler(...args: any[]): AuthorizationError | undefined;
+export declare function onlyMsp(msp: string): (obj: object, propertyKey?: any, descriptor?: any) => void;
+export declare function onlyNamespaceRole(namespace: string, role?: string): (obj: object, propertyKey?: any, descriptor?: any) => void;

package/lib/types/contracts/auth/decorators.d.mts

@@ -0,0 +1,6 @@
+import { AuthHandler, AuthorizationError } from "@decaf-ts/core";
+export declare function hlfAllowIf(handler: AuthHandler, ...argz: any[]): (obj: object, propertyKey?: any, descriptor?: any) => void;
+export declare function mspHandler(...args: any[]): AuthorizationError | undefined;
+export declare function namespaceHandler(...args: any[]): AuthorizationError | undefined;
+export declare function onlyMsp(msp: string): (obj: object, propertyKey?: any, descriptor?: any) => void;
+export declare function onlyNamespaceRole(namespace: string, role?: string): (obj: object, propertyKey?: any, descriptor?: any) => void;

package/lib/types/contracts/auth/index.d.cts

@@ -0,0 +1 @@
+export * from "./decorators.cjs";

package/lib/types/contracts/auth/index.d.mts

@@ -0,0 +1 @@
+export * from "./decorators.js";