sv-router 0.8.0 → 0.9.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.0",
+  "version": "0.9.0",
   "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",

package/src/RecursiveComponentTree.svelte

@@ -1,5 +1,4 @@
 <script>
-	import { params } from './create-router.svelte.js';
 	import RecursiveComponentTree from './RecursiveComponentTree.svelte';
 
 	/** @type {{ tree: import('svelte').Component[] }} */
@@ -9,10 +8,8 @@
 	const restTree = $derived(tree.slice(1));
 </script>
 
-{#key restTree.length > 0 || Object.values(params.value)}
-	<FirstComponent>
-		{#if restTree.length > 0}
-			<RecursiveComponentTree tree={restTree}></RecursiveComponentTree>
-		{/if}
-	</FirstComponent>
-{/key}
+<FirstComponent>
+	{#if restTree.length > 0}
+		<RecursiveComponentTree tree={restTree}></RecursiveComponentTree>
+	{/if}
+</FirstComponent>

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';
@@ -22,11 +25,11 @@ export const base = {
 /** @type {{ value: import('svelte').Component[] }} */
 export let componentTree = $state({ value: [] });
 
-/** @type {{ value: Record<string, string> }} */
-export let params = $state({ value: {} });
-
 export let location = $state(updatedLocation());
 
+/** @type {{ value: Record<string, string> }} */
+let params = $state({ value: {} });
+
 let meta = $state({ value: {} });
 
 let navigationIndex = 0;
@@ -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) {
@@ -130,10 +130,10 @@ function filePathToRoute(filename) {
 /**
  * @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 +178,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');
 }
 

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/match-route.js

@@ -67,6 +67,7 @@ export function matchRoute(pathname, routes) {
 				}
 				if (breakFromLayouts) {
 					routePart = `(${routePart})`;
+					layouts = [];
 				} else if ('layout' in routes && routes.layout) {
 					layouts.push(routes.layout);
 				}

package/src/helpers/preload.js

@@ -1,5 +1,5 @@
 import { matchRoute } from './match-route.js';
-import { resolveRouteComponents } from './utils.js';
+import { parseSearch, resolveRouteComponents } from './utils.js';
 
 /**
  * @param {import('../index.js').Routes} routes
@@ -9,7 +9,12 @@ 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);
 }

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,66 @@ 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)]),
+	);
+	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

@@ -183,7 +183,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 +198,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 +225,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 +247,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/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);
 }