sv-router 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sv-router",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",
@@ -36,24 +36,24 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.3",
-    "@eslint/js": "^9.26.0",
-    "@types/node": "^22.15.15",
-    "eslint": "^9.26.0",
-    "eslint-config-prettier": "^10.1.3",
+    "@changesets/cli": "^2.29.4",
+    "@eslint/js": "^9.28.0",
+    "@types/node": "^22.15.30",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-svelte": "^3.5.1",
+    "eslint-plugin-svelte": "^3.9.1",
     "eslint-plugin-unicorn": "^59.0.1",
-    "globals": "^16.1.0",
+    "globals": "^16.2.0",
     "prettier": "^3.5.3",
     "prettier-plugin-jsdoc": "^1.3.2",
-    "prettier-plugin-svelte": "^3.3.3",
-    "svelte-check": "^4.1.7",
+    "prettier-plugin-svelte": "^3.4.0",
+    "svelte-check": "^4.2.1",
     "type-testing": "^0.2.0",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.0",
+    "typescript-eslint": "^8.33.1",
     "vite": "^6.3.5",
-    "vitest": "^3.1.3"
+    "vitest": "^3.2.2"
   },
   "peerDependencies": {
     "svelte": "^5"

package/src/create-router.svelte.js

@@ -2,7 +2,7 @@ import { BROWSER, DEV } from 'esm-env';
 import { isActive } from './helpers/is-active.js';
 import { matchRoute } from './helpers/match-route.js';
 import { preload, preloadOnHover } from './helpers/preload.js';
-import { constructPath, join, resolveRouteComponents } from './helpers/utils.js';
+import { constructPath, join, resolveRouteComponents, updatedLocation } from './helpers/utils.js';
 import { syncSearchParams } from './search-params.svelte.js';
 
 /** @type {import('./index.d.ts').Routes} */
@@ -16,6 +16,8 @@ export let params = $state({ value: {} });
 
 export let location = $state(updatedLocation());
 
+let meta = $state({ value: {} });
+
 let navigationIndex = 0;
 let pendingNavigationIndex = 0;
 
@@ -51,6 +53,12 @@ export function createRouter(r) {
 			get params() {
 				return params.value;
 			},
+			getParams(pathname) {
+				if (!isActive(pathname)) {
+					throw new Error(`\`${pathname}\` does not match the current route`);
+				}
+				return params.value;
+			},
 			get pathname() {
 				return /** @type {import('./index.d.ts').Path<T>} */ (location.pathname);
 			},
@@ -63,6 +71,9 @@ export function createRouter(r) {
 			get hash() {
 				return location.hash;
 			},
+			get meta() {
+				return meta.value;
+			},
 		},
 	};
 }
@@ -104,12 +115,12 @@ export async function onNavigate(path, options = {}) {
 	if (base.name && matchPath.startsWith(base.name)) {
 		matchPath = matchPath.slice(base.name.length) || '/';
 	}
-	const { match, layouts, hooks, params: newParams } = matchRoute(matchPath, routes);
+	const { match, layouts, hooks, meta: newMeta, params: newParams } = matchRoute(matchPath, routes);
 
 	for (const { beforeLoad } of hooks) {
 		try {
 			pendingNavigationIndex = currentNavigationIndex;
-			await beforeLoad?.();
+			await beforeLoad?.({ pathname: matchPath, ...options });
 		} catch {
 			return;
 		}
@@ -140,7 +151,8 @@ export async function onNavigate(path, options = {}) {
 	} else {
 		componentTree.value = routeComponents;
 	}
-	params.value = newParams || {};
+	params.value = newParams;
+	meta.value = newMeta;
 	syncSearchParams();
 	Object.assign(location, updatedLocation());
 
@@ -149,7 +161,7 @@ export async function onNavigate(path, options = {}) {
 	}
 
 	for (const { afterLoad } of hooks) {
-		afterLoad?.();
+		afterLoad?.({ pathname: matchPath, ...options });
 	}
 }
 
@@ -175,12 +187,3 @@ export function onGlobalClick(event) {
 		viewTransition: viewTransition === '' || viewTransition === 'true',
 	});
 }
-
-function updatedLocation() {
-	return {
-		pathname: globalThis.location.pathname,
-		search: globalThis.location.search,
-		state: history.state,
-		hash: globalThis.location.hash,
-	};
-}

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

