sv-router 0.0.6 → 0.0.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sv-router",
-  "version": "0.0.6",
-  "description": "Modern Svelte routing",
+  "version": "0.0.7",
+  "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",
     "router",
@@ -36,31 +36,34 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.27.11",
-    "@eslint/js": "^9.18.0",
-    "@types/node": "^22.10.7",
-    "eslint-config-prettier": "^10.0.1",
+    "@changesets/cli": "^2.28.1",
+    "@eslint/js": "^9.21.0",
+    "@types/node": "^22.13.8",
+    "eslint": "^9.21.0",
+    "eslint-config-prettier": "^10.0.2",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-svelte": "^2.46.1",
-    "eslint-plugin-unicorn": "^56.0.1",
-    "globals": "^15.14.0",
-    "prettier": "^3.4.2",
+    "eslint-plugin-svelte": "^3.0.2",
+    "eslint-plugin-unicorn": "^57.0.0",
+    "globals": "^16.0.0",
+    "prettier": "^3.5.2",
     "prettier-plugin-jsdoc": "^1.3.2",
     "prettier-plugin-svelte": "^3.3.3",
+    "svelte-check": "^4.1.4",
     "type-testing": "^0.2.0",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.20.0",
-    "vite": "^6.0.7",
-    "vitest": "^3.0.2"
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.25.0",
+    "vite": "^6.2.0",
+    "vitest": "^3.0.7"
   },
   "peerDependencies": {
     "svelte": "^5"
   },
   "scripts": {
-    "ex:config-based": "pnpm --filter config-based-example",
-    "ex:file-based": "pnpm --filter file-based-example",
+    "docs:dev": "pnpm --filter docs dev",
+    "docs:build": "pnpm --filter docs build",
+    "docs:preview": "pnpm --filter docs preview",
     "test": "vitest",
-    "check": "tsc --noEmit && pnpm -r check",
+    "check": "svelte-check && pnpm -r check",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier . --check",

package/src/Router.svelte

@@ -6,7 +6,7 @@
 	onNavigate();
 
 	$effect(() => {
-		const off1 = on(globalThis, 'popstate', onNavigate);
+		const off1 = on(globalThis, 'popstate', () => onNavigate());
 		const off2 = on(globalThis, 'click', onGlobalClick);
 
 		return () => {

package/src/create-router.svelte.js

@@ -57,40 +57,65 @@ export function createRouter(r) {
 }
 
 /**
- * @param {string} path
+ * @param {string | number} path
  * @param {import('./index.d.ts').NavigateOptions & { params?: Record<string, string> }} options
  */
 function navigate(path, options = {}) {
+	if (typeof path === 'number') {
+		globalThis.history.go(path);
+		return;
+	}
 	if (options.params) {
 		path = constructPath(path, options.params);
 	}
-	if (options.search) {
-		path += (options.search.startsWith('?') ? '' : '?') + options.search;
+	if (options.search && !options.search.startsWith('?')) {
+		options.search = '?' + options.search;
 	}
-	if (options.hash) {
-		path += options.hash;
+	if (options.hash && !options.hash.startsWith('#')) {
+		options.hash = '#' + options.hash;
 	}
-	const historyMethod = options.replace ? 'replaceState' : 'pushState';
-	globalThis.history[historyMethod](options.state || {}, '', path);
-	onNavigate();
+	onNavigate(path, options);
 }
-navigate.back = () => globalThis.history.back();
-navigate.forward = () => globalThis.history.forward();
 
-export function onNavigate() {
+/**
+ * @param {string} [path]
+ * @param {import('./index.d.ts').NavigateOptions} options
+ */
+export async function onNavigate(path, options = {}) {
 	if (!routes) {
 		throw new Error('Router not initialized: `createRouter` was not called.');
 	}
+	const {
+		match,
+		layouts,
+		hooks,
+		params: newParams,
+	} = matchRoute(path || globalThis.location.pathname, routes);
+
+	for (const { beforeLoad } of hooks) {
+		try {
+			await beforeLoad?.();
+		} catch {
+			return;
+		}
+	}
 
-	syncSearchParams();
+	componentTree.value = await resolveRouteComponents(match ? [...layouts, match] : layouts);
+	params.value = newParams || {};
 
+	if (path) {
+		if (options.search) path += options.search;
+		if (options.hash) path += options.hash;
+		const historyMethod = options.replace ? 'replaceState' : 'pushState';
+		globalThis.history[historyMethod](options.state || {}, '', path);
+	}
+
+	syncSearchParams();
 	Object.assign(location, updatedLocation());
 
-	const { match, layouts, params: newParams } = matchRoute(globalThis.location.pathname, routes);
-	params.value = newParams || {};
-	resolveRouteComponents(match ? [...layouts, match] : layouts).then((components) => {
-		componentTree.value = components;
-	});
+	for (const { afterLoad } of hooks) {
+		afterLoad?.();
+	}
 }
 
 /** @param {Event} event */
@@ -106,9 +131,12 @@ export function onGlobalClick(event) {
 
 	event.preventDefault();
 	const { replace, state } = anchor.dataset;
-	const historyMethod = replace === undefined || replace === 'false' ? 'pushState' : 'replaceState';
-	globalThis.history[historyMethod](state || {}, '', anchor.href);
-	onNavigate();
+	onNavigate(url.pathname, {
+		replace: replace === '' || replace === 'true',
+		search: url.search,
+		state,
+		hash: url.hash,
+	});
 }
 
 function updatedLocation() {

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

@@ -9,7 +9,9 @@ import path from 'node:path';
  * }} GeneratedRoutes
  */
 
-const PARAM_FILENAME_REGEX = /\[(.*)\].svelte/g;
+const PARAM_FILENAME_REGEX = /\[(.*)\](\.lazy)?\.svelte$/; // [any].svelte, [any].lazy.svelte
+const CATCH_ALL_FILENAME_REGEX = /\[\.\.\.(.*)\](\.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
 
 /**
  * @param {string} routesPath
@@ -35,34 +37,12 @@ export function buildFileTree(routesPath) {
 			tree.push({ name: entry, tree: buildFileTree(path.join(routesPath, entry)) });
 			continue;
 		}
-		if (!entry.endsWith('.svelte')) continue;
-		handleFlatFilename(tree, entry);
-	}
-	return tree;
-}
-
-/**
- * @param {FileTree} tree
- * @param {string} path
- */
-function handleFlatFilename(tree, path) {
-	// Split the path by the first dot that is not preceded or followed by another dot
-	const splited = path.split(/(?<!\.)\.(?!\.)/);
-	if (splited.length === 2) {
-		tree.push(path);
-		return;
-	}
-	const first = /** @type {string} */ (splited.shift());
-	for (const item of tree) {
-		if (typeof item === 'object' && item.name === first) {
-			handleFlatFilename(item.tree, splited.join('.'));
-			return;
+		if (!entry.endsWith('.svelte') && !HOOKS_FILENAME_REGEX.test(entry)) {
+			continue;
 		}
+		tree.push(entry);
 	}
-	/** @type {FileTree} */
-	const branch = [];
-	handleFlatFilename(branch, splited.join('.'));
-	tree.push({ name: first, tree: branch });
+	return tree;
 }
 
 /**
@@ -75,36 +55,56 @@ export function createRouteMap(fileTree, prefix = '') {
 	const result = {};
 	for (const entry of fileTree) {
 		if (typeof entry === 'string') {
-			const catchAll = /\[\.\.\.(.*)\]\.svelte/g.exec(entry); // Match [...slug].svelte
-			switch (true) {
-				case entry === 'index.svelte': {
-					result['/'] = prefix + entry;
-					break;
-				}
-				case entry === 'layout.svelte': {
-					result['layout'] = prefix + entry;
-					break;
-				}
-				case !!catchAll: {
-					result['*' + catchAll[1]] = prefix + entry;
-					break;
-				}
-				default: {
-					if (PARAM_FILENAME_REGEX.test(entry)) {
-						result['/' + entry.replaceAll(PARAM_FILENAME_REGEX, ':$1')] = prefix + entry;
-						break;
-					}
-					result['/' + entry.replace('.svelte', '')] = prefix + entry;
-					break;
+			if (!entry.endsWith('.svelte')) {
+				if (HOOKS_FILENAME_REGEX.test(entry)) {
+					result['hooks'] = prefix + entry;
+					continue;
 				}
+				continue;
+			}
+
+			if (entry.endsWith('index.svelte') || entry.endsWith('index.lazy.svelte')) {
+				const indexEntry = entry.replace(/\.?index(\.lazy)?\.svelte/, '');
+				result['/' + (indexEntry ? filePathToRoute(indexEntry) : '')] = prefix + entry;
+				continue;
 			}
+
+			if (entry === 'layout.svelte' || entry === 'layout.lazy.svelte') {
+				result['layout'] = prefix + entry;
+				continue;
+			}
+
+			const catchAll = CATCH_ALL_FILENAME_REGEX.exec(entry);
+			if (catchAll) {
+				result['*' + catchAll[1]] = prefix + entry;
+				continue;
+			}
+
+			// Match [id].svelte
+			if (PARAM_FILENAME_REGEX.test(entry)) {
+				result['/' + filePathToRoute(entry.replace(PARAM_FILENAME_REGEX, ':$1'))] = prefix + entry;
+				continue;
+			}
+
+			result['/' + filePathToRoute(entry.replace('.svelte', ''))] = prefix + entry;
 		} else {
-			result['/' + entry.name] = createRouteMap(entry.tree, prefix + entry.name + '/');
+			const entryName = filePathToRoute(entry.name);
+			result['/' + entryName] = createRouteMap(entry.tree, prefix + entryName + '/');
 		}
 	}
 	return result;
 }
 
+/**
+ * Replace `.` with `/`, but not `...`
+ *
+ * @param {string} filename
+ * @returns {string}
+ */
+function filePathToRoute(filename) {
+	return filename.replaceAll(/\.(?!\.\.)/g, '/');
+}
+
 /**
  * @param {GeneratedRoutes} routes
  * @param {string} routesPath
@@ -115,14 +115,76 @@ export function createRouterCode(routes, routesPath) {
 		routesPath += '/';
 	}
 
-	const jsonRoutes = JSON.stringify(routes, undefined, 2);
-	const withImports = jsonRoutes.replaceAll(
-		/"(.*)": "(.*)",?/g,
-		`"$1": () => import("${routesPath}$2"),`,
-	);
+	/** @type {Map<string, string>} */
+	const importsMap = new Map();
+
+	const withImports = (function handleImports(routes, routesPath) {
+		/** @type {GeneratedRoutes} */
+		const result = {};
+		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')) {
+				const variableName = pathToCorrectCasing(value);
+				importsMap.set(variableName, routesPath + value);
+				result[key] = variableName;
+			} else {
+				result[key] = `() => import('${routesPath}${value}')`;
+			}
+		}
+		return result;
+	})(routes, routesPath);
+
+	const imports = [...importsMap.entries()].map(([key, value]) => {
+		if (value.endsWith('.ts')) {
+			value = value.replace('.ts', '');
+		}
+		return `import ${key} from '${value}';`;
+	});
+
+	const stringifiedRoutes = JSON.stringify(withImports, undefined, 2)
+		.replaceAll(/"(.*)": /g, `'$1': `)
+		.replaceAll(/: "(.*)"/g, ': $1');
+
 	return [
-		'import { createRouter } from "sv-router";',
-		'\n\n',
-		`export const { p, navigate, isActive, route } = createRouter(${withImports});`,
-	].join('');
+		`import { createRouter } from 'sv-router';`,
+		...imports,
+		'',
+		`export const { p, navigate, isActive, route } = createRouter(${stringifiedRoutes});`,
+	].join('\n');
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function pathToCorrectCasing(value) {
+	const parts = /** @type {string[]} */ ([]);
+
+	/** @param {RegExp} regex */
+	function extractLastPart(regex) {
+		if (!regex.test(value)) return;
+		const exec = /** @type {RegExpExecArray} */ (regex.exec(value));
+		if (exec.index > 0) {
+			const before = value.slice(0, exec.index - 1);
+			parts.push(...before.split(/\/|-|\./));
+		}
+		return exec[1];
+	}
+
+	const lastPart =
+		extractLastPart(CATCH_ALL_FILENAME_REGEX) ||
+		extractLastPart(PARAM_FILENAME_REGEX) ||
+		extractLastPart(HOOKS_FILENAME_REGEX) ||
+		extractLastPart(/([\w-]+)(\.lazy)?\.svelte$/);
+	if (!lastPart) {
+		throw new Error(`Invalid filename: ${value}`);
+	}
+	parts.push(...lastPart.split('-'));
+
+	const uppercased = parts.map((part, index) => {
+		if (index === 0 && lastPart === 'hooks') return part;
+		return part.charAt(0).toUpperCase() + part.slice(1);
+	});
+	return uppercased.join('');
 }

package/src/helpers/match-route.js

@@ -3,6 +3,8 @@
  *
  * @typedef {import('../index.d.ts').RouteComponent} RouteComponent
  *
+ * @typedef {import('../index.d.ts').Hooks} Hooks
+ *
  * @typedef {import('../index.d.ts').Routes} Routes
  */
 
@@ -12,6 +14,7 @@
  * @returns {{
  * 	match: RouteComponent | undefined;
  * 	layouts: LayoutComponent[];
+ * 	hooks: Hooks[];
  * 	params: Record<string, string>;
  * 	breakFromLayouts: boolean;
  * }}
@@ -30,6 +33,9 @@ export function matchRoute(pathname, routes) {
 	/** @type {LayoutComponent[]} */
 	let layouts = [];
 
+	/** @type {Hooks[]} */
+	let hooks = [];
+
 	/** @type {Record<string, string>} */
 	let params = {};
 
@@ -74,6 +80,10 @@ export function matchRoute(pathname, routes) {
 				layouts.push(routes.layout);
 			}
 
+			if ('hooks' in routes && routes.hooks) {
+				hooks.push(routes.hooks);
+			}
+
 			if (typeof routeMatch === 'function') {
 				if (routeParts.length === pathParts.length) {
 					match = routeMatch;
@@ -87,6 +97,7 @@ export function matchRoute(pathname, routes) {
 			if (result) {
 				match = result.match;
 				params = { ...params, ...result.params };
+				hooks.push(...result.hooks);
 				if (result.breakFromLayouts) {
 					layouts = [];
 				} else {
@@ -97,7 +108,7 @@ export function matchRoute(pathname, routes) {
 		}
 	}
 
-	return { match, layouts, params, breakFromLayouts };
+	return { match, layouts, hooks, params, breakFromLayouts };
 }
 
 /**

package/src/helpers/utils.js

@@ -42,5 +42,5 @@ export function resolveRouteComponent(input) {
  * @returns {input is import('../index.d.ts').LazyRouteComponent}
  */
 export function isLazyImport(input) {
-	return typeof input === 'function' && !!/\(\)\s?=>\s?import\(.*\)/g.test(String(input));
+	return typeof input === 'function' && !!/\(\)\s?=>\s?import\(.*\)/.test(String(input));
 }

package/src/index.d.ts

@@ -15,7 +15,7 @@ export const isActiveLink: IsActiveLink;
  * Setup a new router instance with the given routes.
  *
  * ```js
- * export const { p, navigate, route } = createRouter({
+ * export const { p, navigate, isActive, route } = createRouter({
  *   '/': Home,
  *   '/about': About,
  *   ...
@@ -42,11 +42,30 @@ export type RouteComponent<Props extends BaseProps = any> =
 	| Component<Props>
 	| LazyRouteComponent<Props>;
 export type LayoutComponent = RouteComponent<{ children: Snippet }>;
+export type Hooks = {
+	/**
+	 * A function that will be called before the route is loaded. If it returns a promise, the route
+	 * will wait for it to resolve before loading.
+	 *
+	 * You can throw a `navigate` call to redirect to another route.
+	 *
+	 * ```js
+	 * async beforeLoad() {
+	 *   await ...
+	 *   throw navigate('/home');
+	 * }
+	 * ```
+	 */
+	beforeLoad?(): void | Promise<void>;
+	/** A function that will be called after the route is loaded. */
+	afterLoad?(): void;
+};
 
 export type Routes = {
 	[_: `/${string}`]: RouteComponent | Routes;
 	[_: `*${string}`]: RouteComponent | undefined;
 	layout?: LayoutComponent;
+	hooks?: Hooks;
 };
 
 export type IsActiveLink = Action<HTMLAnchorElement, { className?: string } | undefined>;
@@ -77,18 +96,15 @@ export type RouterApi<T extends Routes> = {
 	 * 	},
 	 * });
 	 * // Back and forward
-	 * navigate.back();
-	 * navigate.forward();
+	 * navigate(-1);
+	 * navigate(2);
 	 * ```
 	 *
 	 * @param route The route to navigate to.
 	 * @param options The navigation options.
 	 */
-	navigate: {
-		<U extends Path<T>>(...args: NavigateArgs<U>): void;
-		back: () => void;
-		forward: () => void;
-	};
+	navigate<U extends Path<T>>(...args: NavigateArgs<U>): void;
+
 	/**
 	 * Will return `true` if the given path is active.
 	 *
@@ -139,21 +155,24 @@ export type NavigateOptions =
 			replace?: boolean;
 			search?: string;
 			state?: string;
-			hash?: `#${string}`;
+			hash?: string;
 	  }
 	| undefined;
 
 type NavigateArgs<T extends string> =
-	PathParams<T> extends never
-		? [T, NavigateOptions]
-		: [T, NavigateOptions & { params: PathParams<T> }];
+	| (PathParams<T> extends never
+			? [T] | [T, NavigateOptions]
+			: [T, NavigateOptions & { params: PathParams<T> }])
+	| [number];
 
 type StripNonRoutes<T extends Routes> = {
 	[K in keyof T as K extends `*${string}`
 		? never
 		: K extends 'layout'
 			? never
-			: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
+			: K extends 'hooks'
+				? never
+				: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
 };
 
 type RecursiveKeys<T extends Routes, Prefix extends string = ''> = {