@algorandfoundation/algokit-utils 9.0.2-beta.1 → 9.1.0-beta.1

package/types/composer.d.ts

@@ -416,6 +416,13 @@ export type Txn = (PaymentParams & {
 } | ((AppCallMethodCall | AppCreateMethodCall | AppUpdateMethodCall) & {
     type: 'methodCall';
 });
+/**
+ * A function that transforms an error into a new error.
+ *
+ * In most cases, an ErrorTransformer should first check if it can or should transform the error
+ * and return the input error if it cannot or should not transform it.
+ */
+export type ErrorTransformer = (error: Error) => Promise<Error>;
 /** Parameters to create an `TransactionComposer`. */
 export type TransactionComposerParams = {
     /** The algod client to use to get suggestedParams and send the transaction group */
@@ -430,9 +437,14 @@ export type TransactionComposerParams = {
     defaultValidityWindow?: bigint;
     /** An existing `AppManager` to use to manage app compilation and cache compilation results.
      *
-     * If not specified than an ephemeral one will be created.
+     * If not specified then an ephemeral one will be created.
      */
     appManager?: AppManager;
+    /**
+     * An array of error transformers to use when an error is caught in simulate or execute
+     * callbacks can later be registered with `registerErrorTransformer`
+     */
+    errorTransformers?: ErrorTransformer[];
 };
 /** Set of transactions built by `TransactionComposer`. */
 export interface BuiltTransactions {
@@ -466,12 +478,20 @@ export declare class TransactionComposer {
     /** Whether the validity window was explicitly set on construction */
     private defaultValidityWindowIsExplicit;
     private appManager;
+    private errorTransformers;
+    private transformError;
     /**
      * Create a `TransactionComposer`.
      * @param params The configuration for this composer
      * @returns The `TransactionComposer` instance
      */
     constructor(params: TransactionComposerParams);
+    /**
+     * Register a function that will be used to transform an error caught when simulating or executing
+     *
+     * @returns The composer so you can chain method calls
+     */
+    registerErrorTransformer(transformer: ErrorTransformer): this;
     /**
      * Add a pre-built transaction to the transaction group.
      * @param transaction The pre-built transaction

package/types/composer.js

@@ -15,8 +15,37 @@ const address = (address) => {
     return typeof address === 'string' ? algosdk.Address.fromString(address) : address;
 };
 const MAX_TRANSACTION_GROUP_SIZE = 16;
+class InvalidErrorTransformerValue extends Error {
+    constructor(originalError, value) {
+        super(`An error transformer returned a non-error value: ${value}. The original error before any transformation: ${originalError}`);
+    }
+}
+class ErrorTransformerError extends Error {
+    constructor(originalError, cause) {
+        super(`An error transformer threw an error: ${cause}. The original error before any transformation: ${originalError} `, { cause });
+    }
+}
 /** TransactionComposer helps you compose and execute transactions as a transaction group. */
 class TransactionComposer {
+    async transformError(originalError) {
+        // Transformers only work with Error instances, so immediately return anything else
+        if (!(originalError instanceof Error)) {
+            return originalError;
+        }
+        let transformedError = originalError;
+        for (const transformer of this.errorTransformers) {
+            try {
+                transformedError = await transformer(transformedError);
+                if (!(transformedError instanceof Error)) {
+                    return new InvalidErrorTransformerValue(originalError, transformedError);
+                }
+            }
+            catch (errorFromTransformer) {
+                return new ErrorTransformerError(originalError, errorFromTransformer);
+            }
+        }
+        return transformedError;
+    }
     /**
      * Create a `TransactionComposer`.
      * @param params The configuration for this composer
@@ -42,6 +71,16 @@ class TransactionComposer {
         this.defaultValidityWindow = params.defaultValidityWindow ?? this.defaultValidityWindow;
         this.defaultValidityWindowIsExplicit = params.defaultValidityWindow !== undefined;
         this.appManager = params.appManager ?? new types_appManager.AppManager(params.algod);
+        this.errorTransformers = params.errorTransformers ?? [];
+    }
+    /**
+     * Register a function that will be used to transform an error caught when simulating or executing
+     *
+     * @returns The composer so you can chain method calls
+     */
+    registerErrorTransformer(transformer) {
+        this.errorTransformers.push(transformer);
+        return this;
     }
     /**
      * Add a pre-built transaction to the transaction group.
@@ -1311,19 +1350,24 @@ class TransactionComposer {
             const { firstValid: firstRound } = suggestedParams;
             waitRounds = Number(BigInt(lastRound) - BigInt(firstRound)) + 1;
         }
-        return await transaction.sendAtomicTransactionComposer({
-            atc: this.atc,
-            suppressLog: params?.suppressLog,
-            maxRoundsToWaitForConfirmation: waitRounds,
-            populateAppCallResources: params?.populateAppCallResources,
-            coverAppCallInnerTransactionFees: params?.coverAppCallInnerTransactionFees,
-            additionalAtcContext: params?.coverAppCallInnerTransactionFees
-                ? {
-                    maxFees: this.txnMaxFees,
-                    suggestedParams: suggestedParams,
-                }
-                : undefined,
-        }, this.algod);
+        try {
+            return await transaction.sendAtomicTransactionComposer({
+                atc: this.atc,
+                suppressLog: params?.suppressLog,
+                maxRoundsToWaitForConfirmation: waitRounds,
+                populateAppCallResources: params?.populateAppCallResources,
+                coverAppCallInnerTransactionFees: params?.coverAppCallInnerTransactionFees,
+                additionalAtcContext: params?.coverAppCallInnerTransactionFees
+                    ? {
+                        maxFees: this.txnMaxFees,
+                        suggestedParams: suggestedParams,
+                    }
+                    : undefined,
+            }, this.algod);
+        }
+        catch (originalError) {
+            throw await this.transformError(originalError);
+        }
     }
     /**
      * @deprecated Use `send` instead.
@@ -1379,8 +1423,7 @@ class TransactionComposer {
             if (config.Config.debug) {
                 await config.Config.events.emitAsync(types_lifecycleEvents.EventType.TxnGroupSimulated, { simulateResponse });
             }
-            error.simulateResponse = simulateResponse;
-            throw error;
+            throw await this.transformError(error);
         }
         if (config.Config.debug && config.Config.traceAll) {
             await config.Config.events.emitAsync(types_lifecycleEvents.EventType.TxnGroupSimulated, { simulateResponse });