@@ -14,6 +14,7 @@ const PARAM_FILENAME_REGEX = /(?<=[/.]|^)\(?\[([\w-]+)\]\)?(\.lazy)?\.svelte$/;
 const CATCH_ALL_FILENAME_REGEX = /(?<=[/.]|^)\(?\[\.\.\.([\w-]+)\]\)?(\.lazy)?\.svelte$/; // [...any].svelte, [...any].lazy.svelte, ([...any]).svelte
 const OUT_OF_LAYOUT_FILENAME_REGEX = /(?<=[/.]|^)\(\[\.?\.?\.?([\w-]+)\]\)(\.lazy)?\.svelte$/; // ([any]).svelte, ([...any]).lazy.svelte
 const HOOKS_FILENAME_REGEX = /(?<=[/.]|^)(hooks)(\.svelte)?\.(js|ts)$/; // hooks.js, hooks.svelte.js, hooks.ts, hooks.svelte.ts
+const META_FILENAME_REGEX = /(?<=[/.]|^)(meta)(\.svelte)?\.(js|ts)$/; // meta.js, meta.svelte.js, meta.ts, meta.svelte.ts
 
 /**
  * @param {string} routesPath
@@ -44,7 +45,11 @@ export function buildFileTree(routesPath) {
 			tree.push({ name: entry, tree: buildFileTree(path.join(routesPath, entry)) });
 			continue;
 		}
-		if (!entry.endsWith('.svelte') && !HOOKS_FILENAME_REGEX.test(entry)) {
+		if (
+			!entry.endsWith('.svelte') &&
+			!HOOKS_FILENAME_REGEX.test(entry) &&
+			!META_FILENAME_REGEX.test(entry)
+		) {
 			continue;
 		}
 		tree.push(entry);
@@ -67,6 +72,10 @@ export function createRouteMap(fileTree, prefix = '') {
 					result['hooks'] = prefix + entry;
 					continue;
 				}
+				if (META_FILENAME_REGEX.test(entry)) {
+					result['meta'] = prefix + entry;
+					continue;
+				}
 				continue;
 			}
 
@@ -101,7 +110,8 @@ export function createRouteMap(fileTree, prefix = '') {
 			result['/' + filePathToRoute(entry.replace('.svelte', ''))] = prefix + entry;
 		} else {
 			const entryName = filePathToRoute(entry.name);
-			result['/' + entryName] = createRouteMap(entry.tree, prefix + entryName + '/');
+			const paramFolder = entryName.replace(/^\[(.*)\]$/, ':$1');
+			result['/' + paramFolder] = createRouteMap(entry.tree, prefix + entryName + '/');
 		}
 	}
 	return result;
@@ -137,7 +147,11 @@ export function createRouterCode(routes, routesPath, { allLazy = false } = {}) {
 		for (const [key, value] of Object.entries(routes)) {
 			if (typeof value === 'object') {
 				result[key] = handleImports(value, routesPath);
-			} else if (key === 'hooks' || (!value.endsWith('.lazy.svelte') && !allLazy)) {
+			} else if (
+				key === 'hooks' ||
+				key === 'meta' ||
+				(!value.endsWith('.lazy.svelte') && !allLazy)
+			) {
 				const variableName = pathToCorrectCasing(value);
 				importsMap.set(variableName, routesPath + value);
 				result[key] = variableName;
@@ -189,6 +203,7 @@ export function pathToCorrectCasing(value) {
 		extractLastPart(CATCH_ALL_FILENAME_REGEX) ||
 		extractLastPart(PARAM_FILENAME_REGEX) ||
 		extractLastPart(HOOKS_FILENAME_REGEX) ||
+		extractLastPart(META_FILENAME_REGEX) ||
 		extractLastPart(FILENAME_REGEX);
 	if (!lastPart) {
 		throw new Error(`Invalid filename: ${value}`);
@@ -196,7 +211,8 @@ export function pathToCorrectCasing(value) {
 	parts.push(...lastPart.split('-'));
 
 	const uppercased = parts.map((part, index) => {
-		if (index === 0 && lastPart === 'hooks') return part;
+		if (index === 0 && (lastPart === 'hooks' || lastPart === 'meta')) return part;
+		part = part.replace(/^\[(.*)\]$/, '$1');
 		return part.charAt(0).toUpperCase() + part.slice(1);
 	});
 	return uppercased.join('');

package/src/helpers/is-active.js

@@ -38,10 +38,12 @@ function compare(compareFn, pathname, params) {
 	const routeParts = location.pathname.split('/').slice(1);
 	for (const [index, pathPart] of pathParts.entries()) {
 		const routePart = routeParts[index];
-		if (routePart.startsWith(':')) {
+		if (pathPart.startsWith(':')) {
 			continue;
 		}
-		return compareFn(pathPart, routePart);
+		if (pathPart !== routePart) {
+			return false;
+		}
 	}
-	return false;
+	return true;
 }

package/src/helpers/match-route.js

@@ -6,6 +6,8 @@
  * @typedef {import('../index.d.ts').Hooks} Hooks
  *
  * @typedef {import('../index.d.ts').Routes} Routes
+ *
+ * @typedef {import('../index.d.ts').RouteMeta} RouteMeta
  */
 
 /**
@@ -15,6 +17,7 @@
  * 	match: RouteComponent | undefined;
  * 	layouts: LayoutComponent[];
  * 	hooks: Hooks[];
+ * 	meta: RouteMeta;
  * 	params: Record<string, string>;
  * 	breakFromLayouts: boolean;
  * }}
@@ -39,6 +42,9 @@ export function matchRoute(pathname, routes) {
 	/** @type {Record<string, string>} */
 	let params = {};
 
