@buzola/router 0.0.3 → 0.0.4

package/src/__tests__/router.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it, mock } from 'bun:test'
-import { createMemoryNavigationAdapter } from '../engine/navigation-adapter'
-import { buildRouteTree } from '../engine/route-tree'
-import { Router } from '../engine/router'
-import type { GuardContext, RouteConfig } from '../engine/types'
+import { createMemoryNavigationAdapter } from '../engine/navigation-adapter.js'
+import { buildRouteTree } from '../engine/route-tree.js'
+import { Router } from '../engine/router.js'
+import type { RouteConfig } from '../engine/types.js'
 
 function dummyComponent() {
 	return null
@@ -107,216 +107,6 @@ describe('Router', () => {
 		expect(router.buildPath('/')).toBe('/')
 	})
 
-	it('handles route guards', async () => {
-		const guard = mock(() => false) // Block navigation
-
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/protected', component: dummyComponent, beforeEnter: guard },
-		])
-
-		router.navigate('/protected')
-		// Guard blocked it, should stay at /
-		expect(router.getState().location.pathname).toBe('/')
-		expect(guard).toHaveBeenCalled()
-	})
-
-	it('handles async route guards that allow navigation', async () => {
-		const guard = mock(() => Promise.resolve(true))
-
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/protected', component: dummyComponent, beforeEnter: guard },
-		])
-
-		router.navigate('/protected')
-		// Async guard — need to wait for microtask
-		await new Promise(resolve => setTimeout(resolve, 10))
-		expect(router.getState().location.pathname).toBe('/protected')
-		expect(guard).toHaveBeenCalled()
-	})
-
-	it('handles async route guards that block navigation', async () => {
-		const guard = mock(() => Promise.resolve(false))
-
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/protected', component: dummyComponent, beforeEnter: guard },
-		])
-
-		router.navigate('/protected')
-		await new Promise(resolve => setTimeout(resolve, 10))
-		expect(router.getState().location.pathname).toBe('/')
-		expect(guard).toHaveBeenCalled()
-	})
-
-	it('handles route guards that redirect', async () => {
-		const guard = mock(() => ({ redirect: '/login' }))
-
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/login', component: dummyComponent },
-			{ path: '/protected', component: dummyComponent, beforeEnter: guard },
-		])
-
-		router.navigate('/protected')
-		await new Promise(resolve => setTimeout(resolve, 10))
-		expect(router.getState().location.pathname).toBe('/login')
-		expect(guard).toHaveBeenCalled()
-	})
-
-	it('handles async route guards that redirect', async () => {
-		const guard = mock(() => Promise.resolve({ redirect: '/login' }))
-
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/login', component: dummyComponent },
-			{ path: '/protected', component: dummyComponent, beforeEnter: guard },
-		])
-
-		router.navigate('/protected')
-		await new Promise(resolve => setTimeout(resolve, 10))
-		expect(router.getState().location.pathname).toBe('/login')
-		expect(guard).toHaveBeenCalled()
-	})
-
-	it('dispose stops intercepting navigations', () => {
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/about', component: dummyComponent },
-		])
-
-		const subscriber = mock(() => {})
-		router.subscribe(subscriber)
-		router.dispose()
-
-		router.navigate('/about')
-		expect(subscriber).not.toHaveBeenCalled()
-	})
-
-	it('updates routes for HMR', () => {
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-		])
-
-		const newRoutes = buildRouteTree([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/new-route', component: dummyComponent },
-		])
-
-		router.updateRoutes(newRoutes)
-		router.navigate('/new-route')
-		expect(router.getState().location.pathname).toBe('/new-route')
-	})
-
-	it('dispose clears all subscribers', () => {
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/about', component: dummyComponent },
-		])
-
-		const subscriber = mock(() => {})
-		router.subscribe(subscriber)
-		router.dispose()
-
-		router.navigate('/about')
-		expect(subscriber).not.toHaveBeenCalled()
-	})
-
-	it('passes GuardContext with AbortSignal to guards', async () => {
-		let receivedContext: GuardContext | undefined
-		const guard = mock((_match: unknown, context: GuardContext) => {
-			receivedContext = context
-			return true
-		})
-
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/protected', component: dummyComponent, beforeEnter: guard },
-		])
-
-		router.navigate('/protected')
-		await new Promise(resolve => setTimeout(resolve, 10))
-		expect(guard).toHaveBeenCalled()
-		expect(receivedContext).toBeDefined()
-		expect(receivedContext!.signal).toBeInstanceOf(AbortSignal)
-		expect(receivedContext!.signal.aborted).toBe(false)
-	})
-
-	it('aborts previous guard signal on new navigation', async () => {
-		let firstSignal: AbortSignal | undefined
-		let resolveFirst: (() => void) | undefined
-
-		const slowGuard = mock((_match: unknown, context: GuardContext) => {
-			firstSignal = context.signal
-			return new Promise<boolean>(resolve => {
-				resolveFirst = () => resolve(true)
-			})
-		})
-
-		const { router } = createRouter([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/slow', component: dummyComponent, beforeEnter: slowGuard },
-			{ path: '/fast', component: dummyComponent },
-		])
-
-		// Start navigation to /slow (guard will hang)
-		router.navigate('/slow')
-		await new Promise(resolve => setTimeout(resolve, 10))
-		expect(firstSignal).toBeDefined()
-		expect(firstSignal!.aborted).toBe(false)
-
-		// Start a new navigation — should abort the previous signal
-		router.navigate('/fast')
-		await new Promise(resolve => setTimeout(resolve, 10))
-		expect(firstSignal!.aborted).toBe(true)
-
-		// Clean up
-		resolveFirst?.()
-	})
-
-	it('throws on guard redirect to non-existent route', async () => {
-		const guard = mock(() => ({ redirect: '/nowhere' }))
-
-		const routes = buildRouteTree([
-			{ path: '/', component: dummyComponent, isIndex: true },
-			{ path: '/protected', component: dummyComponent, beforeEnter: guard },
-		])
-		const adapter = createMemoryNavigationAdapter({ initialURL: 'http://localhost/' })
-
-		// Intercept the navigate event to capture the handler promise for assertions
-		// while converting the error to NavigationAbortedError so the adapter swallows it.
-		let handlerPromise: Promise<void> | undefined
-		const origAddEventListener = adapter.addEventListener
-		adapter.addEventListener = (_type, listener) => {
-			origAddEventListener.call(adapter, _type, (event) => {
-				const origEventIntercept = event.intercept.bind(event)
-				event.intercept = (opts) => {
-					handlerPromise = opts.handler()
-					origEventIntercept({
-						...opts,
-						handler: () =>
-							handlerPromise!.catch(() => {
-								// Convert to NavigationAbortedError so the adapter swallows it
-								const err = new Error()
-								err.name = 'NavigationAbortedError'
-								throw err
-							}),
-					})
-				}
-				listener(event)
-			})
-		}
-
-		const router = new Router({ routes, adapter })
-		router.start()
-
-		router.navigate('/protected')
-		expect(handlerPromise).toBeDefined()
-		await expect(handlerPromise!).rejects.toThrow('does not match any route')
-		expect(router.getState().location.pathname).toBe('/')
-	})
-
 	it('generates deterministic path-based IDs', () => {
 		const routes = buildRouteTree([
 			{

package/src/__tests__/setup-dom.ts

@@ -0,0 +1,21 @@
+import { GlobalWindow } from 'happy-dom'
+
+const window = new GlobalWindow()
+
+for (const key of Object.getOwnPropertyNames(window)) {
+	if (key in globalThis) continue
+	try {
+		Object.defineProperty(globalThis, key, {
+			value: (window as unknown as Record<string, unknown>)[key],
+			writable: true,
+			configurable: true,
+		})
+	} catch {
+		// Some properties can't be set — skip them
+	}
+}
+
+Object.defineProperty(globalThis, 'window', { value: window, writable: true, configurable: true })
+Object.defineProperty(globalThis, 'document', { value: window.document, writable: true, configurable: true })
+Object.defineProperty(globalThis, 'navigator', { value: window.navigator, writable: true, configurable: true })
+Object.defineProperty(globalThis, 'HTMLElement', { value: window.HTMLElement, writable: true, configurable: true })

package/src/define/create-page.tsx

@@ -1,10 +1,11 @@
 import type { ReactElement } from 'react'
 import { type ComponentType, use, useCallback, useEffect, useMemo, useReducer, useState } from 'react'
-import { isOptionalSchema, type ParamLiteral, resolveParamLiteral } from '../engine/schema'
-import type { RouteComponent, StandardSchema } from '../engine/types'
-import { extractParamNames } from '../engine/utils'
-import { RouteContext, RouterContext } from '../react/context'
-import { ErrorBoundary } from '../react/error-boundary'
+import type { LoaderCache } from '../engine/loader-cache.js'
+import { isOptionalSchema, type ParamLiteral, resolveParamLiteral, validateSchema } from '../engine/schema.js'
+import type { EffectivePageParams, RegisteredPage, RouteComponent, StandardSchema } from '../engine/types.js'
+import { extractParamNames } from '../engine/utils.js'
+import { RouteContext, RouterContext } from '../react/context.js'
+import { ErrorBoundary } from '../react/error-boundary.js'
 
 export interface PageProps<TParams> {
 	params: TParams
@@ -29,7 +30,7 @@ export interface PageDefinition<TParams = Record<string, never>> {
 	route?: string
 	paramsSchema?: StandardSchema
 	paramsMeta: ParamMeta[]
-	loader?: (ctx: { params: any }) => Promise<unknown>
+	loader?: (ctx: { params: any; redirect: RedirectFn }) => Promise<unknown>
 }
 
 // ─── Route pattern type safety ──────────────────────────────────────────────
@@ -113,18 +114,47 @@ function resolveParamsInput<T>(input: StandardSchema<T> | ParamsShape): {
 	return { schema, paramsMeta }
 }
 
+// ─── Redirect response ───────────────────────────────────────────────────────
+
+export class BuzolaRedirect {
+	readonly __buzolaRedirect = true
+	constructor(
+		readonly pageId: string,
+		readonly params?: Record<string, string>,
+	) {}
+}
+
+export type RedirectFn = <P extends RegisteredPage>(
+	to: P,
+	...args: [keyof EffectivePageParams<P>] extends [never] ? []
+		// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+		: {} extends EffectivePageParams<P> ? [params?: EffectivePageParams<P>]
+		: [params: EffectivePageParams<P>]
+) => BuzolaRedirect
+
+export const redirect: RedirectFn = (pageId: string, params?: Record<string, string>): BuzolaRedirect => {
+	return new BuzolaRedirect(pageId, params)
+}
+
 // ─── Loader helpers ─────────────────────────────────────────────────────────
 
-type LoaderFn = (ctx: { params: any }) => Promise<any>
+type LoaderFn = (ctx: { params: any; redirect: RedirectFn }) => Promise<any>
 
 function combineLoaders(loaders: LoaderFn[]): LoaderFn | undefined {
 	if (loaders.length === 0) return undefined
 	if (loaders.length === 1) return loaders[0]
-	return async (ctx) => Object.assign({}, ...await Promise.all(loaders.map(fn => fn(ctx))))
+	return async (ctx) => {
+		const results = await Promise.all(loaders.map(fn => fn(ctx)))
+		const redir = results.find(r => r instanceof BuzolaRedirect)
+		if (redir) return redir
+		return Object.assign({}, ...results)
+	}
 }
 
 // ─── Component factory ──────────────────────────────────────────────────────
 
+let nextPageId = 0
+
 function createPageComponent<TParams>(
 	schema: StandardSchema<TParams> | undefined,
 	paramsMeta: ParamMeta[],
@@ -145,18 +175,27 @@ function createPageComponent<TParams>(
 	let activeUrlHref: string | null = null
 	let activeCacheKey: string | null = null
 	let activePromise: Promise<unknown> | null = null
-	let activeResolvedData: unknown = undefined
+	let activeResolvedData: unknown
 	let hasResolved = false
 	let pendingBackgroundKey: string | null = null
 
-	// LRU cache for previously visited URLs (url → resolved data)
-	const staleDataCache = new Map<string, unknown>()
+	// Unique ID for namespacing entries in the global loader cache
+	const pageId = nextPageId++
 
-	function evictStaleCache(maxSize: number): void {
-		while (staleDataCache.size > maxSize) {
-			const first = staleDataCache.keys().next().value!
-			staleDataCache.delete(first)
-		}
+	function staleCacheKey(urlHref: string): string {
+		return `${pageId}:${urlHref}`
+	}
+
+	function staleCacheGet(cache: LoaderCache, urlHref: string): { hit: true; value: unknown } | { hit: false } {
+		const key = staleCacheKey(urlHref)
+		if (!cache.has(key)) return { hit: false }
+		const value = cache.get(key)
+		cache.delete(key)
+		return { hit: true, value }
+	}
+
+	function staleCacheSet(cache: LoaderCache, urlHref: string, value: unknown): void {
+		cache.set(staleCacheKey(urlHref), value)
 	}
 
 	function BuzolaPage(): ReactElement | null {
@@ -204,13 +243,7 @@ function createPageComponent<TParams>(
 			}
 
 			if (schema) {
-				const result = schema['~standard'].validate(merged)
-				if ('issues' in result) {
-					throw new Error(
-						`Page params validation failed: ${result.issues.map(i => i.message).join(', ')}`,
-					)
-				}
-				return result.value
+				return validateSchema(schema, merged, 'Page params validation failed: ')
 			}
 
 			return merged as TParams
@@ -226,10 +259,11 @@ function createPageComponent<TParams>(
 			return router.onInvalidate(() => setLoaderKey(k => k + 1))
 		}, [router])
 
-		const cacheSize = router?.loaderCacheSize ?? 0
+		const loaderCache = router?.loaderCache
 
-		let data: unknown = undefined
+		let data: unknown
 		let isLoading = false
+		let shouldRedirect = false
 
 		if (loaderFn) {
 			const currentUrlHref = routeContext.state.location.href
@@ -237,25 +271,26 @@ function createPageComponent<TParams>(
 
 			// URL changed — save old data to stale cache, restore from stale cache if available
 			if (activeUrlHref !== null && activeUrlHref !== currentUrlHref) {
-				if (hasResolved && activeResolvedData !== undefined) {
-					staleDataCache.set(activeUrlHref, activeResolvedData)
-					evictStaleCache(cacheSize)
+				if (loaderCache && hasResolved && activeResolvedData !== undefined) {
+					staleCacheSet(loaderCache, activeUrlHref, activeResolvedData)
 				}
 
-				if (staleDataCache.has(currentUrlHref)) {
-					activeResolvedData = staleDataCache.get(currentUrlHref)
-					staleDataCache.delete(currentUrlHref)
+				const cached = loaderCache && staleCacheGet(loaderCache, currentUrlHref)
+				if (cached?.hit) {
+					activeResolvedData = cached.value
 					hasResolved = true
 				} else {
 					hasResolved = false
 					activeResolvedData = undefined
 				}
 				pendingBackgroundKey = null
-			} else if (activeUrlHref === null && staleDataCache.has(currentUrlHref)) {
+			} else if (activeUrlHref === null && loaderCache) {
 				// Remount — restore from stale cache
-				activeResolvedData = staleDataCache.get(currentUrlHref)
-				staleDataCache.delete(currentUrlHref)
-				hasResolved = true
+				const cached = staleCacheGet(loaderCache, currentUrlHref)
+				if (cached.hit) {
+					activeResolvedData = cached.value
+					hasResolved = true
+				}
 			}
 			activeUrlHref = currentUrlHref
 
@@ -276,7 +311,7 @@ function createPageComponent<TParams>(
 				}
 			} else if (hasResolved) {
 				// Cache key changed + we have stale data → background reload (SWR)
-				const promise = loaderFn({ params })
+				const promise = loaderFn({ params, redirect })
 				activeCacheKey = cacheKey
 				activePromise = promise
 				pendingBackgroundKey = cacheKey
@@ -287,6 +322,10 @@ function createPageComponent<TParams>(
 					(result) => {
 						// Only apply if this is still the active load
 						if (activeCacheKey === cacheKey) {
+							if (result instanceof BuzolaRedirect) {
+								router?.navigateToPage(result.pageId, result.params, { replace: true })
+								return
+							}
 							activeResolvedData = result
 							pendingBackgroundKey = null
 							forceUpdate()
@@ -304,21 +343,28 @@ function createPageComponent<TParams>(
 				)
 			} else {
 				// No stale data — first load, suspend via use()
-				const promise = loaderFn({ params })
+				const promise = loaderFn({ params, redirect })
 				activeCacheKey = cacheKey
 				activePromise = promise
-				data = use(promise)
-				activeResolvedData = data
-				hasResolved = true
+				const result = use(promise)
+				if (result instanceof BuzolaRedirect) {
+					router?.navigateToPage(result.pageId, result.params, { replace: true })
+					shouldRedirect = true
+				} else {
+					data = result
+				}
+				if (!shouldRedirect) {
+					activeResolvedData = data
+					hasResolved = true
+				}
 			}
 		}
 
 		// On unmount, save active data to stale cache and reset active state
 		useEffect(() => {
 			return () => {
-				if (hasResolved && activeResolvedData !== undefined && activeUrlHref) {
-					staleDataCache.set(activeUrlHref, activeResolvedData)
-					evictStaleCache(cacheSize)
+				if (loaderCache && hasResolved && activeResolvedData !== undefined && activeUrlHref) {
+					staleCacheSet(loaderCache, activeUrlHref, activeResolvedData)
 				}
 				hasResolved = false
 				activeResolvedData = undefined
@@ -329,6 +375,8 @@ function createPageComponent<TParams>(
 			}
 		}, [])
 
+		if (shouldRedirect) return null
+
 		return <RenderComponent params={params} data={data} invalidate={invalidate} isLoading={isLoading} />
 	}
 
@@ -383,13 +431,13 @@ interface WithLoaderChain<TParams, TData>
 	extends WithRoute<TParams, PageProps<TParams> & { data: TData; invalidate: () => void; isLoading: boolean }>
 {
 	loader<TNew extends Record<string, unknown>>(
-		fn: (ctx: { params: TParams }) => Promise<TNew>,
+		fn: (ctx: { params: TParams; redirect: RedirectFn }) => Promise<TNew | BuzolaRedirect>,
 	): WithLoaderChain<TParams, TData & TNew>
 }
 
 interface WithLoader<TParams> extends WithRoute<TParams, PageProps<TParams>> {
 	loader<TData extends Record<string, unknown>>(
-		fn: (ctx: { params: TParams }) => Promise<TData>,
+		fn: (ctx: { params: TParams; redirect: RedirectFn }) => Promise<TData | BuzolaRedirect>,
 	): WithLoaderChain<TParams, TData>
 }
 
@@ -397,7 +445,7 @@ interface PageBuilder {
 	params<T extends ParamsShape>(shape: T): WithLoader<InferShape<T>>
 	params<T extends Record<string, unknown>>(schema: StandardSchema<T>): WithLoader<T>
 	loader<TData extends Record<string, unknown>>(
-		fn: (ctx: { params: Record<string, never> }) => Promise<TData>,
+		fn: (ctx: { params: Record<string, never>; redirect: RedirectFn }) => Promise<TData | BuzolaRedirect>,
 	): WithLoaderChain<Record<string, never>, TData>
 	catch(handler: CatchHandler): WithCatch<Record<string, never>, PageProps<Record<string, never>>>
 	route<R extends string>(

package/src/engine/loader-cache.ts

@@ -0,0 +1,55 @@
+/**
+ * Global LRU cache for page loader data.
+ * Shared across all page components to limit total memory usage.
+ * Uses Map insertion order for LRU eviction — oldest entries are evicted first.
+ */
+export class LoaderCache {
+	private cache = new Map<string, unknown>()
+	private _maxSize: number
+
+	constructor(maxSize: number) {
+		if (maxSize < 0) {
+			throw new Error(`[buzola] LoaderCache maxSize must be non-negative, got ${maxSize}`)
+		}
+		this._maxSize = maxSize
+	}
+
+	get maxSize(): number {
+		return this._maxSize
+	}
+
+	get size(): number {
+		return this.cache.size
+	}
+
+	get(key: string): unknown {
+		const value = this.cache.get(key)
+		if (value !== undefined || this.cache.has(key)) {
+			// Move to end (most recently used)
+			this.cache.delete(key)
+			this.cache.set(key, value)
+		}
+		return value
+	}
+
+	has(key: string): boolean {
+		return this.cache.has(key)
+	}
+
+	set(key: string, value: unknown): void {
+		this.cache.delete(key)
+		this.cache.set(key, value)
+		while (this.cache.size > this._maxSize) {
+			const first = this.cache.keys().next().value!
+			this.cache.delete(first)
+		}
+	}
+
+	delete(key: string): void {
+		this.cache.delete(key)
+	}
+
+	clear(): void {
+		this.cache.clear()
+	}
+}

package/src/engine/matcher.ts

@@ -1,4 +1,4 @@
-import type { RouteMatch, RouteNode } from './types'
+import type { RouteMatch, RouteNode } from './types.js'
 
 /**
  * Match a URL against the route tree.

package/src/engine/navigation-adapter.ts

@@ -1,4 +1,4 @@
-import type { BuzolaNavigateEvent, NavigateOptions, NavigationAdapter } from './types'
+import type { BuzolaNavigateEvent, NavigateOptions, NavigationAdapter } from './types.js'
 
 // ─── Browser adapter ────────────────────────────────────────────────────────
 

package/src/engine/route-tree.ts

@@ -1,4 +1,4 @@
-import type { RouteComponent, RouteConfig, RouteGuard, RouteNode, StandardSchema } from './types'
+import type { RouteComponent, RouteConfig, RouteNode, StandardSchema } from './types.js'
 
 /**
  * Normalize a path segment — ensure it starts with "/" and strip trailing slashes.
@@ -24,7 +24,6 @@ export interface CreateRouteNodeOptions {
 	fullPath: string
 	component?: RouteComponent
 	searchSchema?: StandardSchema
-	beforeEnter?: RouteGuard
 	children?: RouteNode[]
 	parent?: RouteNode
 	isLayout?: boolean
@@ -40,7 +39,6 @@ export function createRouteNode(options: CreateRouteNodeOptions): RouteNode {
 		fullPath,
 		component,
 		searchSchema,
-		beforeEnter,
 		children = [],
 		parent,
 		isLayout = false,
@@ -69,7 +67,6 @@ export function createRouteNode(options: CreateRouteNodeOptions): RouteNode {
 		prefixPattern,
 		component,
 		searchSchema,
-		beforeEnter,
 		children,
 		parent,
 		isLayout,
@@ -101,7 +98,9 @@ function buildRouteNodes(configs: RouteConfig[], parentPath: string): RouteNode[
 		const isIndex = config.isIndex ?? (!isLayout && (config.path === '/' || config.path === ''))
 
 		let fullPath: string
-		if (isIndex) {
+		if (config.matchPath != null) {
+			fullPath = config.matchPath
+		} else if (isIndex) {
 			fullPath = parentPath || '/'
 		} else {
 			fullPath = joinPaths(parentPath || '/', segment)
@@ -116,7 +115,6 @@ function buildRouteNodes(configs: RouteConfig[], parentPath: string): RouteNode[
 			fullPath,
 			component: config.component,
 			searchSchema: config.searchSchema,
-			beforeEnter: config.beforeEnter,
 			children,
 			isLayout,
 			isIndex,