feat: provide match function to allow the opposite of resolve

Author: hmnd

.changeset/new-bugs-fail.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: `match` function to map a path back to a route id and params

packages/kit/src/runtime/app/paths/client.js

@@ -2,6 +2,8 @@
 /** @import { ResolveArgs } from './types.js' */
 import { base, assets, hash_routing } from './internal/client.js';
 import { resolve_route } from '../../../utils/routing.js';
+import { decode_params } from '../../../utils/url.js';
+import { get_routes } from '../../client/client.js';
 
 /**
  * Resolve the URL of an asset in your `static` directory, by prefixing it with [`config.kit.paths.assets`](https://svelte.dev/docs/kit/configuration#paths) if configured, or otherwise by prefixing it with the base path.
@@ -58,4 +60,40 @@ export function resolve(...args) {
 	);
 }
 
+/**
+ * Match a pathname to a route ID and extracts any parameters.
+ *
+ * @example
+ * ```js
+ * import { match } from '$app/paths';
+ *
+ * const result = await match('/blog/hello-world');
+ * // → { id: '/blog/[slug]', params: { slug: 'hello-world' } }
+ *
+ *
+ * @param {Pathname} pathname
+ * @returns {Promise<{ id: RouteId, params: Record<string, string> } | null>}
+ */
+export async function match(pathname) {
+	let path = pathname;
+
+	if (base && path.startsWith(base)) {
+		path = path.slice(base.length) || '/';
+	}
+
+	if (hash_routing && path.startsWith('#')) {
+		path = path.slice(1) || '/';
+	}
+
+	const routes = get_routes();
+	for (const route of routes) {
+		const params = route.exec(path);
+		if (params) {
+			return { id: /** @type {RouteId} */ (route.id), params: decode_params(params) };
+		}
+	}
+
+	return null;
+}
+
 export { base, assets, resolve as resolveRoute };

packages/kit/src/runtime/app/paths/server.js

@@ -1,6 +1,8 @@
 import { base, assets, relative, initial_base } from './internal/server.js';
-import { resolve_route } from '../../../utils/routing.js';
+import { resolve_route, exec } from '../../../utils/routing.js';
+import { decode_params } from '../../../utils/url.js';
 import { try_get_request_store } from '@sveltejs/kit/internal/server';
+import { manifest } from '__sveltekit/server';
 
 /** @type {import('./client.js').asset} */
 export function asset(file) {
@@ -27,4 +29,30 @@ export function resolve(id, params) {
 	return base + resolved;
 }
 
+/** @type {import('./client.js').match} */
+export async function match(pathname) {
+	let path = pathname;
+
+	if (base && path.startsWith(base)) {
+		path = path.slice(base.length) || '/';
+	}
+
+	const matchers = await manifest._.matchers();
+
+	for (const route of manifest._.routes) {
+		const match = route.pattern.exec(path);
+		if (!match) continue;
+
+		const matched = exec(match, route.params, matchers);
+		if (matched) {
+			return {
+				id: /** @type {import('$app/types').RouteId} */ (route.id),
+				params: decode_params(matched)
+			};
+		}
+	}
+
+	return null;
+}
+
 export { base, assets, resolve as resolveRoute };

packages/kit/src/runtime/client/client.js

@@ -189,6 +189,14 @@ let target;
 /** @type {import('./types.js').SvelteKitApp} */
 export let app;
 
+/**
+ * Returns the client-side routes array. Used by `$app/paths` for route matching.
+ * @returns {import('types').CSRRoute[]}
+ */
+export function get_routes() {
+	return routes;
+}
+
 /**
  * Data that was serialized during SSR. This is cleared when the user first navigates
  * @type {Record<string, any>}

packages/kit/test/apps/basics/src/routes/match/+page.server.js

@@ -0,0 +1,12 @@
+import { match } from '$app/paths';
+import { testPaths } from './const';
+
+export async function load() {
+	const serverResults = await Promise.all(
+		testPaths.map(async (path) => ({ path, result: await match(path) }))
+	);
+
+	return {
+		serverResults
+	};
+}

packages/kit/test/apps/basics/src/routes/match/+page.svelte

@@ -0,0 +1,34 @@
+<script>
+	import { match } from '$app/paths';
+	import { onMount } from 'svelte';
+	import { testPaths } from './const';
+
+	let { data } = $props();
+
+	const clientResults = $state([]);
+
+	onMount(async () => {
+		for (const path of testPaths) {
+			const result = await match(path);
+			clientResults.push({ path, result });
+		}
+	});
+</script>
+
+<h1>Match Test</h1>
+
+<div id="server-results">
+	{#each data.serverResults as { path, result }}
+		<div class="result" data-path={path}>
+			{JSON.stringify(result)}
+		</div>
+	{/each}
+</div>
+
+<div id="client-results">
+	{#each clientResults as { path, result }}
+		<div class="result" data-path={path}>
+			{JSON.stringify(result)}
+		</div>
+	{/each}
+</div>

packages/kit/test/apps/basics/src/routes/match/const.ts

@@ -0,0 +1,5 @@
+export const testPaths = [
+	'/match/load/foo',
+	'/match/slug/test-slug',
+	'/match/not-a-real-route-that-exists'
+];

packages/kit/test/apps/basics/src/routes/match/load/foo/+page.svelte

@@ -0,0 +1 @@
+bar

packages/kit/test/apps/basics/src/routes/match/slug/[slug]/+page.svelte

@@ -0,0 +1 @@
+slug

packages/kit/test/apps/basics/test/test.js

@@ -766,6 +766,29 @@ test.describe('$app/paths', () => {
 			javaScriptEnabled ? absolute : '../../../../favicon.png'
 		);
 	});
+
+	test('match() returns route id and params for matching routes', async ({
+		page,
+		javaScriptEnabled
+	}) => {
+		await page.goto('/match');
+
+		const samples = [
+			{ path: '/match/load/foo', expected: { id: '/match/load/foo', params: {} } },
+			{
+				path: '/match/slug/test-slug',
+				expected: { id: '/match/slug/[slug]', params: { slug: 'test-slug' } }
+			},
+			{ path: '/match/not-a-real-route-that-exists', expected: null }
+		];
+
+		for (const { path, expected } of samples) {
+			const results = javaScriptEnabled
+				? page.locator('#client-results')
+				: page.locator('#server-results');
+			await expect(results.locator(`[data-path="${path}"]`)).toHaveText(JSON.stringify(expected));
+		}
+	});
 });
 
 // TODO SvelteKit 3: remove these tests