+	/** @type {RouteMeta} */
+	let meta = {};
+
 	let breakFromLayouts = false;
 
 	outer: for (const route of allRoutes) {
@@ -69,7 +75,7 @@ export function matchRoute(pathname, routes) {
 				);
 				match = /** @type {RouteComponent} */ (routes[resolvedPath]);
 				break outer;
-			} else if (routePart !== pathPart) {
+			} else if (routePart !== pathPart?.toLowerCase()) {
 				break;
 			}
 
@@ -89,6 +95,10 @@ export function matchRoute(pathname, routes) {
 				hooks.push(routes.hooks);
 			}
 
+			if ('meta' in routes && routes.meta) {
+				meta = { ...meta, ...routes.meta };
+			}
+
 			if (typeof routeMatch === 'function') {
 				if (routeParts.length === pathParts.length) {
 					match = routeMatch;
@@ -103,6 +113,7 @@ export function matchRoute(pathname, routes) {
 				match = result.match;
 				params = { ...params, ...result.params };
 				hooks.push(...result.hooks);
+				meta = { ...meta, ...result.meta };
 				if (result.breakFromLayouts) {
 					layouts = [];
 				} else {
@@ -113,7 +124,7 @@ export function matchRoute(pathname, routes) {
 		}
 	}
 
-	return { match, layouts, hooks, params, breakFromLayouts };
+	return { match, layouts, hooks, params, meta, breakFromLayouts };
 }
 
 /**

package/src/helpers/preload.js

@@ -4,11 +4,12 @@ import { resolveRouteComponents } from './utils.js';
 /**
  * @param {import('../index.js').Routes} routes
  * @param {string} path
+ * @param {import('../index.d.ts').NavigateOptions} [options]
  */
-export async function preload(routes, path) {
+export async function preload(routes, path, options) {
 	const { match, layouts, hooks } = matchRoute(path, routes);
 	for (const { onPreload } of hooks) {
-		onPreload?.();
+		onPreload?.({ pathname: path, ...options });
 	}
 	await resolveRouteComponents(match ? [...layouts, match] : layouts);
 }
@@ -18,7 +19,9 @@ const linkSet = new Set();
 /** @param {import('../index.js').Routes} routes */
 export function preloadOnHover(routes) {
 	const observer = new MutationObserver(() => {
-		const links = document.querySelectorAll('a[data-preload]');
+		const links = /** @type {NodeListOf<HTMLAnchorElement>} */ (
+			document.querySelectorAll('a[data-preload]')
+		);
 		for (const link of links) {
 			if (linkSet.has(link)) continue;
 			linkSet.add(link);
@@ -27,7 +30,14 @@ export function preloadOnHover(routes) {
 				link.removeEventListener('mouseenter', callback);
 				const href = link.getAttribute('href');
 				if (!href) return;
-				preload(routes, href);
+				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,
+				});
 			});
 		}
 	});

package/src/helpers/utils.js

@@ -25,7 +25,7 @@ export function resolveRouteComponents(input) {
  * @param {import('../index.d.ts').RouteComponent} input
  * @returns {Promise<import('svelte').Component>}
  */
-export function resolveRouteComponent(input) {
+function resolveRouteComponent(input) {
 	return new Promise((resolve) => {
 		if (isLazyImport(input)) {
 			Promise.resolve(input()).then((module) => {
@@ -59,3 +59,12 @@ export function join(...parts) {
 	}
 	return result;
 }
+
+export function updatedLocation() {
+	return {
+		pathname: globalThis.location.pathname,
+		search: globalThis.location.search,
+		state: history.state,
+		hash: globalThis.location.hash,
+	};
+}

package/src/helpers/validate-routes.js

@@ -26,9 +26,12 @@ export function validateRoutes(routes) {
 export function getRoutePaths(routes) {
 	const paths = [];
 	for (const [key, value] of Object.entries(routes)) {
+		if (['layout', 'hooks', 'meta'].includes(key)) {
+			continue;
+		}
 		if (typeof value === 'object') {
 			paths.push(
-				...getRoutePaths(value).map((path) => {
+				...getRoutePaths(/** @type {import('../index.d.ts').Routes} */ (value)).map((path) => {
 					if (path === '*') {
 						return key + '/*';
 					}

package/src/index.d.ts

@@ -56,17 +56,17 @@ export type Hooks = {
 	 * You can throw a `navigate` call to redirect to another route.
 	 *
 	 * ```js
-	 * async beforeLoad() {
+	 * async beforeLoad({ pathname }) {
 	 *   await ...
 	 *   throw navigate('/home');
 	 * }
 	 * ```
 	 */
-	beforeLoad?(): void | Promise<void>;
+	beforeLoad?(context: HooksContext): void | Promise<void>;
 	/** A function that will be called after the route is loaded. */
-	afterLoad?(): void;
+	afterLoad?(context: HooksContext): void;
 	/** A function that will be called when the route is preloaded. */
-	onPreload?(): void;
+	onPreload?(context: HooksContext): void;
 };
 
 export type Routes = {
@@ -74,6 +74,7 @@ export type Routes = {
 	[_: `*${string}` | `(*${string})`]: RouteComponent | undefined;
 	layout?: LayoutComponent;
 	hooks?: Hooks;
+	meta?: RouteMeta;
 };
 
 export type IsActiveLink = Action<
@@ -81,6 +82,20 @@ export type IsActiveLink = Action<
 	{ className?: string; startsWith?: boolean } | undefined
 >;
 
+/**
+ * Route metadata that can be extended via module augmentation.
+ *
+ * @example
+ * 	declare module 'sv-router' {
+ * 		interface RouteMeta {
+ * 			public?: boolean;
+ * 			requiresAuth?: boolean;
+ * 		}
+ * 	}
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RouteMeta {}
+
 export type RouterApi<T extends Routes> = {
 	/**
 	 * Construct a path while ensuring type safety.
@@ -147,6 +162,17 @@ export type RouterApi<T extends Routes> = {
 		 * 'hello-world', commentId: '123' }`.
 		 */
 		params: AllParams<T>;
+		/**
+		 * Extract parameters from the given pathname. Will throw if the pathname does not match the
+		 * current route.
+		 *
+		 * ```ts
+		 * route.getParams('/posts/:slug').slug;
+		 * ```
+		 *
+		 * @param pathname
+		 */
+		getParams<U extends Path<T>>(pathname: U): Record<ExtractParams<U>, string>;
 		/** The reactive pathname of the URL. */
 		pathname: (Path<T, true> & {}) | (string & {});
 		/** The reactive query string part of the URL. */
@@ -155,6 +181,8 @@ export type RouterApi<T extends Routes> = {
 		state: unknown;
 		/** The reactive hash part of the URL. */
 		hash: string;
+		/** Arbitrary metadata associated with the route. */
+		meta: RouteMeta;
 	};
 };
 
@@ -177,6 +205,14 @@ export type AllParams<T extends Routes> = Partial<
 	Record<ExtractParams<RemoveParenthesis<RecursiveKeys<T>>>, string>
 >;
 
+export type HooksContext = {
+	pathname: string;
+	replace?: boolean;
+	search?: string;
+	state?: string;
+	hash?: string;
+};
+
 export type NavigateOptions =
 	| {
 			replace?: boolean;
@@ -210,7 +246,9 @@ type StripNonRoutes<T extends Routes> = {
 				? never
 				: K extends 'hooks'
 					? never
-					: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
+					: K extends 'meta'
+						? never
+						: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
 };
 
 type RecursiveKeys<