refactor: replace Object.assign error pattern with ApiError class

- Create ApiError class extending Error in src/utils/ApiError.ts
- Rename ApiError type to ApiErrorType to avoid naming conflict
- Update all hooks to throw new ApiError instances

Author: AliceR

src/hooks/useCollection.ts

@@ -1,13 +1,13 @@
 import { useMemo } from 'react';
 
-import type { ApiError, LoadingState } from '../types';
+import type { ApiErrorType, LoadingState } from '../types';
 import type { Collection } from '../types/stac';
 import useCollections from './useCollections';
 
 type StacCollectionHook = {
   collection?: Collection;
   state: LoadingState;
-  error?: ApiError;
+  error?: ApiErrorType;
   reload: () => void;
 };
 
@@ -19,7 +19,7 @@ function useCollection(collectionId: string): StacCollectionHook {
   }, [collectionId, collections]);
 
   // Determine error: prefer requestError, else local 404 if collection not found
-  const error: ApiError | undefined = requestError
+  const error: ApiErrorType | undefined = requestError
     ? requestError
     : !collection && collections
       ? {

src/hooks/useCollections.ts

@@ -1,16 +1,17 @@
 import { useEffect, useState, useMemo } from 'react';
 import { useQuery } from '@tanstack/react-query';
-import { type ApiError, type LoadingState } from '../types';
+import { type ApiErrorType, type LoadingState } from '../types';
 import type { CollectionsResponse } from '../types/stac';
 import debounce from '../utils/debounce';
+import { ApiError } from '../utils/ApiError';
 import { generateCollectionsQueryKey } from '../utils/queryKeys';
 import { useStacApiContext } from '../context/useStacApiContext';
 
 type StacCollectionsHook = {
   collections?: CollectionsResponse;
   reload: () => void;
   state: LoadingState;
-  error?: ApiError;
+  error?: ApiErrorType;
 };
 
 function useCollections(): StacCollectionsHook {
@@ -28,12 +29,7 @@ function useCollections(): StacCollectionsHook {
         detail = await response.text();
       }
 
-      const err = Object.assign(new Error(response.statusText), {
-        status: response.status,
-        statusText: response.statusText,
-        detail,
-      });
-      throw err;
+      throw new ApiError(response.statusText, response.status, detail);
     }
     return await response.json();
   };
@@ -44,7 +40,7 @@ function useCollections(): StacCollectionsHook {
     isLoading,
     isFetching,
     refetch,
-  } = useQuery<CollectionsResponse, ApiError>({
+  } = useQuery<CollectionsResponse, ApiErrorType>({
     queryKey: generateCollectionsQueryKey(),
     queryFn: fetchCollections,
     enabled: !!stacApi,
@@ -76,7 +72,7 @@ function useCollections(): StacCollectionsHook {
     collections,
     reload,
     state,
-    error: error as ApiError,
+    error: error as ApiErrorType,
   };
 }
 

src/hooks/useItem.ts

@@ -1,14 +1,15 @@
 import { useEffect, useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { Item } from '../types/stac';
-import { ApiError, LoadingState } from '../types';
+import { type ApiErrorType, type LoadingState } from '../types';
 import { useStacApiContext } from '../context/useStacApiContext';
+import { ApiError } from '../utils/ApiError';
 import { generateItemQueryKey } from '../utils/queryKeys';
 
 type ItemHook = {
   item?: Item;
   state: LoadingState;
-  error?: ApiError;
+  error?: ApiErrorType;
   reload: () => void;
 };
 
@@ -26,12 +27,8 @@ function useItem(url: string): ItemHook {
       } catch {
         detail = await response.text();
       }
-      const err = Object.assign(new Error(response.statusText), {
-        status: response.status,
-        statusText: response.statusText,
-        detail,
-      });
-      throw err;
+
+      throw new ApiError(response.statusText, response.status, detail);
     }
     return await response.json();
   };
@@ -42,7 +39,7 @@ function useItem(url: string): ItemHook {
     isLoading,
     isFetching,
     refetch,
-  } = useQuery<Item, ApiError>({
+  } = useQuery<Item, ApiErrorType>({
     queryKey: generateItemQueryKey(url),
     queryFn: fetchItem,
     enabled: !!stacApi,
@@ -60,7 +57,7 @@ function useItem(url: string): ItemHook {
   return {
     item,
     state,
-    error: error as ApiError,
+    error: error as ApiErrorType,
     reload: refetch as () => void,
   };
 }

src/hooks/useStacSearch.ts

@@ -2,7 +2,8 @@ import { useCallback, useState, useMemo, useEffect } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import debounce from '../utils/debounce';
 import { generateStacSearchQueryKey } from '../utils/queryKeys';
-import type { ApiError, LoadingState } from '../types';
+import { type ApiErrorType, type LoadingState } from '../types';
+import { ApiError } from '../utils/ApiError';
 import type {
   Link,
   Bbox,
@@ -33,7 +34,7 @@ type StacSearchHook = {
   submit: () => void;
   results?: SearchResponse;
   state: LoadingState;
-  error: ApiError | undefined;
+  error?: ApiErrorType;
   nextPage: PaginationHandler | undefined;
   previousPage: PaginationHandler | undefined;
 };
@@ -122,12 +123,8 @@ function useStacSearch(): StacSearchHook {
       } catch {
         detail = await response.text();
       }
-      const err = Object.assign(new Error(response.statusText), {
-        status: response.status,
-        statusText: response.statusText,
-        detail,
-      });
-      throw err;
+
+      throw new ApiError(response.statusText, response.status, detail);
     }
     return await response.json();
   };
@@ -140,7 +137,7 @@ function useStacSearch(): StacSearchHook {
     error,
     isLoading,
     isFetching,
-  } = useQuery<SearchResponse, ApiError>({
+  } = useQuery<SearchResponse, ApiErrorType>({
     queryKey: currentRequest ? generateStacSearchQueryKey(currentRequest) : ['stacSearch', 'idle'],
     queryFn: () => fetchRequest(currentRequest!),
     enabled: currentRequest !== null,

src/stac-api/index.ts

@@ -1,4 +1,4 @@
-import type { ApiError, GenericObject } from '../types';
+import type { ApiErrorType, GenericObject } from '../types';
 import type { Bbox, SearchPayload, DateRange } from '../types/stac';
 
 type RequestPayload = SearchPayload;
@@ -88,7 +88,7 @@ class StacApi {
 
   async handleError(response: Response) {
     const { status, statusText } = response;
-    const e: ApiError = {
+    const e: ApiErrorType = {
       status,
       statusText,
     };

src/types/index.d.ts

@@ -2,7 +2,7 @@ export type GenericObject = {
   [key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any
 };
 
-export type ApiError = {
+export type ApiErrorType = {
   detail?: GenericObject | string;
   status: number;
   statusText: string;

src/utils/ApiError.ts

@@ -0,0 +1,25 @@
+import type { GenericObject } from '../types';
+
+/**
+ * Custom error class for STAC API errors.
+ * Extends the native Error class with HTTP response details.
+ */
+export class ApiError extends Error {
+  status: number;
+  statusText: string;
+  detail?: GenericObject | string;
+
+  constructor(statusText: string, status: number, detail?: GenericObject | string) {
+    super(statusText);
+    this.name = 'ApiError';
+    this.status = status;
+    this.statusText = statusText;
+    this.detail = detail;
+
+    // Maintains proper stack trace for where our error was thrown
+    // Note: Error.captureStackTrace is a V8-only feature (Node.js, Chrome)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ApiError);
+    }
+  }
+}