@buzola/router 0.0.7 → 0.0.9

package/dist/engine/matcher.d.ts

@@ -2,7 +2,7 @@ import type { RouteMatch, RouteNode } from './types.js';
 /**
  * Match a URL against the route tree.
  * Returns an array of RouteMatch from root layout to leaf page, or null if no match.
- * Performs depth-first matching.
+ * When multiple routes match, selects the most specific one (fewest dynamic params).
  */
 export declare function matchRoutes(nodes: RouteNode[], url: URL): RouteMatch[] | null;
 //# sourceMappingURL=matcher.d.ts.map

package/dist/engine/matcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../src/engine/matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEvD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,GAAG,UAAU,EAAE,GAAG,IAAI,CAS7E"}
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../src/engine/matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEvD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,GAAG,UAAU,EAAE,GAAG,IAAI,CAG7E"}

package/dist/engine/matcher.js

@@ -1,31 +1,54 @@
 /**
  * Match a URL against the route tree.
  * Returns an array of RouteMatch from root layout to leaf page, or null if no match.
- * Performs depth-first matching.
+ * When multiple routes match, selects the most specific one (fewest dynamic params).
  */
 export function matchRoutes(nodes, url) {
     const pathname = url.pathname;
+    return pickBestMatch(nodes, pathname);
+}
+/**
+ * Find the best match among sibling nodes.
+ * Tries all siblings and picks the most specific match (fewest dynamic params).
+ */
+function pickBestMatch(nodes, pathname) {
+    let best = null;
+    let bestParamCount = Infinity;
     for (const node of nodes) {
         const result = matchNode(node, pathname);
-        if (result)
-            return result;
+        if (result) {
+            const paramCount = countParams(result);
+            if (paramCount < bestParamCount) {
+                best = result;
+                bestParamCount = paramCount;
+                if (paramCount === 0)
+                    break; // Can't do better than zero params
+            }
+        }
     }
-    return null;
+    return best;
+}
+/**
+ * Count total dynamic params across all matches in a chain.
+ */
+function countParams(matches) {
+    let count = 0;
+    for (const match of matches) {
+        count += Object.keys(match.params).length;
+    }
+    return count;
 }
 function matchNode(node, pathname) {
     // Layout nodes: try to match children, prepend self if any child matches
     if (node.isLayout && !node.isIndex) {
-        for (const child of node.children) {
-            const childMatch = matchNode(child, pathname);
-            if (childMatch) {
-                // Layout is part of the match chain
-                const layoutMatch = {
-                    node,
-                    params: extractLayoutParams(node, pathname),
-                    pathname,
-                };
-                return [layoutMatch, ...childMatch];
-            }
+        const childMatch = pickBestMatch(node.children, pathname);
+        if (childMatch) {
+            const layoutMatch = {
+                node,
+                params: extractLayoutParams(node, pathname),
+                pathname,
+            };
+            return [layoutMatch, ...childMatch];
         }
         return null;
     }
@@ -37,11 +60,9 @@ function matchNode(node, pathname) {
             const match = { node, params, pathname };
             // If this node has children (e.g., a page with nested routes), try them too
             if (node.children.length > 0) {
-                for (const child of node.children) {
-                    const childMatch = matchNode(child, pathname);
-                    if (childMatch) {
-                        return [match, ...childMatch];
-                    }
+                const childMatch = pickBestMatch(node.children, pathname);
+                if (childMatch) {
+                    return [match, ...childMatch];
                 }
             }
             return [match];

package/dist/engine/matcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"matcher.js","sourceRoot":"","sources":["../../src/engine/matcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"matcher.js","sourceRoot":"","sources":["../../src/engine/matcher.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import 'urlpattern-polyfill';
 export { LoaderCache } from './engine/loader-cache.js';
 export { NavigationAbortedError, Router } from './engine/router.js';
 export type { RouterOptions, RouterSubscriber } from './engine/router.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAEzE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxE,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAC9G,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAGpF,YAAY,EACX,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,UAAU,EACV,SAAS,EACT,WAAW,EACX,cAAc,GACd,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAC9E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAGlG,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,qBAAqB,CAAA;AAG5B,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAEzE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxE,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAC9G,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAGpF,YAAY,EACX,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,UAAU,EACV,SAAS,EACT,WAAW,EACX,cAAc,GACd,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAC9E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAGlG,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -1,3 +1,5 @@
+// ─── Polyfills ──────────────────────────────────────────────────────────────
+import 'urlpattern-polyfill';
 // ─── Engine ─────────────────────────────────────────────────────────────────
 export { LoaderCache } from './engine/loader-cache.js';
 export { NavigationAbortedError, Router } from './engine/router.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGnE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAsB9G,gFAAgF;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAEtC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAG9E,+EAA+E;AAC/E,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,qBAAqB,CAAA;AAE5B,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGnE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAsB9G,gFAAgF;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAEtC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAG9E,+EAA+E;AAC/E,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@buzola/router",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -36,5 +36,8 @@
 		"happy-dom": "^20.8.3",
 		"react": "^19.0.0",
 		"typescript": "^5.7.0"
+	},
+	"dependencies": {
+		"urlpattern-polyfill": "^10.1.0"
 	}
 }

package/src/__tests__/matcher.test.ts

@@ -145,6 +145,50 @@ describe('matchRoutes', () => {
 		expect(matches![1].params).toEqual({ userId: '42' })
 	})
 
+	it('prefers static route over dynamic sibling when layout with matchPath comes first', () => {
+		// Simulates the real-world scenario: layout with dynamic matchPath children
+		// appears before a static route at the same level (e.g., /project/detail layout
+		// with matchPath /project/:id vs /project/create static page)
+		const tree = createTestTree([
+			{
+				path: '/',
+				component: dummyComponent,
+				isLayout: true,
+				children: [
+					{
+						path: '/project/detail',
+						component: dummyComponent,
+						isLayout: true,
+						children: [
+							{ path: '/', matchPath: '/project/:id', component: dummyComponent, isIndex: true },
+						],
+					},
+					{ path: '/project/create', component: dummyComponent },
+				],
+			},
+		])
+
+		// /project/create should match the static route, not /project/:id with id=create
+		const matches = matchRoutes(tree, new URL('http://localhost/project/create'))
+		expect(matches).not.toBeNull()
+		const leaf = matches![matches!.length - 1]
+		expect(leaf.node.fullPath).toBe('/project/create')
+		expect(leaf.params).toEqual({})
+	})
+
+	it('prefers route with fewer dynamic params among siblings', () => {
+		const tree = createTestTree([
+			{ path: '/users/:userId', component: dummyComponent },
+			{ path: '/users/me', component: dummyComponent },
+		])
+
+		const matches = matchRoutes(tree, new URL('http://localhost/users/me'))
+		expect(matches).not.toBeNull()
+		expect(matches).toHaveLength(1)
+		expect(matches![0].node.fullPath).toBe('/users/me')
+		expect(matches![0].params).toEqual({})
+	})
+
 	it('does not match partial paths', () => {
 		const tree = createTestTree([
 			{ path: '/about', component: dummyComponent },

package/src/__tests__/type-safety.test.tsx

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'bun:test'
 import React from 'react'
 import { createPage } from '../define/create-page.js'
-import type { StandardSchema } from '../engine/types.js'
+import type { EffectivePageParams, NavigateOptions, RegisteredPage, StandardSchema } from '../engine/types.js'
 import type { LinkProps } from '../react/link.js'
 
 // Register pages for type-safe testing
@@ -229,3 +229,76 @@ describe('Link JSX generic inference', () => {
 		expect(true).toBe(true)
 	})
 })
+
+// ─── NavigateFn type safety ─────────────────────────────────────────────────
+
+/**
+ * Replicate the NavigateFn type from hooks.ts for testing without React hooks.
+ */
+type NavigateFn = <P extends RegisteredPage>(
+	to: P,
+	...args: [keyof EffectivePageParams<P>] extends [never] ? [options?: NavigateOptions]
+		// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+		: {} extends EffectivePageParams<P> ? [options?: NavigateOptions & { params?: EffectivePageParams<P> }]
+		: [options: NavigateOptions & { params: EffectivePageParams<P> }]
+) => void
+
+describe('NavigateFn type safety', () => {
+	const noop = (() => {}) as NavigateFn
+
+	it('static page does not require options', () => {
+		noop('home')
+		noop('about')
+		expect(true).toBe(true)
+	})
+
+	it('static page accepts NavigateOptions without params', () => {
+		noop('home', { replace: true })
+		expect(true).toBe(true)
+	})
+
+	it('static page rejects params', () => {
+		// @ts-expect-error — static page should not accept params
+		noop('home', { params: { foo: 'bar' } })
+		expect(true).toBe(true)
+	})
+
+	it('dynamic page requires options with params', () => {
+		noop('users/detail', { params: { userId: '1' } })
+
+		// @ts-expect-error — missing required options with params
+		noop('users/detail')
+		expect(true).toBe(true)
+	})
+
+	it('dynamic page requires correct param names', () => {
+		// @ts-expect-error — wrong param name (id instead of userId)
+		noop('users/detail', { params: { id: '1' } })
+		expect(true).toBe(true)
+	})
+
+	it('dynamic page rejects params passed directly as options (without params wrapper)', () => {
+		// @ts-expect-error — { userId: '1' } is not valid, must be { params: { userId: '1' } }
+		noop('users/detail', { userId: '1' })
+		expect(true).toBe(true)
+	})
+
+	it('multi-param page requires all params', () => {
+		noop('users/posts', { params: { userId: '1', postId: '2' } })
+
+		// @ts-expect-error — missing postId
+		noop('users/posts', { params: { userId: '1' } })
+		expect(true).toBe(true)
+	})
+
+	it('rejects unregistered pages', () => {
+		// @ts-expect-error — page not in BuzolaPageMap
+		noop('unknown')
+		expect(true).toBe(true)
+	})
+
+	it('allows NavigateOptions alongside params', () => {
+		noop('users/detail', { params: { userId: '1' }, replace: true })
+		expect(true).toBe(true)
+	})
+})

package/src/engine/matcher.ts

@@ -3,33 +3,58 @@ import type { RouteMatch, RouteNode } from './types.js'
 /**
  * Match a URL against the route tree.
  * Returns an array of RouteMatch from root layout to leaf page, or null if no match.
- * Performs depth-first matching.
+ * When multiple routes match, selects the most specific one (fewest dynamic params).
  */
 export function matchRoutes(nodes: RouteNode[], url: URL): RouteMatch[] | null {
 	const pathname = url.pathname
+	return pickBestMatch(nodes, pathname)
+}
+
+/**
+ * Find the best match among sibling nodes.
+ * Tries all siblings and picks the most specific match (fewest dynamic params).
+ */
+function pickBestMatch(nodes: RouteNode[], pathname: string): RouteMatch[] | null {
+	let best: RouteMatch[] | null = null
+	let bestParamCount = Infinity
 
 	for (const node of nodes) {
 		const result = matchNode(node, pathname)
-		if (result) return result
+		if (result) {
+			const paramCount = countParams(result)
+			if (paramCount < bestParamCount) {
+				best = result
+				bestParamCount = paramCount
+				if (paramCount === 0) break // Can't do better than zero params
+			}
+		}
 	}
 
-	return null
+	return best
+}
+
+/**
+ * Count total dynamic params across all matches in a chain.
+ */
+function countParams(matches: RouteMatch[]): number {
+	let count = 0
+	for (const match of matches) {
+		count += Object.keys(match.params).length
+	}
+	return count
 }
 
 function matchNode(node: RouteNode, pathname: string): RouteMatch[] | null {
 	// Layout nodes: try to match children, prepend self if any child matches
 	if (node.isLayout && !node.isIndex) {
-		for (const child of node.children) {
-			const childMatch = matchNode(child, pathname)
-			if (childMatch) {
-				// Layout is part of the match chain
-				const layoutMatch: RouteMatch = {
-					node,
-					params: extractLayoutParams(node, pathname),
-					pathname,
-				}
-				return [layoutMatch, ...childMatch]
+		const childMatch = pickBestMatch(node.children, pathname)
+		if (childMatch) {
+			const layoutMatch: RouteMatch = {
+				node,
+				params: extractLayoutParams(node, pathname),
+				pathname,
 			}
+			return [layoutMatch, ...childMatch]
 		}
 		return null
 	}
@@ -43,11 +68,9 @@ function matchNode(node: RouteNode, pathname: string): RouteMatch[] | null {
 
 			// If this node has children (e.g., a page with nested routes), try them too
 			if (node.children.length > 0) {
-				for (const child of node.children) {
-					const childMatch = matchNode(child, pathname)
-					if (childMatch) {
-						return [match, ...childMatch]
-					}
+				const childMatch = pickBestMatch(node.children, pathname)
+				if (childMatch) {
+					return [match, ...childMatch]
 				}
 			}
 

package/src/index.ts

@@ -1,3 +1,6 @@
+// ─── Polyfills ──────────────────────────────────────────────────────────────
+import 'urlpattern-polyfill'
+
 // ─── Engine ─────────────────────────────────────────────────────────────────
 export { LoaderCache } from './engine/loader-cache.js'