Use sveltekit-search-params to simplify query string manipulation (#168)

## Summary

Simplify client side query string / URL management by using
[sveltekit-search-params](https://github.com/paoloricciuti/sveltekit-search-params).
This is especially helpful to manage types when reading and also
setting/updating values without having to manually use `import { page }
from '$app/stores'` and `import { goto } from '$app/navigation'` in
reactive statements (`$derived`, `$effect`, etc)

Also added `getSearchParamValues(searchParams, paramConfigs)` to
simplify getting value server side, handling type parsing and defaults
with the same configs.

## Checklist
- [ ] Added Unit Tests
- [ ] Covered by existing CI
- [ ] Integration tested
- [ ] Documentation update
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Release Notes

- **New Dependencies**
- Added `sveltekit-search-params` package to improve URL parameter
management.

- **Improvements**
  - Streamlined sorting and metric type selection mechanisms.
  - Enhanced type safety for sort directions and metric types.
- Simplified state management in components, including date range
selection.
- Updated data fetching and sorting logic for improved organization and
performance.

- **Technical Updates**
  - Refactored URL parameter handling across multiple components.
- Updated import and function structures to support new parameter
management approach.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

<!-- av pr metadata
This information is embedded by the av CLI when creating PRs to track
the status of stacks when using Aviator. Please do not delete or edit
this section of the PR.
```
{"parent":"main","parentHead":"","trunk":"main"}
```
-->

---------

Co-authored-by: Sean Lynch <[email protected]>

Author: sean-zlai

frontend/package-lock.json

@@ -48,6 +48,7 @@
 		"svelte-check": "^4.1.1",
 		"svelte-intersection-observer": "^1.0.0",
 		"svelte-radix": "^1.1.1",
+		"sveltekit-search-params": "^4.0.0-next.0",
 		"tailwindcss": "^3.4.17",
 		"typescript": "^5.7.2",
 		"typescript-eslint": "^8.18.1",

frontend/package.json

@@ -1,4 +1,6 @@
 <script lang="ts">
+	import { queryParameters } from 'sveltekit-search-params';
+
 	import { Button } from '$lib/components/ui/button';
 	import { cn } from '$lib/utils';
 
@@ -7,14 +9,7 @@
 	import IconSquare3Stack3d from '~icons/heroicons/square-3-stack-3d-16-solid';
 	import IconXMark from '~icons/heroicons/x-mark-16-solid';
 
-	import { goto } from '$app/navigation';
-	import { page } from '$app/stores';
-	import {
-		getSortDirection,
-		updateContextSort,
-		type SortDirection,
-		type SortContext
-	} from '$lib/util/sort';
+	import { getSortParamKey, type SortContext, getSortParamsConfig } from '$lib/util/sort';
 
 	let {
 		showCluster = false,
@@ -30,14 +25,13 @@
 
 	let activeCluster = showCluster ? 'GroupBys' : null;
 
-	let currentSort: SortDirection = $derived.by(() =>
-		getSortDirection($page.url.searchParams, context)
+	const sortKey = $derived(getSortParamKey(context));
+	const params = $derived(
+		queryParameters(getSortParamsConfig(context), { pushHistory: false, showDefaults: false })
 	);
 
-	function handleSort() {
-		const newSort: SortDirection = currentSort === 'asc' ? 'desc' : 'asc';
-		const url = updateContextSort($page.url, context, newSort);
-		goto(url, { replaceState: true });
+	function toggleSort() {
+		params[sortKey] = params[sortKey] === 'asc' ? 'desc' : 'asc';
 	}
 </script>
 
@@ -61,9 +55,9 @@
 	<!-- Action Buttons Section -->
 	<div class="flex gap-3">
 		{#if showSort}
-			<Button variant="secondary" size="sm" icon="leading" on:click={handleSort}>
+			<Button variant="secondary" size="sm" icon="leading" on:click={toggleSort}>
 				<IconArrowsUpDown />
-				Sort {currentSort === 'asc' ? 'A-Z' : 'Z-A'}
+				Sort {params[sortKey] === 'asc' ? 'A-Z' : 'Z-A'}
 			</Button>
 		{/if}
 		<Button variant="secondary" size="sm" icon="leading" disabled>

frontend/src/lib/components/ActionButtons/ActionButtons.svelte

@@ -1,35 +1,59 @@
 <script lang="ts">
+	import { untrack } from 'svelte';
+	import { queryParameters } from 'sveltekit-search-params';
+	import type { DateRange } from 'bits-ui';
+	import { DateFormatter, getLocalTimeZone, fromAbsolute } from '@internationalized/date';
+
 	import {
 		DATE_RANGE_PARAM,
 		DATE_RANGES,
 		CUSTOM,
 		DATE_RANGE_START_PARAM,
 		DATE_RANGE_END_PARAM,
-		type DateRangeOption,
 		getDateRangeByValue
 	} from '$lib/constants/date-ranges';
 	import { Button } from '$lib/components/ui/button';
 	import { Popover, PopoverContent, PopoverTrigger } from '$lib/components/ui/popover';
 	import IconCalendarDateRange from '~icons/heroicons/calendar-date-range-16-solid';
-	import type { DateRange } from 'bits-ui';
-	import { DateFormatter, getLocalTimeZone, fromAbsolute } from '@internationalized/date';
+
 	import { cn } from '$lib/utils';
 	import { RangeCalendar } from '$lib/components/ui/range-calendar/index';
-	import { goto } from '$app/navigation';
-	import { page } from '$app/stores';
-	import { untrack } from 'svelte';
-	import { parseDateRangeParams } from '$lib/util/date-ranges';
+	import { getDateRangeParamsConfig } from '$lib/util/date-ranges';
+
+	const params = queryParameters(getDateRangeParamsConfig(), {
+		pushHistory: false,
+		showDefaults: false
+	});
 
 	const df = new DateFormatter('en-US', {
 		dateStyle: 'medium'
 	});
 
-	let selectDateRange: DateRangeOption | undefined = $state(undefined);
+	let selectDateRange = $derived(getDateRangeByValue(params[DATE_RANGE_PARAM]));
+
 	let calendarDateRange: DateRange | undefined = $state({
 		start: undefined,
 		end: undefined
 	});
 
+	// Update `calendarDateRange` when `selectDateRange` (preset selection) changes
+	$effect(() => {
+		const selectedRange = selectDateRange?.getRange();
+		const isCustomPreset = selectDateRange?.value === CUSTOM;
+		untrack(() => {
+			calendarDateRange = {
+				start: fromAbsolute(
+					isCustomPreset ? params[DATE_RANGE_START_PARAM] : selectedRange?.[0],
+					getLocalTimeZone()
+				),
+				end: fromAbsolute(
+					isCustomPreset ? params[DATE_RANGE_END_PARAM] : selectedRange?.[1],
+					getLocalTimeZone()
+				)
+			};
+		});
+	});
+
 	let dateRangePopoverOpen = $state(false);
 	let calendarDateRangePopoverOpen = $state(false);
 
@@ -42,40 +66,23 @@
 		if (newSelectedDateRange && newSelectedDateRange.start && newSelectedDateRange.end) {
 			const startDate = newSelectedDateRange.start.toDate(getLocalTimeZone()).getTime();
 			const endDate = newSelectedDateRange.end.toDate(getLocalTimeZone()).getTime();
-			updateURLParams(CUSTOM, startDate.toString(), endDate.toString());
+			updateURLParams(CUSTOM, startDate, endDate);
 			calendarDateRangePopoverOpen = false;
 		}
 	}
 
-	function updateURLParams(range: string, start?: string, end?: string) {
-		const url = new URL($page.url);
-		url.searchParams.set(DATE_RANGE_PARAM, range);
+	function updateURLParams(range: string, start?: number, end?: number) {
+		params[DATE_RANGE_PARAM] = range;
 
 		if (range === CUSTOM && start && end) {
-			url.searchParams.set(DATE_RANGE_START_PARAM, start);
-			url.searchParams.set(DATE_RANGE_END_PARAM, end);
+			params[DATE_RANGE_START_PARAM] = start;
+			params[DATE_RANGE_END_PARAM] = end;
 		} else {
-			url.searchParams.delete(DATE_RANGE_START_PARAM);
-			url.searchParams.delete(DATE_RANGE_END_PARAM);
+			params[DATE_RANGE_START_PARAM] = null;
+			params[DATE_RANGE_END_PARAM] = null;
 		}
-
-		goto(url.toString(), { replaceState: true });
 	}
 
-	$effect(() => {
-		const url = new URL($page.url);
-		untrack(() => {
-			const { dateRangeValue, startTimestamp, endTimestamp } = parseDateRangeParams(
-				url.searchParams
-			);
-			selectDateRange = getDateRangeByValue(dateRangeValue);
-			calendarDateRange = {
-				start: fromAbsolute(Number(startTimestamp), getLocalTimeZone()),
-				end: fromAbsolute(Number(endTimestamp), getLocalTimeZone())
-			};
-		});
-	});
-
 	function getNonCustomDateRanges() {
 		return DATE_RANGES.filter((range) => range.value !== CUSTOM);
 	}

frontend/src/lib/components/DateRangeSelector/DateRangeSelector.svelte

@@ -1,29 +1,25 @@
 <script lang="ts">
+	import { queryParameters } from 'sveltekit-search-params';
+
 	import { Button } from '$lib/components/ui/button';
 	import {
 		METRIC_LABELS,
 		METRIC_TYPES,
-		type MetricType,
-		getMetricTypeFromParams
+		getMetricTypeParamsConfig
 	} from '$lib/types/MetricType/MetricType';
-	import { page } from '$app/stores';
-	import { goto } from '$app/navigation';
-
-	let selected = $derived(getMetricTypeFromParams(new URL($page.url).searchParams));
 
-	function toggle(value: MetricType) {
-		const url = new URL($page.url);
-		url.searchParams.set('metric', value);
-		goto(url, { replaceState: true });
-	}
+	const params = queryParameters(getMetricTypeParamsConfig(), {
+		pushHistory: false,
+		showDefaults: false
+	});
 </script>
 
 <div class="flex space-x-[1px]">
 	{#each METRIC_TYPES as metricType}
 		<Button
-			variant={selected === metricType ? 'default' : 'secondary'}
+			variant={params.metric === metricType ? 'default' : 'secondary'}
 			size="sm"
-			on:click={() => toggle(metricType)}
+			on:click={() => (params.metric = metricType)}
 			class="first:rounded-r-none last:rounded-l-none [&:not(:first-child):not(:last-child)]:rounded-none"
 		>
 			{METRIC_LABELS[metricType]}

frontend/src/lib/components/MetricTypeToggle/MetricTypeToggle.svelte

@@ -61,6 +61,6 @@ export const DATE_RANGES: DateRange[] = [
 
 export type DateRangeOption = (typeof DATE_RANGES)[number];
 
-export function getDateRangeByValue(value: string): DateRange | undefined {
+export function getDateRangeByValue(value: string | null): DateRange | undefined {
 	return DATE_RANGES.find((range) => range.value === value);
 }

frontend/src/lib/constants/date-ranges.ts

@@ -1,3 +1,6 @@
+import type { EncodeAndDecodeOptions } from 'sveltekit-search-params/sveltekit-search-params';
+import { getSearchParamValues } from '$lib/util/search-params';
+
 export const METRIC_TYPES = ['jsd', 'hellinger', 'psi'] as const;
 export type MetricType = (typeof METRIC_TYPES)[number];
 
@@ -15,7 +18,18 @@ export const METRIC_SCALES: Record<MetricType, { min: number; max: number }> = {
 	psi: { min: 0, max: 25 }
 };
 
+export function getMetricTypeParamsConfig() {
+	return {
+		metric: {
+			encode: (value) => value,
+			decode: (value) =>
+				METRIC_TYPES.includes(value as MetricType) ? (value as MetricType) : null,
+			defaultValue: DEFAULT_METRIC_TYPE
+		} satisfies EncodeAndDecodeOptions<MetricType>
+	};
+}
+
 export function getMetricTypeFromParams(searchParams: URLSearchParams): MetricType {
-	const metric = searchParams.get('metric');
-	return METRIC_TYPES.includes(metric as MetricType) ? (metric as MetricType) : DEFAULT_METRIC_TYPE;
+	const paramsConfig = getMetricTypeParamsConfig();
+	return getSearchParamValues(searchParams, paramsConfig).metric;
 }

frontend/src/lib/types/MetricType/MetricType.ts

@@ -1,34 +1,40 @@
+import { ssp } from 'sveltekit-search-params';
+
 import {
 	DATE_RANGE_PARAM,
 	DATE_RANGE_START_PARAM,
 	DATE_RANGE_END_PARAM,
 	PAST_1_WEEK,
 	getDateRangeByValue
 } from '$lib/constants/date-ranges';
+import { getSearchParamValues } from './search-params';
 
 export function getDateRange(range: string): [number, number] {
 	const dateRange = getDateRangeByValue(range);
 	return dateRange ? dateRange.getRange() : getDateRangeByValue(PAST_1_WEEK)!.getRange();
 }
 
-export function parseDateRangeParams(searchParams: URLSearchParams) {
-	const dateRangeValue = searchParams.get(DATE_RANGE_PARAM);
-	const startParam = searchParams.get(DATE_RANGE_START_PARAM);
-	const endParam = searchParams.get(DATE_RANGE_END_PARAM);
+export function getDateRangeParamsConfig() {
+	return {
+		[DATE_RANGE_PARAM]: ssp.string(PAST_1_WEEK),
+		[DATE_RANGE_START_PARAM]: ssp.number(),
+		[DATE_RANGE_END_PARAM]: ssp.number()
+	};
+}
 
-	let startTimestamp: number;
-	let endTimestamp: number;
+export function parseDateRangeParams(searchParams: URLSearchParams) {
+	const paramsConfig = getDateRangeParamsConfig();
+	const paramValues = getSearchParamValues(searchParams, paramsConfig);
 
-	if (startParam && endParam) {
-		startTimestamp = Number(startParam);
-		endTimestamp = Number(endParam);
-	} else {
-		[startTimestamp, endTimestamp] = getDateRange(dateRangeValue || PAST_1_WEEK);
+	if (paramValues[DATE_RANGE_START_PARAM] == null || paramValues[DATE_RANGE_END_PARAM] == null) {
+		const [start, end] = getDateRange(paramValues[DATE_RANGE_PARAM] || PAST_1_WEEK);
+		paramValues[DATE_RANGE_START_PARAM] = start;
+		paramValues[DATE_RANGE_END_PARAM] = end;
 	}
 
 	return {
-		dateRangeValue: dateRangeValue || PAST_1_WEEK,
-		startTimestamp,
-		endTimestamp
+		dateRangeValue: paramValues[DATE_RANGE_PARAM],
+		startTimestamp: paramValues[DATE_RANGE_START_PARAM],
+		endTimestamp: paramValues[DATE_RANGE_END_PARAM]
 	};
 }

frontend/src/lib/util/date-ranges.ts

@@ -0,0 +1,16 @@
+import type { EncodeAndDecodeOptions } from 'sveltekit-search-params/sveltekit-search-params';
+
+/** Get URLSearchParam values from `sveltekit-search-params` config.
+ *  Mostly useful server-side (use `queryParameters()` client side)
+ **/
+export function getSearchParamValues(
+	searchParams: URLSearchParams,
+	paramsConfig: Record<string, EncodeAndDecodeOptions>
+) {
+	const paramEntries = Object.entries(paramsConfig).map(([paramName, paramConfig]) => {
+		const value = searchParams.get(paramName);
+		let decodedValue = paramConfig.decode(value) ?? paramConfig.defaultValue;
+		return [paramName, decodedValue];
+	});
+	return Object.fromEntries(paramEntries);
+}

frontend/src/lib/util/search-params.ts

@@ -1,12 +1,26 @@
 import type { FeatureResponse, JoinTimeSeriesResponse } from '$lib/types/Model/Model';
+import type { EncodeAndDecodeOptions } from 'sveltekit-search-params/sveltekit-search-params';
 
-export type SortDirection = 'asc' | 'desc';
+export const SORT_DIRECTIONS = ['asc', 'desc'] as const;
+export type SortDirection = (typeof SORT_DIRECTIONS)[number];
 export type SortContext = 'drift' | 'distributions';
 
 export function getSortParamKey(context: SortContext): string {
 	return `${context}Sort`;
 }
 
+export function getSortParamsConfig(context: SortContext) {
+	const sortKey = getSortParamKey(context);
+	return {
+		[sortKey]: {
+			encode: (value) => value,
+			decode: (value) =>
+				SORT_DIRECTIONS.includes(value as SortDirection) ? (value as SortDirection) : null,
+			defaultValue: 'asc'
+		} satisfies EncodeAndDecodeOptions<SortDirection>
+	};
+}
+
 export function getSortDirection(
 	searchParams: URLSearchParams,
 	context: SortContext
@@ -15,12 +29,6 @@ export function getSortDirection(
 	return param === 'desc' ? 'desc' : 'asc';
 }
 
-export function updateContextSort(url: URL, context: SortContext, direction: SortDirection): URL {
-	const newUrl = new URL(url);
-	newUrl.searchParams.set(getSortParamKey(context), direction);
-	return newUrl;
-}
-
 export function sortDrift(
 	joinTimeseries: JoinTimeSeriesResponse,
 	direction: SortDirection