sv-router 0.8.1 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="./docs/public/logo.svg" alt="" height="128px">
+<img src="./docs/public/logo.svg" alt="" width="128px" height="128px">
 
 # sv-router
 
@@ -26,6 +26,7 @@ A feature-rich yet intuitive routing library for Svelte single-page apps.
 - 🧩 **Familiar API**: Follows established conventions from popular meta frameworks.
 - 🪶 **Lightweight**: Minimal impact on your bundle size.
 - 🚀 **Made for Svelte 5**: True Svelte 5 implementation with the latest features.
+- #️⃣ **Hash-based routing**: Hash-based routing enables usage in local environments.
 
 ## Getting Started
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sv-router",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",
@@ -47,7 +47,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-svelte": "^3.11.0",
-    "eslint-plugin-unicorn": "^60.0.0",
+    "eslint-plugin-unicorn": "^61.0.2",
     "globals": "^16.3.0",
     "happy-dom": "^18.0.1",
     "prettier": "^3.6.2",

package/src/create-router.svelte.js

@@ -4,8 +4,11 @@ import { matchRoute } from './helpers/match-route.js';
 import { preload, preloadOnHover } from './helpers/preload.js';
 import {
 	constructPath,
+	constructUrl,
 	join,
+	parseSearch,
 	resolveRouteComponents,
+	serializeSearch,
 	stripBase,
 	updatedLocation,
 } from './helpers/utils.js';
