refactor: fetch single collection directly from /collections/{id} endpoint

- Add getCollection(collectionId) method to StacApi class
- Refactor useCollection to query /collections/{collectionId} directly
- Add generateCollectionQueryKey for independent collection caching
- Update tests to mock single collection endpoint instead of filtering

Previously, useCollection fetched all collections and filtered to find one.
Now it uses the STAC spec's dedicated endpoint, improving efficiency for
large catalogs and enabling independent collection caching.

Author: AliceR

src/hooks/useCollection.test.ts

@@ -11,40 +11,30 @@ describe('useCollection', () => {
   it('queries collection', async () => {
     fetch
       .mockResponseOnce(JSON.stringify({ links: [] }), { url: 'https://fake-stac-api.net' })
-      .mockResponseOnce(
-        JSON.stringify({
-          collections: [
-            { id: 'abc', title: 'Collection A' },
-            { id: 'def', title: 'Collection B' },
-          ],
-        })
-      );
+      .mockResponseOnce(JSON.stringify({ id: 'abc', title: 'Collection A' }));
 
     const { result } = renderHook(() => useCollection('abc'), { wrapper });
     await waitFor(() => expect(result.current.isLoading).toEqual(false));
     await waitFor(() =>
       expect(result.current.collection).toEqual({ id: 'abc', title: 'Collection A' })
     );
+    expect(fetch.mock.calls[1][0]).toEqual('https://fake-stac-api.net/collections/abc');
   });
 
   it('returns error if collection does not exist', async () => {
     fetch
       .mockResponseOnce(JSON.stringify({ links: [] }), { url: 'https://fake-stac-api.net' })
-      .mockResponseOnce(
-        JSON.stringify({
-          collections: [
-            { id: 'abc', title: 'Collection A' },
-            { id: 'def', title: 'Collection B' },
-          ],
-        })
-      );
+      .mockResponseOnce(JSON.stringify({ error: 'Collection not found' }), {
+        status: 404,
+        statusText: 'Not Found',
+      });
 
-    const { result } = renderHook(() => useCollection('ghi'), { wrapper });
+    const { result } = renderHook(() => useCollection('nonexistent'), { wrapper });
     await waitFor(() =>
       expect(result.current.error).toEqual({
         status: 404,
-        statusText: 'Not found',
-        detail: 'Collection does not exist',
+        statusText: 'Not Found',
+        detail: { error: 'Collection not found' },
       })
     );
   });
@@ -73,34 +63,20 @@ describe('useCollection', () => {
       .mockResponseOnce('Wrong query', { status: 400, statusText: 'Bad Request' });
 
     const { result } = renderHook(() => useCollection('abc'), { wrapper });
-    await waitFor(() => expect(result.current.error).toBeDefined());
-
-    expect(result.current.error).toEqual({
-      status: 400,
-      statusText: 'Bad Request',
-      detail: 'Wrong query',
-    });
+    await waitFor(() =>
+      expect(result.current.error).toEqual({
+        status: 400,
+        statusText: 'Bad Request',
+        detail: 'Wrong query',
+      })
+    );
   });
 
   it('reloads collection', async () => {
     fetch
       .mockResponseOnce(JSON.stringify({ links: [] }), { url: 'https://fake-stac-api.net' })
-      .mockResponseOnce(
-        JSON.stringify({
-          collections: [
-            { id: 'abc', title: 'Collection A' },
-            { id: 'def', title: 'Collection B' },
-          ],
-        })
-      )
-      .mockResponseOnce(
-        JSON.stringify({
-          collections: [
-            { id: 'abc', title: 'Collection A - Updated' },
-            { id: 'def', title: 'Collection B' },
-          ],
-        })
-      );
+      .mockResponseOnce(JSON.stringify({ id: 'abc', title: 'Collection A' }))
+      .mockResponseOnce(JSON.stringify({ id: 'abc', title: 'Collection A - Updated' }));
 
     const { result } = renderHook(() => useCollection('abc'), { wrapper });
     await waitFor(() =>

src/hooks/useCollection.ts

@@ -1,8 +1,9 @@
-import { useMemo } from 'react';
-
+import { useQuery } from '@tanstack/react-query';
 import type { ApiErrorType } from '../types';
 import type { Collection } from '../types/stac';
-import useCollections from './useCollections';
+import { ApiError } from '../utils/ApiError';
+import { generateCollectionQueryKey } from '../utils/queryKeys';
+import { useStacApiContext } from '../context/useStacApiContext';
 
 type StacCollectionHook = {
   collection?: Collection;
@@ -13,29 +14,43 @@ type StacCollectionHook = {
 };
 
 function useCollection(collectionId: string): StacCollectionHook {
-  const { collections, isLoading, isFetching, error: requestError, reload } = useCollections();
+  const { stacApi } = useStacApiContext();
 
-  const collection = useMemo(() => {
-    return collections?.collections.find(({ id }) => id === collectionId);
-  }, [collectionId, collections]);
+  const fetchCollection = async (): Promise<Collection> => {
+    if (!stacApi) throw new Error('No STAC API configured');
+    const response: Response = await stacApi.getCollection(collectionId);
+    if (!response.ok) {
+      let detail;
+      try {
+        detail = await response.json();
+      } catch {
+        detail = await response.text();
+      }
 
-  // Determine error: prefer requestError, else local 404 if collection not found
-  const error: ApiErrorType | undefined = requestError
-    ? requestError
-    : !collection && collections
-      ? {
-          status: 404,
-          statusText: 'Not found',
-          detail: 'Collection does not exist',
-        }
-      : undefined;
+      throw new ApiError(response.statusText, response.status, detail);
+    }
+    return await response.json();
+  };
+
+  const {
+    data: collection,
+    error,
+    isLoading,
+    isFetching,
+    refetch,
+  } = useQuery<Collection, ApiErrorType>({
+    queryKey: generateCollectionQueryKey(collectionId),
+    queryFn: fetchCollection,
+    enabled: !!stacApi,
+    retry: false,
+  });
 
   return {
     collection,
     isLoading,
     isFetching,
-    error,
-    reload,
+    error: error as ApiErrorType,
+    reload: refetch as () => void,
   };
 }
 

src/stac-api/index.ts

@@ -152,6 +152,10 @@ class StacApi {
     return this.fetch(`${this.baseUrl}/collections`);
   }
 
+  getCollection(collectionId: string): Promise<Response> {
+    return this.fetch(`${this.baseUrl}/collections/${collectionId}`);
+  }
+
   get(href: string, headers = {}): Promise<Response> {
     return this.fetch(href, { headers });
   }

src/utils/queryKeys.test.ts

@@ -4,6 +4,7 @@ import {
   generateStacApiQueryKey,
   generateItemQueryKey,
   generateCollectionsQueryKey,
+  generateCollectionQueryKey,
 } from './queryKeys';
 import type { SearchRequestPayload, Sortby } from '../types/stac';
 
@@ -15,6 +16,21 @@ describe('Query Key Generators', () => {
     });
   });
 
+  describe('generateCollectionQueryKey', () => {
+    it('should generate key with collection ID', () => {
+      const key = generateCollectionQueryKey('my-collection');
+      expect(key).toEqual(['collection', 'my-collection']);
+    });
+
+    it('should handle different collection IDs', () => {
+      const key1 = generateCollectionQueryKey('collection-a');
+      const key2 = generateCollectionQueryKey('collection-b');
+      expect(key1).not.toEqual(key2);
+      expect(key1).toEqual(['collection', 'collection-a']);
+      expect(key2).toEqual(['collection', 'collection-b']);
+    });
+  });
+
   describe('generateItemQueryKey', () => {
     it('should generate key with item URL', () => {
       const url = 'https://example.com/collections/test/items/item1';

src/utils/queryKeys.ts

@@ -45,6 +45,14 @@ export function generateCollectionsQueryKey(): [string] {
   return ['collections'];
 }
 
+/**
+ * Generates a query key for a single STAC collection request.
+ * Collections are fetched by ID from /collections/{collectionId}.
+ */
+export function generateCollectionQueryKey(collectionId: string): [string, string] {
+  return ['collection', collectionId];
+}
+
 /**
  * Generates a query key for STAC item requests.
  * Items are fetched by URL.