Improving Svelte 5 URL State Persistence with useQueryPersistence

[frederikhors]

I've tried many ideas in the past to achieve similar ease of use in Svelte 5 components:

<script lang="ts">
	import type { ListPagination, PlayersListFilters } from '$lib/api';
	import { useQueryPersistence } from '$lib/helpers.svelte';

	useQueryPersistence([
		{
			key: 'pagination',
			defaultValue: { ...PAGINATION.DEFAULT },
			getter: () => pagination,
			setter: (v: ListPagination) => (pagination = v)
		},
		{
			key: 'filters',
			defaultValue: {},
			getter: () => filters,
			setter: (v: PlayerListFilters) => (filters = v),
		},
		{
			key: 'search',
			defaultValue: '',
			getter: () => searchText,
			setter: (v: string) => (searchText = v),
		}
	]);
</script>

What I wanted is to be able to read and write to the URL (as also suggested by Svelte Kit here).

I wrote this code but I think it is far from the perfection that both Svelte and SvelteKit deserve.

Can you help me improve it?

I can then create a PR to suggest this code as an example for the benefit of all, maybe even on sveltesociety.dev.

I tried sveltekit-search-params but it doesn't work as I would like and it's not written in Svelte 5.

The code:

export const isAnEmptyOrFalsyObject = (obj: unknown): boolean => {
	if (!obj || typeof obj !== 'object') return true;

	return Object.entries(obj).every(([, value]) => {
		if (value === null || value === undefined) return true;

		if (typeof value === 'object' && !Array.isArray(value)) {
			return isAnEmptyOrFalsyObject(value);
		}

		if (Array.isArray(value)) {
			return value.length === 0;
		}

		return false;
	});
};

export const mayChangeUrlParam = (
	url: URL,
	key: string,
	thing: Record<string, unknown> | string | number | null | undefined,
	defaultValue?: unknown
): boolean => {
	const param = url.searchParams.get(key);

	let actual: string | null = null;

	try {
		if (typeof thing === 'object') {
			if (defaultValue && JSON.stringify(thing) === JSON.stringify(defaultValue)) {
				actual = null;
			} else {
				actual = isAnEmptyOrFalsyObject(thing) ? null : JSON.stringify(thing);
			}
		} else {
			actual = thing ? JSON.stringify(thing) : null;
		}
	} catch (error) {
		console.warn(`Failed to serialize parameter ${key}:`, error);

		return false;
	}

	if (param === actual) return false;

	if (actual) {
		url.searchParams.set(key, actual);
	} else {
		url.searchParams.delete(key);
	}

	return true;
};

type QuerySlot<T> = {
	key: string;
	defaultValue: T;
	getter: () => T | null | undefined;
	setter: (v: T) => void;
	disabled?: boolean;
};

// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function useQueryPersistence(slots: QuerySlot<any>[], globalDisabled?: boolean) {
	if (globalDisabled) return;

	afterNavigate(({ type, to }) => {
		if (type === 'goto' || !to) return;

		for (const { key, setter, defaultValue, disabled } of slots) {
			if (disabled) continue;

			const param = to.url.searchParams.get(key);

			if (!param) continue;

			try {
				const parsed = JSON.parse(param);

				setter(parsed);
			} catch (err) {
				console.error(`Failed to parse URL parameter "${key}":`, err);

				if (defaultValue !== undefined) {
					setter(defaultValue);
				}
			}
		}
	});

	$effect(() => {
		const url = new URL(page.url);

		let hasChanges = false;

		for (const { key, getter, defaultValue, disabled } of slots) {
			if (disabled) continue;

			const changed = mayChangeUrlParam(url, key, getter(), defaultValue);

			if (changed) hasChanges = true;
		}

		if (hasChanges) {
			goto(url, { replaceState: true, keepFocus: true, noScroll: true });
		}
	});
}

Thanks!