@acmekit/orchestration 2.13.1

package/dist/transaction/transaction-orchestrator.d.ts

@@ -0,0 +1,207 @@
+import { DistributedTransactionType } from "./distributed-transaction";
+import { TransactionStep, TransactionStepHandler } from "./transaction-step";
+import { StepFeatures, TransactionFlow, TransactionModelOptions, TransactionOptions, TransactionStepsDefinition } from "./types";
+import { Context } from "@acmekit/types";
+import { EventEmitter } from "events";
+/**
+ * @class TransactionOrchestrator is responsible for managing and executing distributed transactions.
+ * It is based on a single transaction definition, which is used to execute all the transaction steps
+ */
+export declare class TransactionOrchestrator extends EventEmitter {
+    id: string;
+    private static ROOT_STEP;
+    static DEFAULT_TTL: number;
+    private invokeSteps;
+    private compensateSteps;
+    private definition;
+    private options?;
+    static DEFAULT_RETRIES: number;
+    private static workflowOptions;
+    static getWorkflowOptions(modelId: string): TransactionOptions;
+    /**
+     * Trace workflow transaction for instrumentation
+     */
+    static traceTransaction?: (transactionResume: (...args: any[]) => Promise<void>, metadata: {
+        model_id: string;
+        transaction_id: string;
+        flow_metadata: TransactionFlow["metadata"];
+    }) => Promise<any>;
+    /**
+     * Trace workflow steps for instrumentation
+     */
+    static traceStep?: (handler: (...args: any[]) => Promise<any>, metadata: {
+        action: string;
+        type: "invoke" | "compensate";
+        step_id: string;
+        step_uuid: string;
+        attempts: number;
+        failures: number;
+        async: boolean;
+        idempotency_key: string;
+    }) => Promise<any>;
+    constructor({ id, definition, options, isClone, }: {
+        id: string;
+        definition: TransactionStepsDefinition;
+        options?: TransactionModelOptions;
+        isClone?: boolean;
+    });
+    static isExpectedError(error: Error): boolean;
+    static clone(orchestrator: TransactionOrchestrator): TransactionOrchestrator;
+    private static SEPARATOR;
+    static getKeyName(...params: string[]): string;
+    private static getPreviousStep;
+    getOptions(): TransactionModelOptions;
+    private getInvokeSteps;
+    private getCompensationSteps;
+    private static countSiblings;
+    private canMoveForward;
+    private canMoveBackward;
+    private canContinue;
+    private hasExpired;
+    private checkTransactionTimeout;
+    private checkStepTimeout;
+    private checkAllSteps;
+    private computeCurrentTransactionState;
+    private flagStepsToRevert;
+    private static setStepSuccess;
+    private static retryStep;
+    private static skipStep;
+    private static setStepTimeout;
+    private static setStepFailure;
+    private executeNext;
+    /**
+     * Finalize the transaction when all steps are complete
+     */
+    private finalizeTransaction;
+    /**
+     * Prepare a step for execution by setting state and incrementing attempts
+     */
+    private prepareStepForExecution;
+    /**
+     * Create the payload for a step execution
+     */
+    private createStepPayload;
+    /**
+     * Prepare handler arguments for step execution
+     */
+    private prepareHandlerArgs;
+    /**
+     * Create the step execution promise with optional tracing
+     */
+    private createStepExecutionPromise;
+    /**
+     * Execute a synchronous step and handle its result
+     */
+    private executeSyncStep;
+    /**
+     * Execute an asynchronous step and handle its result
+     */
+    private executeAsyncStep;
+    /**
+     * Check if step or transaction has expired and handle timeouts
+     */
+    private handleStepExpiration;
+    /**
+     * Handle successful step completion
+     */
+    private handleStepSuccess;
+    /**
+     * Handle step failure
+     */
+    private handleStepFailure;
+    /**
+     * Start a new transaction or resume a transaction that has been previously started
+     * @param transaction - The transaction to resume
+     */
+    resume(transaction: DistributedTransactionType): Promise<void>;
+    /**
+     * Cancel and revert a transaction compensating all its executed steps. It can be an ongoing transaction or a completed one
+     * @param transaction - The transaction to be reverted
+     */
+    cancelTransaction(transaction: DistributedTransactionType, options?: {
+        preventExecuteNext?: boolean;
+    }): Promise<void>;
+    private parseFlowOptions;
+    private createTransactionFlow;
+    private static loadTransactionById;
+    static buildSteps(flow: TransactionStepsDefinition, existingSteps?: {
+        [key: string]: TransactionStep;
+    }): [{
+        [key: string]: TransactionStep;
+    }, StepFeatures];
+    /** Create a new transaction
+     * @param transactionId - unique identifier of the transaction
+     * @param handler - function to handle action of the transaction
+     * @param payload - payload to be passed to all the transaction steps
+     * @param flowMetadata - flow metadata which can include event group id for example
+     */
+    beginTransaction({ transactionId, handler, payload, flowMetadata, context, onLoad, }: {
+        transactionId: string;
+        handler: TransactionStepHandler;
+        payload?: unknown;
+        flowMetadata?: TransactionFlow["metadata"];
+        context?: Context;
+        onLoad?: (transaction: DistributedTransactionType) => Promise<void> | void;
+    }): Promise<DistributedTransactionType>;
+    /** Returns an existing transaction
+     * @param transactionId - unique identifier of the transaction
+     * @param handler - function to handle action of the transaction
+     */
+    retrieveExistingTransaction(transactionId: string, handler: TransactionStepHandler, options?: {
+        isCancelling?: boolean;
+    }): Promise<DistributedTransactionType>;
+    private static getStepByAction;
+    private static getTransactionAndStepFromIdempotencyKey;
+    /** Skip the execution of a specific transaction and step
+     * @param responseIdempotencyKey - The idempotency key for the step
+     * @param handler - The handler function to execute the step
+     * @param transaction - The current transaction. If not provided it will be loaded based on the responseIdempotencyKey
+     */
+    skipStep({ responseIdempotencyKey, handler, transaction, }: {
+        responseIdempotencyKey: string;
+        handler?: TransactionStepHandler;
+        transaction?: DistributedTransactionType;
+    }): Promise<DistributedTransactionType>;
+    /**
+     * Manually force a step to retry even if it is still in awaiting status
+     * @param responseIdempotencyKey - The idempotency key for the step
+     * @param handler - The handler function to execute the step
+     * @param transaction - The current transaction. If not provided it will be loaded based on the responseIdempotencyKey
+     */
+    retryStep({ responseIdempotencyKey, handler, transaction, onLoad, }: {
+        responseIdempotencyKey: string;
+        handler?: TransactionStepHandler;
+        transaction?: DistributedTransactionType;
+        onLoad?: (transaction: DistributedTransactionType) => Promise<void> | void;
+    }): Promise<DistributedTransactionType>;
+    /** Register a step success for a specific transaction and step
+     * @param responseIdempotencyKey - The idempotency key for the step
+     * @param handler - The handler function to execute the step
+     * @param transaction - The current transaction. If not provided it will be loaded based on the responseIdempotencyKey
+     * @param response - The response of the step
+     */
+    registerStepSuccess({ responseIdempotencyKey, handler, transaction, response, onLoad, }: {
+        responseIdempotencyKey: string;
+        handler?: TransactionStepHandler;
+        transaction?: DistributedTransactionType;
+        response?: unknown;
+        onLoad?: (transaction: DistributedTransactionType) => Promise<void> | void;
+    }): Promise<DistributedTransactionType>;
+    /**
+     * Register a step failure for a specific transaction and step
+     * @param responseIdempotencyKey - The idempotency key for the step
+     * @param error - The error that caused the failure
+     * @param handler - The handler function to execute the step
+     * @param transaction - The current transaction
+     * @param response - The response of the step
+     */
+    registerStepFailure({ responseIdempotencyKey, error, handler, transaction, onLoad, forcePermanentFailure, }: {
+        responseIdempotencyKey: string;
+        error?: Error | any;
+        handler?: TransactionStepHandler;
+        transaction?: DistributedTransactionType;
+        onLoad?: (transaction: DistributedTransactionType) => Promise<void> | void;
+        forcePermanentFailure?: boolean;
+    }): Promise<DistributedTransactionType>;
+}
+//# sourceMappingURL=transaction-orchestrator.d.ts.map

package/dist/transaction/transaction-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-orchestrator.d.ts","sourceRoot":"","sources":["../../src/transaction/transaction-orchestrator.ts"],"names":[],"mappings":"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"}