feat: Add sortby field (resolve #23)

Author: oliverroick

README.md

@@ -271,6 +271,8 @@ Option             | Type      | Description
 `setDateRangeFrom(fromDate)` | `function` | Callback to set `dateRangeFrom`. `fromDate` must be ISO representation of a date, ie. `2022-05-18`, or `undefined` to reset.
 `dateRangeTo`      | `string` | The to-date of the search query. `undefined` if unset.
 `setDateRangeTo(toDate)`   | `function` | Callback to set `dateRangeto`. `toDate` must be ISO representation of a date, ie. `2022-05-18`, or `undefined` to reset.
+`sortby`             | `array`   | Specifies the order of results. Array of `{ field: string, direction: 'asc' | 'desc' }`
+`setSortby(sort)`          | `function` | Callback to set `sortby`. `sort` must be an array of `{ field: string, direction: 'asc' | 'desc' }`, or `undefined` to reset.
 `results`          | `object`   | The result of the last search query; a [GeoJSON `FeatureCollection` with additional members](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0-rc.2/fragments/itemcollection/README.md). `undefined` if the search request has not been submitted, or if there was an error. 
 `state`            | `string` | The status of the request. `"IDLE"` before and after the request is sent or received. `"LOADING"` when the request is in progress. 
 `error`            | [`Error`](#error)   | Error information if the last request was unsuccessful. `undefined` if the last request was successful. 

src/hooks/useStacSearch.test.ts

@@ -528,6 +528,30 @@ describe('useStacSearch — API supports POST', () => {
     expect(result.current.results).toEqual({ data: '12345' });
   });
 
+  it('includes sortBy in search', async () => {
+    fetch
+      .mockResponseOnce(
+        JSON.stringify({ links: [{ rel: 'search', method: 'POST' }] }),
+        { url: 'https://fake-stac-api.net' }
+      )
+      .mockResponseOnce(JSON.stringify({ data: '12345' }));
+
+    const { result, waitForNextUpdate } = renderHook(
+      () => useStacSearch(),
+      { wrapper }
+    );
+    await waitForNextUpdate();
+
+    act(() => result.current.setSortby([{ field: 'id', direction: 'asc'}]));
+    act(() => result.current.submit());
+    
+    await waitForNextUpdate();
+
+    const postPayload = parseRequestPayload(fetch.mock.calls[1][1]);
+    expect(postPayload).toEqual({ sortby: [{ field: 'id', direction: 'asc'}], limit: 25 });
+    expect(result.current.results).toEqual({ data: '12345' });
+  });
+
   // it('should reset state with each new StacApi instance', async () => {
   //   const bbox: Bbox = [-0.59, 51.24, 0.30, 51.74];
   //   fetch.mockResponseOnce(JSON.stringify({ data: '12345' }));
@@ -665,4 +689,29 @@ describe('useStacSearch — API supports GET', () => {
     expect(fetch.mock.calls[1][0]).toEqual('https://fake-stac-api.net/search?datetime=..%2F2022-05-17&limit=25');
     expect(result.current.results).toEqual({ data: '12345' });
   });
+
+  it('includes sortby', async () => {
+    fetch
+      .mockResponseOnce(
+        JSON.stringify({ links: [] }),
+        { url: 'https://fake-stac-api.net' }
+      )
+      .mockResponseOnce(JSON.stringify({ data: '12345' }));
+
+    const { result, waitForNextUpdate } = renderHook(
+      () => useStacSearch(),
+      { wrapper }
+    );
+    await waitForNextUpdate();
+
+    act(() => result.current.setSortby([
+      { field: 'id', direction: 'asc' },
+      { field: 'properties.cloud', direction: 'desc' },
+    ]));
+    act(() => result.current.submit());
+    await waitForNextUpdate();
+
+    expect(fetch.mock.calls[1][0]).toEqual('https://fake-stac-api.net/search?limit=25&sortby=%2Bid%2C-properties.cloud');
+    expect(result.current.results).toEqual({ data: '12345' });
+  });
 });

src/hooks/useStacSearch.ts

@@ -8,6 +8,7 @@ import type {
   SearchPayload,
   SearchResponse,
   LinkBody,
+  Sortby
 } from '../types/stac';
 import { useStacApiContext } from '../context';
 
@@ -24,6 +25,8 @@ type StacSearchHook = {
   setDateRangeFrom: (date: string) => void
   dateRangeTo?: string
   setDateRangeTo: (date: string) => void
+  sortby?: Sortby[]
+  setSortby: (sort: Sortby[]) => void
   submit: () => void
   results?: SearchResponse
   state: LoadingState;
@@ -40,6 +43,7 @@ function useStacSearch(): StacSearchHook {
   const [ collections, setCollections ] = useState<CollectionIdList>();
   const [ dateRangeFrom, setDateRangeFrom ] = useState<string>('');
   const [ dateRangeTo, setDateRangeTo ] = useState<string>('');
+  const [ sortby, setSortby ] = useState<Sortby[]>();
   const [ state, setState ] = useState<LoadingState>('IDLE');
   const [ error, setError ] = useState<ApiError>();
 
@@ -53,6 +57,7 @@ function useStacSearch(): StacSearchHook {
     setIds(undefined);
     setDateRangeFrom('');
     setDateRangeTo('');
+    setSortby(undefined);
   };
 
   /**
@@ -78,9 +83,10 @@ function useStacSearch(): StacSearchHook {
       ids,
       bbox,
       collections,
-      dateRange: { from: dateRangeFrom, to: dateRangeTo }
+      dateRange: { from: dateRangeFrom, to: dateRangeTo },
+      sortby
     }),
-    [ ids, bbox, collections, dateRangeFrom, dateRangeTo ]
+    [ ids, bbox, collections, dateRangeFrom, dateRangeTo, sortby ]
   );
 
   /**
@@ -179,6 +185,8 @@ function useStacSearch(): StacSearchHook {
     results,
     state,
     error,
+    sortby,
+    setSortby,
     nextPage: nextPageConfig ? nextPageFn : undefined,
     previousPage: previousPageConfig ? previousPageFn : undefined
   };

src/stac-api/index.ts

@@ -63,7 +63,7 @@ class StacApi {
     }
   }
 
-  payloadToQuery(payload: SearchPayload): string {
+  payloadToQuery({ sortby, ...payload }: SearchPayload): string {
     const queryObj = {};
     for (const [key, value] of Object.entries(payload)) {
       if (!value) continue;
@@ -74,6 +74,13 @@ class StacApi {
         queryObj[key] = value;
       }
     }
+
+    if(sortby) {
+      queryObj['sortby'] = sortby
+        .map(( { field, direction } ) => `${direction === 'asc' ? '+' : '-'}${field}`)
+        .join(',');
+    }
+
     return new URLSearchParams(queryObj).toString();
   }
 

src/types/stac.d.ts

@@ -8,12 +8,17 @@ export type DateRange = {
   from?: string,
   to?: string
 }
+type Sortby = {
+  field: string;
+  direction: 'asc' | 'desc';
+}
 
 export type SearchPayload = {
   ids?: IdList,
   bbox?: Bbox,
   collections?: CollectionIdList,
   dateRange?: DateRange,
+  sortby?: Sortby[]
 }
 
 export type LinkBody = SearchPayload & {