chore: deprecate helpers related to InvocationScope (#3920)

Author: Torres-ssf

.changeset/lazy-coins-tease.md

@@ -0,0 +1,5 @@
+---
+"@fuel-ts/program": patch
+---
+
+chore: deprecate helpers related to `InvocationScope`

packages/program/src/contract-call-script.ts

@@ -140,14 +140,19 @@ const scriptResultDecoder = (contractId: Address) => (result: ScriptResult) => {
     });
 };
 
-export const decodeContractCallScriptResult = (
-  callResult: CallResult,
-  contractId: Address,
-  logs: DecodedLogs<any>['logs'] = [],
-  groupedLogs: DecodedLogs<any>['groupedLogs'] = {},
-  abis?: JsonAbisFromAllCalls
-): Uint8Array[] =>
-  decodeCallResult(callResult, scriptResultDecoder(contractId), logs, groupedLogs, abis);
+export const decodeContractCallScriptResult = (params: {
+  callResult: CallResult;
+  contractId: Address;
+  logs?: DecodedLogs<any>['logs'];
+  groupedLogs: DecodedLogs<any>['groupedLogs'];
+  abis?: JsonAbisFromAllCalls;
+}): Uint8Array[] => {
+  const { contractId, ...rest } = params;
+  return decodeCallResult({
+    ...rest,
+    scriptResultDecoder: scriptResultDecoder(contractId),
+  });
+};
 
 const getCallInstructionsLength = (contractCalls: ContractCall[]): number =>
   contractCalls.reduce(

packages/program/src/response.ts

@@ -22,37 +22,103 @@ import type {
 } from './types';
 import { getAbisFromAllCalls, getAllResultLogs } from './utils';
 
-/** @hidden */
-export const extractInvocationResult = <T>(
+export type ExtractInvocationResultParams = {
+  functionScopes: Array<InvocationScopeLike>;
+  receipts: TransactionResultReceipt[];
+  isMultiCall: boolean;
+  logs?: DecodedLogs<unknown>['logs'];
+  groupedLogs?: DecodedLogs<unknown>['groupedLogs'];
+  abis?: JsonAbisFromAllCalls;
+};
+
+/**
+ * Extracts the invocation result from an invocation call.
+ *
+ * @template T - The type of the result to be extracted.
+ * @param functionScopes - An array of invocation scopes.
+ * @param receipts - The transaction result receipts.
+ * @param isMultiCall - A boolean indicating if the call is a multi-call.
+ * @param logs - Optional logs associated with the transaction.
+ * @param groupedLogs - Optional grouped logs associated with the transaction.
+ * @param abis - Optional ABIs associated with the transaction.
+ * @returns The extracted invocation result of type T.
+ *
+ * @deprecated Use the object-based approach for parameters instead.
+ */
+export function extractInvocationResult<T>(
   functionScopes: Array<InvocationScopeLike>,
   receipts: TransactionResultReceipt[],
   isMultiCall: boolean,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  logs: DecodedLogs<any>['logs'],
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  groupedLogs: DecodedLogs<any>['groupedLogs'] = {},
+  logs?: DecodedLogs<unknown>['logs'],
+  groupedLogs?: DecodedLogs<unknown>['groupedLogs'],
   abis?: JsonAbisFromAllCalls
-) => {
+): T;
+
+/**
+ * Extracts the invocation result from a invocation call.
+ *
+ * @template T - The type of the result to be extracted.
+ * @param params - Object of type `ExtractInvocationResultParams` containing extraction parameters
+ */
+export function extractInvocationResult<T>(params: ExtractInvocationResultParams): T;
+
+export function extractInvocationResult<T>(
+  paramsOrFunctionScopes: ExtractInvocationResultParams | Array<InvocationScopeLike>,
+  _receipts?: TransactionResultReceipt[],
+  _isMultiCall?: boolean,
+  _logs?: DecodedLogs<unknown>['logs'],
+  _groupedLogs?: DecodedLogs<unknown>['groupedLogs'],
+  _abis?: JsonAbisFromAllCalls
+): T {
+  let functionScopes: Array<InvocationScopeLike>;
+  let receipts: TransactionResultReceipt[];
+  let isMultiCall: boolean;
+  let logs: DecodedLogs<unknown>['logs'];
+  let groupedLogs: DecodedLogs<unknown>['groupedLogs'];
+  let abis: JsonAbisFromAllCalls | undefined;
+
+  if (typeof paramsOrFunctionScopes === 'object' && !Array.isArray(paramsOrFunctionScopes)) {
+    functionScopes = paramsOrFunctionScopes.functionScopes;
+    receipts = paramsOrFunctionScopes.receipts;
+    isMultiCall = paramsOrFunctionScopes.isMultiCall;
+    logs = paramsOrFunctionScopes.logs ?? [];
+    groupedLogs = paramsOrFunctionScopes.groupedLogs ?? {};
+    abis = paramsOrFunctionScopes.abis;
+  } else {
+    functionScopes = paramsOrFunctionScopes;
+    receipts = _receipts as TransactionResultReceipt[];
+    isMultiCall = _isMultiCall as boolean;
+    logs = _logs ?? [];
+    groupedLogs = _groupedLogs ?? {};
+    abis = _abis;
+  }
+
   const mainCallConfig = functionScopes[0]?.getCallConfig();
 
   if (functionScopes.length === 1 && mainCallConfig && 'bytes' in mainCallConfig.program) {
-    return callResultToInvocationResult<T>({ receipts }, mainCallConfig, logs, groupedLogs, abis);
+    return callResultToInvocationResult<T>({
+      callResult: { receipts },
+      call: mainCallConfig,
+      logs,
+      groupedLogs,
+      abis,
+    });
   }
-  const encodedResults = decodeContractCallScriptResult(
-    { receipts },
-    (mainCallConfig?.program as AbstractContract).id,
+  const encodedResults = decodeContractCallScriptResult({
+    callResult: { receipts },
+    contractId: (mainCallConfig?.program as AbstractContract).id,
     logs,
     groupedLogs,
-    abis
-  );
+    abis,
+  });
 
   const decodedResults = encodedResults.map((encodedResult, i) => {
     const { func } = functionScopes[i].getCallConfig();
     return func.decodeOutput(encodedResult)?.[0];
   });
 
   return (isMultiCall ? decodedResults : decodedResults?.[0]) as T;
-};
+}
 
 type BuiltFunctionResultParams = {
   funcScope: InvocationScopeLike | Array<InvocationScopeLike>;

packages/program/src/script-request.ts

@@ -90,25 +90,26 @@ function callResultToScriptResult(callResult: CallResult): ScriptResult {
   return scriptResult;
 }
 
+type DecodeCallResultParams<TResult> = {
+  callResult: CallResult;
+  scriptResultDecoder: (scriptResult: ScriptResult) => TResult;
+  logs?: DecodedLogs['logs'];
+  groupedLogs?: DecodedLogs['groupedLogs'];
+  abis?: JsonAbisFromAllCalls;
+};
+
 /**
- * Decodes a CallResult using the provided decoder function.
+ * Decodes a CallResult using the provided options.
  *
- * @param callResult - The CallResult to decode.
- * @param decoder - The decoding function to apply on the ScriptResult.
- * @param logs - Optional logs associated with the decoding.
+ * @param params - The options to decode the CallResult.
  * @returns The decoded result.
  * @throws Throws an error if decoding fails.
  */
-export function decodeCallResult<TResult>(
-  callResult: CallResult,
-  decoder: (scriptResult: ScriptResult) => TResult,
-  logs: DecodedLogs['logs'] = [],
-  groupedLogs: DecodedLogs['groupedLogs'] = {},
-  abis?: JsonAbisFromAllCalls
-): TResult {
+export function decodeCallResult<TResult>(params: DecodeCallResultParams<TResult>): TResult {
+  const { callResult, scriptResultDecoder, logs = [], groupedLogs = {}, abis } = params;
   try {
     const scriptResult = callResultToScriptResult(callResult);
-    return decoder(scriptResult);
+    return scriptResultDecoder(scriptResult);
   } catch (error) {
     if ((<FuelError>error).code === ErrorCode.SCRIPT_REVERTED) {
       const statusReason = (<DryRunFailureStatusFragment>callResult?.dryRunStatus)?.reason;
@@ -125,24 +126,27 @@ export function decodeCallResult<TResult>(
   }
 }
 
+export type CallResultToInvocationResultParams = {
+  callResult: CallResult;
+  call: CallConfig;
+  logs?: DecodedLogs<unknown>['logs'];
+  groupedLogs?: DecodedLogs<unknown>['groupedLogs'];
+  abis?: JsonAbisFromAllCalls;
+};
+
 /**
- * Converts a CallResult to an invocation result based on the provided call configuration.
+ * Decodes a CallResult using the provided options.
  *
- * @param callResult - The CallResult from the script call.
- * @param call - The call configuration.
- * @param logs - Optional logs associated with the decoding.
+ * @param params - The parameters to decode the CallResult.
  * @returns The decoded invocation result.
  */
 export function callResultToInvocationResult<TReturn>(
-  callResult: CallResult,
-  call: CallConfig,
-  logs?: DecodedLogs<unknown>['logs'],
-  groupedLogs?: DecodedLogs<unknown>['groupedLogs'],
-  abis?: JsonAbisFromAllCalls
+  params: CallResultToInvocationResultParams
 ): TReturn {
-  return decodeCallResult(
+  const { callResult, call, logs = [], groupedLogs = {}, abis } = params;
+  return decodeCallResult({
     callResult,
-    (scriptResult: ScriptResult) => {
+    scriptResultDecoder: (scriptResult: ScriptResult) => {
       if (scriptResult.returnReceipt.type === ReceiptType.Revert) {
         throw new FuelError(
           ErrorCode.SCRIPT_REVERTED,
@@ -178,8 +182,8 @@ export function callResultToInvocationResult<TReturn>(
     },
     logs,
     groupedLogs,
-    abis
-  );
+    abis,
+  });
 }
 
 export type EncodedScriptCall = Uint8Array | { data: Uint8Array; script: Uint8Array };
@@ -266,11 +270,58 @@ export class ScriptRequest<TData = void, TResult = void> {
   /**
    * Decodes the result of a script call.
    *
-   * @param callResult - The CallResult from the script call.
+   * @param callResultOrParams - The CallResult from the script call.
    * @param logs - Optional logs associated with the decoding.
+   * @param groupedLogs - Optional grouped logs associated with the decoding.
+   * @param abis - Optional abis associated with the decoding.
+   * @returns The decoded result.
+   *
+   * @deprecated Use the object-based approach for parameters instead.
+   */
+  decodeCallResult(
+    callResult: CallResult,
+    logs?: Array<any>,
+    groupedLogs?: DecodedLogs['groupedLogs'],
+    abis?: JsonAbisFromAllCalls
+  ): TResult;
+
+  /**
+   * Decodes the result of a script call.
+   *
+   * @param params - The parameters to decode the CallResult.
    * @returns The decoded result.
    */
-  decodeCallResult(callResult: CallResult, logs: Array<any> = []): TResult {
-    return decodeCallResult(callResult, this.scriptResultDecoder, logs);
+  decodeCallResult(params: Omit<DecodeCallResultParams<TResult>, 'scriptResultDecoder'>): TResult;
+
+  decodeCallResult(
+    callResultOrParams: CallResult | Omit<DecodeCallResultParams<TResult>, 'scriptResultDecoder'>,
+    _logs?: Array<any>,
+    _groupedLogs?: DecodedLogs['groupedLogs'],
+    _abis?: JsonAbisFromAllCalls
+  ): TResult {
+    let callResult: CallResult;
+    let logs: Array<any>;
+    let groupedLogs: DecodedLogs['groupedLogs'];
+    let abis: JsonAbisFromAllCalls | undefined;
+
+    if (typeof callResultOrParams === 'object' && 'callResult' in callResultOrParams) {
+      callResult = callResultOrParams.callResult as CallResult;
+      logs = callResultOrParams.logs ?? [];
+      groupedLogs = callResultOrParams.groupedLogs ?? {};
+      abis = callResultOrParams.abis;
+    } else {
+      callResult = callResultOrParams as CallResult;
+      logs = _logs ?? [];
+      groupedLogs = _groupedLogs ?? {};
+      abis = _abis;
+    }
+
+    return decodeCallResult({
+      callResult,
+      scriptResultDecoder: this.scriptResultDecoder,
+      logs,
+      groupedLogs,
+      abis,
+    });
   }
 }