feat: optimize React Query cache keys

- Add centralized query key generators in src/utils/queryKeys.ts
- Extract minimal parameters instead of hashing full request objects
- Update all hooks to use optimized query key generators

Reduces hashing costs for React Query cache lookups by generating smaller,
more stable keys with only search-relevant parameters.

Author: AliceR

src/hooks/useCollections.ts

@@ -3,6 +3,7 @@ import { useQuery } from '@tanstack/react-query';
 import { type ApiError, type LoadingState } from '../types';
 import type { CollectionsResponse } from '../types/stac';
 import debounce from '../utils/debounce';
+import { generateCollectionsQueryKey } from '../utils/queryKeys';
 import { useStacApiContext } from '../context/useStacApiContext';
 
 type StacCollectionsHook = {
@@ -44,7 +45,7 @@ function useCollections(): StacCollectionsHook {
     isFetching,
     refetch,
   } = useQuery<CollectionsResponse, ApiError>({
-    queryKey: ['collections'],
+    queryKey: generateCollectionsQueryKey(),
     queryFn: fetchCollections,
     enabled: !!stacApi,
     retry: false,

src/hooks/useItem.ts

@@ -3,6 +3,7 @@ import { useQuery } from '@tanstack/react-query';
 import { Item } from '../types/stac';
 import { ApiError, LoadingState } from '../types';
 import { useStacApiContext } from '../context/useStacApiContext';
+import { generateItemQueryKey } from '../utils/queryKeys';
 
 type ItemHook = {
   item?: Item;
@@ -42,7 +43,7 @@ function useItem(url: string): ItemHook {
     isFetching,
     refetch,
   } = useQuery<Item, ApiError>({
-    queryKey: ['item', url],
+    queryKey: generateItemQueryKey(url),
     queryFn: fetchItem,
     enabled: !!stacApi,
     retry: false,

src/hooks/useStacApi.ts

@@ -2,6 +2,7 @@ import { useQuery } from '@tanstack/react-query';
 import StacApi, { SearchMode } from '../stac-api';
 import { Link } from '../types/stac';
 import { GenericObject } from '../types';
+import { generateStacApiQueryKey } from '../utils/queryKeys';
 
 type StacApiHook = {
   stacApi?: StacApi;
@@ -11,7 +12,7 @@ type StacApiHook = {
 
 function useStacApi(url: string, options?: GenericObject): StacApiHook {
   const { data, isSuccess, isLoading, isError } = useQuery({
-    queryKey: ['stacApi', url, options],
+    queryKey: generateStacApiQueryKey(url, options),
     queryFn: async () => {
       let searchMode = SearchMode.GET;
       const response = await fetch(url, {

src/hooks/useStacSearch.ts

@@ -1,14 +1,15 @@
 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 {
   Link,
   Bbox,
   CollectionIdList,
-  SearchPayload,
   SearchResponse,
   Sortby,
+  FetchRequest,
 } from '../types/stac';
 import { useStacApiContext } from '../context/useStacApiContext';
 
@@ -37,17 +38,6 @@ type StacSearchHook = {
   previousPage: PaginationHandler | undefined;
 };
 
-type FetchRequest =
-  | {
-      type: 'search';
-      payload: SearchPayload;
-      headers?: Record<string, string>;
-    }
-  | {
-      type: 'get';
-      url: string;
-    };
-
 function useStacSearch(): StacSearchHook {
   const { stacApi } = useStacApiContext();
   const queryClient = useQueryClient();
@@ -151,7 +141,7 @@ function useStacSearch(): StacSearchHook {
     isLoading,
     isFetching,
   } = useQuery<SearchResponse, ApiError>({
-    queryKey: ['stacSearch', currentRequest],
+    queryKey: currentRequest ? generateStacSearchQueryKey(currentRequest) : ['stacSearch', 'idle'],
     queryFn: () => fetchRequest(currentRequest!),
     enabled: currentRequest !== null,
     retry: false,

src/types/stac.d.ts

@@ -21,6 +21,37 @@ export type SearchPayload = {
   sortby?: Sortby[];
 };
 
+/**
+ * Extended search payload that includes both the base SearchPayload structure
+ * and additional properties used in API requests.
+ */
+export type SearchRequestPayload = SearchPayload & {
+  /** Datetime string in ISO 8601 format (transformed from dateRange) */
+  datetime?: string;
+  /** Maximum number of results to return */
+  limit?: number;
+  /** Pagination token for cursor-based pagination */
+  token?: string;
+  /** Page number for offset-based pagination */
+  page?: number;
+  /** Flag indicating if this payload should be merged with current search params */
+  merge?: boolean;
+};
+
+/**
+ * Type for fetch requests used in useStacSearch hook
+ */
+export type FetchRequest =
+  | {
+      type: 'search';
+      payload: SearchRequestPayload;
+      headers?: Record<string, string>;
+    }
+  | {
+      type: 'get';
+      url: string;
+    };
+
 export type LinkBody = SearchPayload & {
   merge?: boolean;
 };

src/utils/queryKeys.test.ts

@@ -0,0 +1,264 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  generateStacSearchQueryKey,
+  generateStacApiQueryKey,
+  generateItemQueryKey,
+  generateCollectionsQueryKey,
+} from './queryKeys';
+import type { SearchRequestPayload, Sortby } from '../types/stac';
+
+describe('Query Key Generators', () => {
+  describe('generateCollectionsQueryKey', () => {
+    it('should generate a simple static key', () => {
+      const key = generateCollectionsQueryKey();
+      expect(key).toEqual(['collections']);
+    });
+  });
+
+  describe('generateItemQueryKey', () => {
+    it('should generate key with item URL', () => {
+      const url = 'https://example.com/collections/test/items/item1';
+      const key = generateItemQueryKey(url);
+      expect(key).toEqual(['item', url]);
+    });
+
+    it('should handle different URLs', () => {
+      const url1 = 'https://example.com/items/a';
+      const url2 = 'https://example.com/items/b';
+      const key1 = generateItemQueryKey(url1);
+      const key2 = generateItemQueryKey(url2);
+      expect(key1).not.toEqual(key2);
+      expect(key1).toEqual(['item', url1]);
+      expect(key2).toEqual(['item', url2]);
+    });
+  });
+
+  describe('generateStacApiQueryKey', () => {
+    it('should generate key with URL only when no options', () => {
+      const url = 'https://example.com/stac';
+      const key = generateStacApiQueryKey(url);
+      expect(key).toEqual(['stacApi', url, undefined]);
+    });
+
+    it('should extract only headers from options', () => {
+      const url = 'https://example.com/stac';
+      const options = {
+        headers: { Authorization: 'Bearer token123' },
+        someOtherField: { deeply: { nested: { object: 'value' } } },
+        anotherField: 'ignored',
+      };
+      const key = generateStacApiQueryKey(url, options);
+      expect(key).toEqual(['stacApi', url, { headers: { Authorization: 'Bearer token123' } }]);
+    });
+
+    it('should handle options without headers', () => {
+      const url = 'https://example.com/stac';
+      const options = {
+        someField: 'value',
+        anotherField: { nested: 'data' },
+      };
+      const key = generateStacApiQueryKey(url, options);
+      expect(key).toEqual(['stacApi', url, undefined]);
+    });
+
+    it('should handle empty options object', () => {
+      const url = 'https://example.com/stac';
+      const key = generateStacApiQueryKey(url, {});
+      expect(key).toEqual(['stacApi', url, undefined]);
+    });
+  });
+
+  describe('generateStacSearchQueryKey', () => {
+    describe('for search requests', () => {
+      it('should generate key with minimal search params', () => {
+        const payload: SearchRequestPayload = {
+          collections: ['collection1'],
+          limit: 25,
+        };
+        const key = generateStacSearchQueryKey({ type: 'search', payload });
+        expect(key).toEqual([
+          'stacSearch',
+          'search',
+          {
+            collections: ['collection1'],
+            limit: 25,
+          },
+        ]);
+      });
+
+      it('should include all search parameters when present', () => {
+        const sortby: Sortby[] = [
+          { field: 'id', direction: 'asc' },
+          { field: 'properties.cloud', direction: 'desc' },
+        ];
+        const payload: SearchRequestPayload = {
+          ids: ['item1', 'item2'],
+          bbox: [-180, -90, 180, 90],
+          collections: ['collection1', 'collection2'],
+          datetime: '2023-01-01/2023-12-31',
+          sortby,
+          limit: 50,
+        };
+        const key = generateStacSearchQueryKey({ type: 'search', payload });
+        expect(key).toEqual([
+          'stacSearch',
+          'search',
+          {
+            ids: ['item1', 'item2'],
+            bbox: [-180, -90, 180, 90],
+            collections: ['collection1', 'collection2'],
+            datetime: '2023-01-01/2023-12-31',
+            sortby,
+            limit: 50,
+          },
+        ]);
+      });
+
+      it('should omit undefined search parameters', () => {
+        const payload: SearchRequestPayload = {
+          collections: ['collection1'],
+          limit: 25,
+        };
+        const key = generateStacSearchQueryKey({ type: 'search', payload });
+        expect(key[2]).not.toHaveProperty('ids');
+        expect(key[2]).not.toHaveProperty('bbox');
+        expect(key[2]).not.toHaveProperty('datetime');
+        expect(key[2]).not.toHaveProperty('sortby');
+      });
+
+      it('should handle empty collections array', () => {
+        const payload: SearchRequestPayload = {
+          collections: [],
+          limit: 25,
+        };
+        const key = generateStacSearchQueryKey({ type: 'search', payload });
+        expect(key).toEqual([
+          'stacSearch',
+          'search',
+          {
+            collections: [],
+            limit: 25,
+          },
+        ]);
+      });
+
+      it('should ignore headers in search requests for key generation', () => {
+        const payload: SearchRequestPayload = {
+          collections: ['collection1'],
+          limit: 25,
+        };
+        const key = generateStacSearchQueryKey({
+          type: 'search',
+          payload,
+          headers: { Authorization: 'Bearer token', 'X-Custom': 'value' },
+        });
+        expect(key).toEqual([
+          'stacSearch',
+          'search',
+          {
+            collections: ['collection1'],
+            limit: 25,
+          },
+        ]);
+        expect(key[2]).not.toHaveProperty('headers');
+      });
+    });
+
+    describe('for pagination GET requests', () => {
+      it('should generate key with URL for GET requests', () => {
+        const url = 'https://example.com/search?page=2&limit=25';
+        const key = generateStacSearchQueryKey({ type: 'get', url });
+        expect(key).toEqual(['stacSearch', 'page', url]);
+      });
+
+      it('should handle different pagination URLs', () => {
+        const url1 = 'https://example.com/search?page=1';
+        const url2 = 'https://example.com/search?page=2';
+        const key1 = generateStacSearchQueryKey({ type: 'get', url: url1 });
+        const key2 = generateStacSearchQueryKey({ type: 'get', url: url2 });
+        expect(key1).not.toEqual(key2);
+        expect(key1).toEqual(['stacSearch', 'page', url1]);
+        expect(key2).toEqual(['stacSearch', 'page', url2]);
+      });
+    });
+
+    describe('key stability', () => {
+      it('should generate identical keys for identical search payloads', () => {
+        const payload: SearchRequestPayload = {
+          collections: ['collection1', 'collection2'],
+          bbox: [-10, -5, 10, 5],
+          limit: 25,
+        };
+        const key1 = generateStacSearchQueryKey({ type: 'search', payload });
+        const key2 = generateStacSearchQueryKey({ type: 'search', payload });
+        expect(key1).toEqual(key2);
+      });
+
+      it('should generate different keys for different search payloads', () => {
+        const payload1: SearchRequestPayload = {
+          collections: ['collection1'],
+          limit: 25,
+        };
+        const payload2: SearchRequestPayload = {
+          collections: ['collection2'],
+          limit: 25,
+        };
+        const key1 = generateStacSearchQueryKey({ type: 'search', payload: payload1 });
+        const key2 = generateStacSearchQueryKey({ type: 'search', payload: payload2 });
+        expect(key1).not.toEqual(key2);
+      });
+
+      it('should generate different keys when only limit changes', () => {
+        const payload1: SearchRequestPayload = {
+          collections: ['collection1'],
+          limit: 25,
+        };
+        const payload2: SearchRequestPayload = {
+          collections: ['collection1'],
+          limit: 50,
+        };
+        const key1 = generateStacSearchQueryKey({ type: 'search', payload: payload1 });
+        const key2 = generateStacSearchQueryKey({ type: 'search', payload: payload2 });
+        expect(key1).not.toEqual(key2);
+      });
+
+      it('should include extra properties for pagination tokens and custom params', () => {
+        const payload1: SearchRequestPayload = {
+          collections: ['collection1'],
+          limit: 25,
+        };
+
+        const payload2 = {
+          collections: ['collection1'],
+          limit: 25,
+          token: 'next:abc123',
+        } as SearchRequestPayload;
+        const key1 = generateStacSearchQueryKey({ type: 'search', payload: payload1 });
+        const key2 = generateStacSearchQueryKey({ type: 'search', payload: payload2 });
+
+        expect(key1).not.toEqual(key2);
+        expect(key2[2]).toHaveProperty('token', 'next:abc123');
+      });
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty search payload', () => {
+      const payload: SearchRequestPayload = {};
+      const key = generateStacSearchQueryKey({ type: 'search', payload });
+      expect(key).toEqual(['stacSearch', 'search', {}]);
+    });
+
+    it('should handle very long URLs', () => {
+      const longUrl = 'https://example.com/items/' + 'a'.repeat(1000);
+      const key = generateItemQueryKey(longUrl);
+      expect(key).toEqual(['item', longUrl]);
+    });
+
+    it('should handle special characters in URLs', () => {
+      const url = 'https://example.com/items/test%20item?query=hello&world=1';
+      const key = generateItemQueryKey(url);
+      expect(key).toEqual(['item', url]);
+    });
+  });
+});