@@ -70,7 +73,7 @@ export function createRouter(r) {
 	preloadOnHover(routes);
 
 	return {
-		p: constructPath,
+		p: constructUrl,
 		navigate,
 		isActive,
 		async preload(pathname) {
@@ -90,7 +93,7 @@ export function createRouter(r) {
 				return /** @type {import('./index.d.ts').Path<T>} */ (stripBase(location.pathname));
 			},
 			get search() {
-				return location.search;
+				return parseSearch(location.search);
 			},
 			get state() {
 				return location.state;
@@ -107,7 +110,10 @@ export function createRouter(r) {
 
 /**
  * @param {string | number} path
- * @param {import('./index.d.ts').NavigateOptions & { params?: Record<string, string> }} options
+ * @param {import('./index.d.ts').NavigateOptions & {
+ * 	params?: Record<string, string>;
+ * 	search?: import('./index.d.ts').Search;
+ * }} options
  */
 function navigate(path, options = {}) {
 	if (typeof path === 'number') {
@@ -116,37 +122,14 @@ function navigate(path, options = {}) {
 	}
 
 	path = constructPath(path, options.params);
-	if (options.search && !options.search.startsWith('?')) {
-		options.search = '?' + options.search;
-	}
-	if (options.hash && !options.hash.startsWith('#') && base.name !== '#') {
-		options.hash = '#' + options.hash;
-	}
 	if (base.name === '#') {
 		path = new URL(path).hash;
+	} else if (options.hash && !options.hash.startsWith('#')) {
+		options.hash = '#' + options.hash;
 	}
 	onNavigate(path, options);
 }
 
-/** @param {string} [path] */
-function getMatchPath(path) {
-	let matchPath = '';
-
-	if (path) {
-		matchPath = path;
-	} else if (base.name === '#') {
-		matchPath = globalThis.location.hash.slice(1);
-	} else {
-		matchPath = globalThis.location.pathname;
-	}
-
-	if (base.name && matchPath.startsWith(base.name)) {
-		matchPath = matchPath.slice(base.name.length) || '/';
-	}
-
-	return stripBase(matchPath);
-}
-
 /**
  * @param {string} [path]
  * @param {import('./index.d.ts').NavigateOptions} options
@@ -162,16 +145,19 @@ export async function onNavigate(path, options = {}) {
 	let matchPath = getMatchPath(path);
 	const { match, layouts, hooks, meta: newMeta, params: newParams } = matchRoute(matchPath, routes);
 
+	const search = parseSearch(options.search);
+	const hooksContext = { pathname: matchPath, meta: newMeta, ...options, search };
+
 	let errorHooks = [];
 	for (const hook of hooks) {
 		try {
 			const { beforeLoad } = hook;
 			errorHooks.push(hook);
 			pendingNavigationIndex = currentNavigationIndex;
-			await beforeLoad?.({ pathname: matchPath, meta: newMeta, ...options });
+			await beforeLoad?.(hooksContext);
 		} catch (error) {
 			for (const { onError } of errorHooks) {
-				void onError?.(error, { pathname: matchPath, meta: newMeta, ...options });
+				void onError?.(error, hooksContext);
 			}
 			return;
 		}
@@ -184,7 +170,7 @@ export async function onNavigate(path, options = {}) {
 		routeComponents = await resolveRouteComponents(match ? [...layouts, match] : layouts);
 	} catch (error) {
 		for (const { onError } of hooks) {
-			void onError?.(error, { pathname: matchPath, meta: newMeta, ...options });
+			void onError?.(error, hooksContext);
 		}
 		throw error;
 	}
@@ -196,18 +182,18 @@ export async function onNavigate(path, options = {}) {
 	}
 
 	if (path) {
-		let url = new URL(globalThis.location.toString());
-		url.search = '';
-		if (options.search) url.search = options.search;
+		const search = serializeSearch(options.search);
+		const url = new URL(globalThis.location.toString());
+		url.search = search || '';
+		url.hash = options.hash || '';
 		if (base.name === '#') {
 			url.hash = path;
 		} else {
-			if (options.hash) path += options.hash;
 			url.pathname = base.name ? join(base.name, path) : path;
 		}
 		const historyMethod = options.replace ? 'replaceState' : 'pushState';
 		globalThis.history[historyMethod](options.state || {}, '', url.toString());
-		syncSearchParams(options.search);
+		syncSearchParams(search);
 	} else {
 		syncSearchParams(globalThis.location.search);
 	}
@@ -228,8 +214,27 @@ export async function onNavigate(path, options = {}) {
 	}
 
 	for (const { afterLoad } of hooks) {
-		void afterLoad?.({ pathname: matchPath, meta: newMeta, ...options });
+		void afterLoad?.(hooksContext);
+	}
+}
+
+/** @param {string} [path] */
+function getMatchPath(path) {
+	let matchPath = '';
+
+	if (path) {
+		matchPath = path;
+	} else if (base.name === '#') {
+		matchPath = globalThis.location.hash.slice(1);
+	} else {
+		matchPath = globalThis.location.pathname;
 	}
+
+	if (base.name && matchPath.startsWith(base.name)) {
+		matchPath = matchPath.slice(base.name.length) || '/';
+	}
+
+	return stripBase(matchPath);
 }
 
 /** @param {Event} event */

package/src/gen/generate-router-code.js

@@ -18,7 +18,7 @@ const META_FILENAME_REGEX = /(?<=[/.]|^)(meta)(\.svelte)?\.(js|ts)$/; // meta.js
 
 /**
  * @param {string} routesPath
- * @param {{ allLazy?: boolean }} [options]
+ * @param {{ allLazy?: boolean; js?: boolean }} [options]
  * @returns {string}
  */
 export function generateRouterCode(routesPath, options) {
@@ -110,8 +110,15 @@ export function createRouteMap(fileTree, prefix = '') {
 			result['/' + filePathToRoute(entry.replace('.svelte', ''))] = prefix + entry;
 		} else {
 			const entryName = filePathToRoute(entry.name);
-			const paramFolder = entryName.replace(/^\[(.*)\]$/, ':$1');
-			result['/' + paramFolder] = createRouteMap(entry.tree, prefix + entryName + '/');
+			const isRouteGroup = /^_[^_[]/.test(entry.name);
+
+			if (isRouteGroup) {
+				const childMap = createRouteMap(entry.tree, prefix + entryName + '/');
+				mergeRouteGroup(result, childMap);
+			} else {
+				const paramFolder = entryName.replace(/^\[(.*)\]$/, ':$1');
+				result['/' + paramFolder] = createRouteMap(entry.tree, prefix + entryName + '/');
+			}
 		}
 	}
 	return result;
@@ -127,13 +134,45 @@ function filePathToRoute(filename) {
 	return filename.replaceAll(/\.(?!\.\.)/g, '/');
 }
 
+/**
+ * @param {GeneratedRoutes} result
+ * @param {GeneratedRoutes} childMap
+ */
+function mergeRouteGroup(result, childMap) {
+	const layout = childMap.layout;
+	const hooks = childMap.hooks;
+	const meta = childMap.meta;
+
+	for (const [key, val] of Object.entries(childMap)) {
+		if (key === 'layout' || key === 'hooks' || key === 'meta') {
+			continue;
+		}
+
+		/** @type {GeneratedRoutes} */
+		let routeWithGroupFiles = {};
+		if (typeof val === 'string') {
+			routeWithGroupFiles = { '/': val };
+		} else {
+			routeWithGroupFiles = { ...val };
+		}
+		if (layout) routeWithGroupFiles.layout = layout;
+		if (hooks) routeWithGroupFiles.hooks = hooks;
+		if (meta) routeWithGroupFiles.meta = meta;
+		if (result[key]) {
+			throw new Error(`Route conflict at \`${key}\``);
+		}
+
+		result[key] = routeWithGroupFiles;
+	}
+}
+
 /**
  * @param {GeneratedRoutes} routes
  * @param {string} routesPath
- * @param {{ allLazy?: boolean }} [options]
+ * @param {{ allLazy?: boolean; js?: boolean }} [options]
  * @returns {string}
  */
-export function createRouterCode(routes, routesPath, { allLazy = false } = {}) {
+export function createRouterCode(routes, routesPath, { allLazy = false, js = false } = {}) {
 	if (!routesPath.endsWith('/')) {
 		routesPath += '/';
 	}
@@ -178,8 +217,9 @@ export function createRouterCode(routes, routesPath, { allLazy = false } = {}) {
 		...imports,
 		'',
 		`const routes = ${stringifiedRoutes};`,
-		'export type Routes = typeof routes;',
+		...(js ? [] : ['export type Routes = typeof routes;']),
 		'export const { p, navigate, isActive, preload, route } = createRouter(routes);',
+		'',
 	].join('\n');
 }
 
@@ -213,6 +253,7 @@ export function pathToCorrectCasing(value) {
 	parts.push(...lastPart.split('-'));
 
 	const uppercased = parts.map((part, index) => {
+		part = part.replace(/^_+/, '');
 		if (index === 0 && (lastPart === 'hooks' || lastPart === 'meta')) return part;
 		part = part.replace(/^\[(.*)\]$/, '$1');
 		return part.charAt(0).toUpperCase() + part.slice(1);

package/src/gen/write-router-code.js

@@ -32,7 +32,10 @@ export function writeRouterCode() {
 		writeFileIfDifferent(genConfig.tsconfigPath, JSON.stringify(tsConfig, undefined, 2));
 
 		// Write `.router/router.ts` file
-		const routerCode = generateRouterCode(genConfig.routesPath, { allLazy: genConfig.allLazy });
+		const routerCode = generateRouterCode(genConfig.routesPath, {
+			allLazy: genConfig.allLazy,
+			js: genConfig.routesInJs,
+		});
 		const written = writeFileIfDifferent(genConfig.routerPath, routerCode);
 
 		if (written) {

package/src/helpers/preload.js

@@ -1,5 +1,9 @@
 import { matchRoute } from './match-route.js';
-import { resolveRouteComponents } from './utils.js';
+import { parseSearch, resolveRouteComponents, stripBase } from './utils.js';
+
+const PREDICT_CONE_LENGTH = 200;
+const PREDICT_CONE_ANGLE = Math.PI / 6;
+const PREDICT_TIMEOUT = 50;
 
 /**
  * @param {import('../index.js').Routes} routes
@@ -9,35 +13,181 @@ import { resolveRouteComponents } from './utils.js';
 export async function preload(routes, path, options) {
 	const { match, layouts, hooks, meta } = matchRoute(path, routes);
 	for (const { onPreload } of hooks) {
-		void onPreload?.({ pathname: path, meta, ...options });
+		void onPreload?.({
+			pathname: path,
+			meta,
+			...options,
+			search: parseSearch(options?.search),
+		});
 	}
 	await resolveRouteComponents(match ? [...layouts, match] : layouts);
 }
 
+/** @type {Set<HTMLAnchorElement>} */
 const linkSet = new Set();
+/** @type {Set<HTMLAnchorElement>} */
+const predictedLinks = new Set();
 
 /** @param {import('../index.js').Routes} routes */
 export function preloadOnHover(routes) {
+	/** @param {HTMLAnchorElement} link */
+	function anchorPreload(link) {
+		const href = link.getAttribute('href');
+		if (!href) return;
+		const url = new URL(link.href);
+		const pathname = stripBase(url.pathname);
+		const { replace, state } = link.dataset;
+		preload(routes, pathname, {
+			replace: replace === '' || replace === 'true',
+			search: url.search,
+			state,
+			hash: url.hash,
+		});
+	}
+
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let throttleTimer = null;
+	function pointerMoveListener(/** @type {PointerEvent} */ event) {
+		if (!event.getPredictedEvents || throttleTimer) return;
+		throttleTimer = setTimeout(() => {
+			throttleTimer = null;
+		}, PREDICT_TIMEOUT);
+
+		if (predictedLinks.size === 0) {
+			document.removeEventListener('pointermove', pointerMoveListener);
+			return;
+		}
+
+		const predictedEvents = event.getPredictedEvents();
+		const lastPredicted = predictedEvents.at(-1);
+		if (!lastPredicted) return;
+
+		const currentX = event.clientX;
+		const currentY = event.clientY;
+		const dx = lastPredicted.clientX - currentX;
+		const dy = lastPredicted.clientY - currentY;
+
+		const distance = Math.hypot(dx, dy);
+		if (distance < 2) return;
+		const dirX = dx / distance;
+		const dirY = dy / distance;
+
+		// Visualize the cone (comment out when not debugging)
+		/*
+		const canvas = document.createElement('canvas');
+		canvas.style.position = 'fixed';
+		canvas.style.left = '0';
+		canvas.style.top = '0';
+		canvas.style.width = '100%';
+		canvas.style.height = '100%';
+		canvas.style.pointerEvents = 'none';
+		canvas.style.zIndex = '99999';
+		canvas.width = window.innerWidth;
+		canvas.height = window.innerHeight;
+		document.body.append(canvas);
+		const ctx = canvas.getContext('2d');
+		ctx.fillStyle = 'rgba(255, 0, 0, 0.3)';
+		ctx.strokeStyle = 'rgba(255, 0, 0, 0.6)';
+		ctx.lineWidth = 2;
+		ctx.beginPath();
+		ctx.moveTo(currentX, currentY);
+		const leftAngle = Math.atan2(dirY, dirX) - PREDICT_CONE_ANGLE;
+		const rightAngle = Math.atan2(dirY, dirX) + PREDICT_CONE_ANGLE;
+		const leftX = currentX + Math.cos(leftAngle) * PREDICT_CONE_LENGTH;
+		const leftY = currentY + Math.sin(leftAngle) * PREDICT_CONE_LENGTH;
+		ctx.lineTo(leftX, leftY);
+		ctx.arc(currentX, currentY, PREDICT_CONE_LENGTH, leftAngle, rightAngle, false);
+		ctx.lineTo(currentX, currentY);
+		ctx.closePath();
+		ctx.fill();
+		ctx.stroke();
+		setTimeout(() => canvas.remove(), PREDICT_TIMEOUT);
+		*/
+
+		outer: for (const link of predictedLinks) {
+			if (!link.isConnected) {
+				predictedLinks.delete(link);
+			}
+			const rect = link.getBoundingClientRect();
+			const points = [
+				{ x: rect.left, y: rect.top },
+				{ x: rect.right, y: rect.top },
+				{ x: rect.left, y: rect.bottom },
+				{ x: rect.right, y: rect.bottom },
+				{ x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+			];
+
+			for (const point of points) {
+				const toPointX = point.x - currentX;
+				const toPointY = point.y - currentY;
+				const distToPoint = Math.hypot(toPointX, toPointY);
+				if (distToPoint > PREDICT_CONE_LENGTH || distToPoint < 0.001) continue;
+
+				const toPointDirX = toPointX / distToPoint;
+				const toPointDirY = toPointY / distToPoint;
+				const dotProduct = dirX * toPointDirX + dirY * toPointDirY;
+				const angle = Math.acos(Math.max(-1, Math.min(1, dotProduct)));
+
+				if (angle <= PREDICT_CONE_ANGLE) {
+					anchorPreload(link);
+					predictedLinks.delete(link);
+					continue outer;
+				}
+			}
+		}
+	}
+
+	const intersectionObserver = new IntersectionObserver((entries) => {
+		for (const entry of entries) {
+			if (entry.isIntersecting) {
+				intersectionObserver.unobserve(entry.target);
+				anchorPreload(/** @type {HTMLAnchorElement} */ (entry.target));
+			}
+		}
+	});
+
 	const observer = new MutationObserver(() => {
 		const links = /** @type {NodeListOf<HTMLAnchorElement>} */ (
 			document.querySelectorAll('a[data-preload]')
 		);
+
 		for (const link of links) {
 			if (linkSet.has(link)) continue;
 			linkSet.add(link);
 
-			link.addEventListener('mouseenter', function callback() {
-				link.removeEventListener('mouseenter', callback);
-				const href = link.getAttribute('href');
-				if (!href) return;
-				const url = new URL(link.href);
-				const { replace, state } = link.dataset;
-				preload(routes, href, {
-					replace: replace === '' || replace === 'true',
-					search: url.search,
-					state,
-					hash: url.hash,
-				});
+			switch (link.dataset.preload) {
+				case '':
+				case 'hover': {
+					link.addEventListener('mouseenter', function callback() {
+						link.removeEventListener('mouseenter', callback);
+						anchorPreload(link);
+					});
+					break;
+				}
+				case 'predict': {
+					if (predictedLinks.size === 0) {
+						document.addEventListener('pointermove', pointerMoveListener);
+					}
+					predictedLinks.add(link);
+					break;
+				}
+				case 'viewport': {
+					intersectionObserver.observe(link);
+					break;
+				}
+				default: {
+					console.warn(
+						`Unknown preload strategy \`${link.dataset.preload}\` on`,
+						link,
+						'\nAvailable strategies are: hover, viewport, predict',
+					);
+					break;
+				}
+			}
+
+			link.addEventListener('focus', function callback() {
+				link.removeEventListener('focus', callback);
+				anchorPreload(link);
 			});
 		}
 	});

package/src/helpers/utils.js

@@ -2,13 +2,13 @@ import { base } from '../create-router.svelte.js';
 
 /**
  * @param {string} path
- * @param {Record<string, string>} [params]
+ * @param {Record<string, string | number | boolean>} [params]
  * @returns {string}
  */
 export function constructPath(path, params) {
 	if (params) {
 		for (const key in params) {
-			path = path.replace(`:${key}`, params[key]);
+			path = path.replace(`:${key}`, String(params[key]));
 		}
 	}
 
@@ -23,6 +23,24 @@ export function constructPath(path, params) {
 	return path;
 }
 
+/**
+ * @param {string} path
+ * @param {import('../index.d.ts').ConstructUrlOptions & {
+ * 	params?: Record<string, string | number | boolean>;
+ * }} [options]
+ * @returns {string}
+ */
+export function constructUrl(path, options) {
+	let result = constructPath(path, options?.params);
+	if (options?.search) {
+		result += serializeSearch(options.search);
+	}
+	if (options?.hash && !options.hash.startsWith('#')) {
+		result += '#' + options.hash;
+	}
+	return result;
+}
+
 /**
  * @param {import('../index.d.ts').RouteComponent[]} input
  * @returns {Promise<import('svelte').Component[]>}
@@ -95,3 +113,69 @@ export function updatedLocation() {
 		hash,
 	};
 }
+
+/**
+ * @param {import('../index.d.ts').Search} [value]
+ * @returns {string | undefined}
+ */
+export function serializeSearch(value) {
+	if (!value) {
+		return;
+	}
+
+	if (typeof value === 'string') {
+		if (!value.startsWith('?')) {
+			value = '?' + value;
+		}
+		return value;
+	}
+
+	const stringValues = Object.fromEntries(
+		Object.entries(value).map(([key, value]) => [key, String(value)]),
+	);
+	if (Object.keys(stringValues).length === 0) {
+		return;
+	}
+	const urlSearchParams = new URLSearchParams(stringValues);
+	return '?' + urlSearchParams.toString();
+}
+
+/**
+ * @param {import('../index.d.ts').Search} [value]
+ * @returns {Record<string, string | number | boolean>}
+ */
+export function parseSearch(value) {
+	if (!value) {
+		return {};
+	}
+
+	if (typeof value === 'string') {
+		const searchParams = new URLSearchParams(value);
+		return Object.fromEntries(
+			searchParams.entries().map(([key, value]) => [key, parseSearchValue(value)]),
+		);
+	}
+
+	return value;
+}
+
+/**
+ * @param {string} value
+ * @returns {string | number | boolean}
+ */
+export function parseSearchValue(value) {
+	if (value === '') {
+		return '';
+	}
+	if (value === 'true') {
+		return true;
+	}
+	if (value === 'false') {
+		return false;
+	}
+	const number = Number(value);
+	if (!Number.isNaN(number)) {
+		return number;
+	}
+	return value;
+}

package/src/index.d.ts

@@ -12,6 +12,9 @@ import type { Action } from 'svelte/action';
  */
 export const isActiveLink: IsActiveLink;
 
+/** Create a search string from the search object that is provided in hooks. */
+export function serializeSearch(search: Search): string | undefined;
+
 /**
  * Setup a new router instance with the given routes.
  *
@@ -183,7 +186,7 @@ export type RouterApi<T extends Routes> = {
 		/** The reactive pathname of the URL. */
 		pathname: (Path<T, true> & {}) | (string & {});
 		/** The reactive query string part of the URL. */
-		search: string;
+		search: Record<string, string | number | boolean>;
 		/** The reactive history state that can be passed to the `navigate` function. */
 		state: unknown;
 		/** The reactive hash part of the URL. */
@@ -198,7 +201,9 @@ export type Path<T extends Routes, AnyParam extends boolean = false> = RemovePar
 >;
 
 export type ConstructPathArgs<TPath extends string> = {
-	[Path in TPath]: PathParams<Path> extends never ? [Path] : [Path, PathParams<Path>];
+	[Path in TPath]: PathParams<Path> extends never
+		? [Path] | [Path, ConstructUrlOptions]
+		: [Path, ConstructUrlOptions & { params: PathParams<Path> }];
 }[TPath];
 
 export type IsActiveArgs<
@@ -223,19 +228,21 @@ export type AllParams<TRoutes extends Routes> = Partial<
 	Record<ExtractParams<RemoveParenthesis<RecursiveKeys<TRoutes>>>, string>
 >;
 
+export type Search = string | Record<string, string | number | boolean>;
+
 export type HooksContext = {
 	hash?: string;
 	meta: RouteMeta;
 	pathname: string;
 	replace?: boolean;
-	search?: string;
+	search: Record<string, string | number | boolean>;
 	state?: string;
 };
 
 export type NavigateOptions =
 	| {
 			replace?: boolean;
-			search?: string;
+			search?: Search;
 			state?: string;
 			hash?: string;
 			scrollToTop?: ScrollBehavior | false;
@@ -243,17 +250,31 @@ export type NavigateOptions =
 	  }
 	| undefined;
 
-export type SearchParams = Omit<URLSearchParams, 'append' | 'delete' | 'set' | 'sort'> & {
-	append: (name: string, value: string, options?: { replace?: boolean }) => void;
-	delete: (name: string, value?: string, options?: { replace?: boolean }) => void;
-	set: (name: string, value: string, options?: { replace?: boolean }) => void;
-	sort: (options?: { replace?: boolean }) => void;
+export type ConstructUrlOptions =
+	| {
+			search?: Search;
+			hash?: string;
+	  }
+	| undefined;
+
+export type SearchParams = Omit<
+	URLSearchParams,
+	'append' | 'delete' | 'entries' | 'get' | 'getAll' | 'set' | 'sort' | 'values'
+> & {
+	append(name: string, value: string | number | boolean, options?: { replace?: boolean }): void;
+	delete(name: string, value?: string | number | boolean, options?: { replace?: boolean }): void;
+	entries(): IterableIterator<[string, string | number | boolean]>;
+	get(name: string): string | number | boolean | null;
+	getAll(name: string): (string | number | boolean)[];
+	set(name: string, value: string | number | boolean, options?: { replace?: boolean }): void;
+	sort(options?: { replace?: boolean }): void;
+	values(): IterableIterator<string | number | boolean>;
 };
 
 type NavigateArgs<T extends string> =
 	| (PathParams<T> extends never
-			? [T] | [T, NavigateOptions]
-			: [T, NavigateOptions & { params: PathParams<T> }])
+			? [T] | [T, Omit<NavigateOptions, 'search'> & { search: Search }]
+			: [T, Omit<NavigateOptions, 'search'> & { search: Search; params: PathParams<T> }])
 	| [number];
 
 type StripNonRoutes<T extends Routes> = {

package/src/index.js

@@ -1,4 +1,5 @@
 export { isActiveLink } from './actions.svelte.js';
 export { createRouter } from './create-router.svelte.js';
+export { serializeSearch } from './helpers/utils.js';
 export { default as Router } from './Router.svelte';
 export { searchParams } from './search-params.svelte.js';

package/src/search-params.svelte.js

@@ -1,29 +1,31 @@
 import { SvelteURLSearchParams } from 'svelte/reactivity';
+import { parseSearchValue } from './helpers/utils.js';
 
 let searchParams = new SvelteURLSearchParams(globalThis.location.search);
 
 /** @type {import('./index.js').SearchParams} */
 const shell = {
 	append(name, value, options) {
-		searchParams.append(name, value);
+		searchParams.append(name, String(value));
 		updateUrlSearchParams(options);
 	},
 	delete(name, value, options) {
-		searchParams.delete(name, value);
+		searchParams.delete(name, value === undefined ? undefined : String(value));
 		updateUrlSearchParams(options);
 	},
 	entries() {
-		return searchParams.entries();
+		return searchParams.entries().map(([key, value]) => [key, parseSearchValue(value)]);
 	},
 	forEach(...args) {
-		// eslint-disable-next-line unicorn/no-array-for-each
 		return searchParams.forEach(...args);
 	},
 	get(...args) {
-		return searchParams.get(...args);
+		const value = searchParams.get(...args);
+		if (value === null) return null;
+		return parseSearchValue(value);
 	},
 	getAll(...args) {
-		return searchParams.getAll(...args);
+		return searchParams.getAll(...args).map(parseSearchValue);
 	},
 	has(...args) {
 		return searchParams.has(...args);
@@ -32,7 +34,7 @@ const shell = {
 		return searchParams.keys();
 	},
 	set(name, value, options) {
-		searchParams.set(name, value);
+		searchParams.set(name, String(value));
 		updateUrlSearchParams(options);
 	},
 	sort(options) {
@@ -43,7 +45,7 @@ const shell = {
 		return searchParams.toString();
 	},
 	values() {
-		return searchParams.values();
+		return searchParams.values().map(parseSearchValue);
 	},
 	get size() {
 		return searchParams.size;
@@ -57,19 +59,23 @@ export { shell as searchParams };
 
 /** @param {string} [search] */
 export function syncSearchParams(search) {
-	if (searchParams.toString() !== search) {
-		searchParams = new SvelteURLSearchParams();
-		const newSearchParams = new URLSearchParams(search);
-		for (const [key, value] of newSearchParams.entries()) {
-			searchParams.append(key, value);
+	if (searchParams.toString() === search) {
+		return;
+	}
+	const newSearch = new URLSearchParams(search);
+	for (const [key, value] of newSearch) {
+		searchParams.set(key, value);
+	}
+	for (const key of searchParams.keys()) {
+		if (!newSearch.has(key)) {
+			searchParams.delete(key);
 		}
 	}
 }
 
 /** @param {{ replace?: boolean }} [options] */
 function updateUrlSearchParams(options) {
-	let url = new URL(globalThis.location.toString());
+	const url = new URL(globalThis.location.toString());
 	url.search = searchParams.toString();
-
 	globalThis.history[options?.replace ? 'replaceState' : 'pushState']({}, '', url);
 }