refactor: add base StacHook interface for type consistency

- Add StacHook base interface with common properties (isLoading, isFetching, error)
- Add StacRefetchFn<T> type for standardized refetch signatures
- Update all hooks to extend StacHook interface (StacCollectionHook, StacCollectionsHook, StacItemHook, StacSearchHook)

Author: AliceR

src/hooks/useCollection.ts

@@ -1,17 +1,14 @@
-import { useQuery, type QueryObserverResult } from '@tanstack/react-query';
-import type { ApiErrorType } from '../types';
+import { useQuery } from '@tanstack/react-query';
+import type { StacHook, StacRefetchFn, ApiErrorType } from '../types';
 import type { Collection } from '../types/stac';
 import { handleStacResponse } from '../utils/handleStacResponse';
 import { generateCollectionQueryKey } from '../utils/queryKeys';
 import { useStacApiContext } from '../context/useStacApiContext';
 
-type StacCollectionHook = {
+interface StacCollectionHook extends StacHook {
   collection?: Collection;
-  isLoading: boolean;
-  isFetching: boolean;
-  refetch: () => Promise<QueryObserverResult<Collection, ApiErrorType>>;
-  error?: ApiErrorType;
-};
+  refetch: StacRefetchFn<Collection>;
+}
 
 function useCollection(collectionId: string): StacCollectionHook {
   const { stacApi } = useStacApiContext();

src/hooks/useCollections.ts

@@ -1,17 +1,14 @@
-import { useQuery, type QueryObserverResult } from '@tanstack/react-query';
-import { type ApiErrorType } from '../types';
+import { useQuery } from '@tanstack/react-query';
+import type { StacHook, StacRefetchFn, ApiErrorType } from '../types';
 import type { CollectionsResponse } from '../types/stac';
 import { handleStacResponse } from '../utils/handleStacResponse';
 import { generateCollectionsQueryKey } from '../utils/queryKeys';
 import { useStacApiContext } from '../context/useStacApiContext';
 
-type StacCollectionsHook = {
+interface StacCollectionsHook extends StacHook {
   collections?: CollectionsResponse;
-  refetch: () => Promise<QueryObserverResult<CollectionsResponse, ApiErrorType>>;
-  isLoading: boolean;
-  isFetching: boolean;
-  error?: ApiErrorType;
-};
+  refetch: StacRefetchFn<CollectionsResponse>;
+}
 
 function useCollections(): StacCollectionsHook {
   const { stacApi } = useStacApiContext();

src/hooks/useItem.ts

@@ -1,19 +1,16 @@
-import { useQuery, type QueryObserverResult } from '@tanstack/react-query';
-import { Item } from '../types/stac';
-import { type ApiErrorType } from '../types';
+import { useQuery } from '@tanstack/react-query';
+import type { StacHook, StacRefetchFn, ApiErrorType } from '../types';
+import type { Item } from '../types/stac';
 import { useStacApiContext } from '../context/useStacApiContext';
 import { handleStacResponse } from '../utils/handleStacResponse';
 import { generateItemQueryKey } from '../utils/queryKeys';
 
-type ItemHook = {
+interface StacItemHook extends StacHook {
   item?: Item;
-  isLoading: boolean;
-  isFetching: boolean;
-  error?: ApiErrorType;
-  refetch: () => Promise<QueryObserverResult<Item, ApiErrorType>>;
-};
+  refetch: StacRefetchFn<Item>;
+}
 
-function useItem(url: string): ItemHook {
+function useItem(url: string): StacItemHook {
   const { stacApi } = useStacApiContext();
 
   const fetchItem = async (): Promise<Item> => {

src/hooks/useStacSearch.ts

@@ -2,7 +2,7 @@ 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 ApiErrorType } from '../types';
+import type { StacHook, ApiErrorType } from '../types';
 import { handleStacResponse } from '../utils/handleStacResponse';
 import type {
   Link,
@@ -16,7 +16,7 @@ import { useStacApiContext } from '../context/useStacApiContext';
 
 type PaginationHandler = () => void;
 
-type StacSearchHook = {
+interface StacSearchHook extends StacHook {
   ids?: string[];
   setIds: (ids?: string[]) => void;
   bbox?: Bbox;
@@ -33,12 +33,9 @@ type StacSearchHook = {
   setLimit: (limit: number) => void;
   submit: () => void;
   results?: SearchResponse;
-  isLoading: boolean;
-  isFetching: boolean;
-  error?: ApiErrorType;
   nextPage: PaginationHandler | undefined;
   previousPage: PaginationHandler | undefined;
-};
+}
 
 function useStacSearch(): StacSearchHook {
   const { stacApi } = useStacApiContext();
@@ -214,7 +211,7 @@ function useStacSearch(): StacSearchHook {
     results,
     isLoading,
     isFetching,
-    error: error ?? undefined,
+    error: error as ApiErrorType,
     sortby,
     setSortby,
     limit,

src/types/index.d.ts

@@ -1,3 +1,5 @@
+import type { QueryObserverResult } from '@tanstack/react-query';
+
 export type GenericObject = {
   [key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any
 };
@@ -8,3 +10,23 @@ export type ApiErrorType = {
   statusText: string;
   url?: string;
 };
+
+/**
+ * Base interface for all STAC hooks providing common loading state and error handling.
+ * All data-fetching hooks (useCollection, useCollections, useItem, useStacSearch)
+ * extend this interface with their specific data and refetch signatures.
+ */
+export interface StacHook {
+  /** True during initial data fetch (no cached data available) */
+  isLoading: boolean;
+  /** True during any fetch operation (including background refetches) */
+  isFetching: boolean;
+  /** Error information if the last request was unsuccessful */
+  error?: ApiErrorType;
+}
+
+/**
+ * Generic refetch function type for STAC hooks.
+ * Returns a Promise with the query result including data and error information.
+ */
+export type StacRefetchFn<T> = () => Promise<QueryObserverResult<T, ApiErrorType>>;