(ts-api-react-actions) Enhance error handling in API actions and hooks with user-facing error mapping

Author: Oksamies

packages/ts-api-react-actions/src/ApiAction.tsx

@@ -1,10 +1,11 @@
 import { useCallback } from "react";
 
 import {
-  type ApiEndpointProps,
-  ApiError,
+  ApiEndpointProps,
+  UserFacingError,
+  mapApiErrorToUserFacingError,
 } from "@thunderstore/thunderstore-api";
-import { type ApiEndpoint } from "@thunderstore/ts-api-react";
+import { ApiEndpoint, UseApiCallOptions } from "@thunderstore/ts-api-react";
 
 import { useApiAction } from "./useApiAction";
 
@@ -15,25 +16,26 @@ export interface ApiActionProps<
   Return,
 > {
   endpoint: ApiEndpoint<Params, QueryParams, Data, Return>;
+  apiCallOptions?: UseApiCallOptions;
   onSubmitSuccess?: (result: Awaited<Return>) => void;
-  onSubmitError?: (error: Error | ApiError) => void;
+  onSubmitError?: (error: UserFacingError) => void;
 }
 
-// As of this moment ApiActions sole purpose is to gracefully handle errors from API calls
 export function ApiAction<
   Params extends object,
   QueryParams extends object,
   Data extends object,
   Return,
 >(props: ApiActionProps<Params, QueryParams, Data, Return>) {
-  const { endpoint, onSubmitSuccess, onSubmitError } = props;
+  const { endpoint, onSubmitSuccess, onSubmitError, apiCallOptions } = props;
   const submitHandler = useApiAction<
     Params,
     QueryParams,
     Data,
     ReturnType<typeof endpoint>
   >({
     endpoint: endpoint,
+    apiCallOptions,
   });
   const onSubmit = useCallback(
     async (onSubmitProps: ApiEndpointProps<Params, QueryParams, Data>) => {
@@ -43,14 +45,17 @@ export function ApiAction<
           onSubmitSuccess(result);
         }
       } catch (e) {
+        const mappedError =
+          e instanceof UserFacingError ? e : mapApiErrorToUserFacingError(e);
+
         if (onSubmitError) {
-          onSubmitError(e as Error | ApiError);
+          onSubmitError(mappedError);
         } else {
-          throw e;
+          throw mappedError;
         }
       }
     },
-    [onSubmitSuccess, onSubmitError]
+    [onSubmitSuccess, onSubmitError, apiCallOptions, submitHandler]
   );
 
   return onSubmit;

packages/ts-api-react-actions/src/useApiAction.ts

@@ -1,20 +1,38 @@
+import { useCallback } from "react";
+
 import { type ApiEndpointProps } from "@thunderstore/thunderstore-api";
-import { type ApiEndpoint, useApiCall } from "@thunderstore/ts-api-react";
+import {
+  type ApiEndpoint,
+  UseApiCallOptions,
+  useApiCall,
+} from "@thunderstore/ts-api-react";
 
 export type UseApiActionArgs<Params, QueryParams, Data, Return> = {
   endpoint: ApiEndpoint<Params, QueryParams, Data, Return>;
+  apiCallOptions?: UseApiCallOptions;
 };
 
+/**
+ * Hook that adapts `useApiCall` to an async submit handler suitable for form actions.
+ */
 export function useApiAction<Params, QueryParams, Data, Return>(
   args: UseApiActionArgs<Params, QueryParams, Data, Return>
-) {
-  const apiCall = useApiCall<Params, QueryParams, Data, Return>(args.endpoint);
+): (
+  props: ApiEndpointProps<Params, QueryParams, Data>
+) => Promise<Awaited<Return>> {
+  const apiCall = useApiCall<Params, QueryParams, Data, Return>(
+    args.endpoint,
+    args.apiCallOptions
+  );
 
-  const submitHandler = async (
-    props: ApiEndpointProps<Params, QueryParams, Data>
-  ) => {
-    return await apiCall(props);
-  };
+  const submitHandler = useCallback(
+    async (
+      props: ApiEndpointProps<Params, QueryParams, Data>
+    ): Promise<Awaited<Return>> => {
+      return await apiCall(props);
+    },
+    [apiCall, args]
+  );
 
   return submitHandler;
 }

packages/ts-api-react/src/index.ts

@@ -18,4 +18,4 @@ export {
 export type { ContextInterface } from "./SessionContext";
 export { StorageManager as NamespacedStorageManager } from "./storage";
 export { useApiCall } from "./useApiCall";
-export type { ApiEndpoint } from "./useApiCall";
+export type { ApiEndpoint, UseApiCallOptions } from "./useApiCall";

packages/ts-api-react/src/useApiCall.ts

@@ -1,13 +1,57 @@
-import { type ApiEndpointProps } from "@thunderstore/thunderstore-api";
+import {
+  type ApiEndpointProps,
+  MapUserFacingErrorOptions,
+  mapApiErrorToUserFacingError,
+} from "@thunderstore/thunderstore-api";
 
+/**
+ * Describes an API endpoint invocation with typed params and data payload.
+ */
 export type ApiEndpoint<Params, QueryParams, Data, Return> = (
   props: ApiEndpointProps<Params, QueryParams, Data>
 ) => Return;
 
+/**
+ * Options that control automatic error mapping for `useApiCall`.
+ */
+export type UseApiCallOptions = {
+  mapErrors?: boolean;
+  errorOptions?: MapUserFacingErrorOptions;
+};
+
+/**
+ * Wraps API endpoints to optionally map thrown errors into `UserFacingError` instances.
+ */
 export function useApiCall<Params, QueryParams, Data, Return>(
-  endpoint: ApiEndpoint<Params, QueryParams, Data, Return>
+  endpoint: ApiEndpoint<Params, QueryParams, Data, Return>,
+  options: UseApiCallOptions = {}
 ): (props: ApiEndpointProps<Params, QueryParams, Data>) => Return {
+  const shouldMapErrors = options.mapErrors ?? true;
+
   return (props: ApiEndpointProps<Params, QueryParams, Data>) => {
-    return endpoint(props);
+    try {
+      const result = endpoint(props);
+
+      if (shouldMapErrors && isPromise(result)) {
+        return result.catch((error) => {
+          throw mapApiErrorToUserFacingError(error, options.errorOptions);
+        }) as Return;
+      }
+
+      return result;
+    } catch (error) {
+      if (!shouldMapErrors) {
+        throw error;
+      }
+      throw mapApiErrorToUserFacingError(error, options.errorOptions);
+    }
   };
 }
+
+function isPromise(value: unknown): value is Promise<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Promise<unknown>).then === "function"
+  );
+}