@buzola/router 0.0.1

package/src/engine/router.ts

@@ -0,0 +1,471 @@
+import { matchRoutes } from './matcher'
+import type { BlockerFn, GuardRedirect, NavigateOptions, NavigationAdapter, RouteMatch, RouteNode, RouterState } from './types'
+import { extractParamNames } from './utils'
+
+function isGuardRedirect(value: unknown): value is GuardRedirect {
+	return typeof value === 'object' && value !== null && 'redirect' in value && typeof (value as GuardRedirect).redirect === 'string'
+}
+
+/**
+ * Thrown when a route guard prevents navigation.
+ */
+export class NavigationAbortedError extends Error {
+	constructor() {
+		super('Navigation aborted by route guard')
+		this.name = 'NavigationAbortedError'
+	}
+}
+
+export type RouterSubscriber = (state: RouterState) => void
+
+export interface RouterOptions {
+	/** Route tree nodes. */
+	routes: RouteNode[]
+	/** Navigation adapter (browser or memory). */
+	adapter: NavigationAdapter
+	/** Enable View Transitions API for navigations. */
+	viewTransitions?: boolean
+	/**
+	 * Base path prefix for all routes (e.g., "/app").
+	 * Routes are defined without the base path; the router prepends it
+	 * for navigation and strips it for matching.
+	 */
+	basePath?: string
+	/**
+	 * Callback that returns fallback values for persistent parameters.
+	 * Used when a persistent param is not explicitly provided and not present in the current URL.
+	 */
+	persistentParams?: () => Record<string, string>
+	/**
+	 * Page registry mapping page IDs to route patterns.
+	 * Generated by the Vite plugin.
+	 */
+	pageRegistry?: Record<string, string>
+	/**
+	 * Number of previously visited URLs to keep cached per page component.
+	 * When navigating back to a cached URL, stale data is shown immediately
+	 * while a background reload runs (SWR).
+	 * Set to 0 to always re-fetch on URL change (default).
+	 */
+	loaderCacheSize?: number
+}
+
+/**
+ * Central Router orchestrator.
+ * Intercepts all navigations via the Navigation API and manages route matching.
+ */
+export class Router {
+	private routes: RouteNode[]
+	private adapter: NavigationAdapter
+	private viewTransitions: boolean
+	private readonly _basePath: string
+	private readonly persistentParamsFn?: () => Record<string, string>
+	private readonly pageRegistry: Record<string, string>
+	private subscribers = new Set<RouterSubscriber>()
+	private invalidationListeners = new Set<() => void>()
+	private state: RouterState
+	private navigationId = 0
+	private currentAbortController?: AbortController
+	private stopFn: (() => void) | undefined
+	private blockers = new Set<BlockerFn>()
+	private pendingScrollBehavior: 'after-transition' | 'manual' = 'after-transition'
+	private readonly _loaderCacheSize: number
+
+	constructor(options: RouterOptions) {
+		this.routes = options.routes
+		this.adapter = options.adapter
+		this.viewTransitions = options.viewTransitions ?? false
+		this._basePath = options.basePath ? options.basePath.replace(/\/$/, '') : ''
+		this.persistentParamsFn = options.persistentParams
+		this.pageRegistry = options.pageRegistry ?? {}
+		this._loaderCacheSize = options.loaderCacheSize ?? 0
+
+		// Initialize state from current URL
+		const url = this.adapter.getCurrentURL()
+		const matches = matchRoutes(this.routes, this.createMatchUrl(url)) ?? []
+
+		this.state = {
+			location: url,
+			matches,
+			isPending: false,
+			navigationState: this.adapter.getState(),
+		}
+	}
+
+	/**
+	 * The configured base path (e.g., "/app"). Empty string if none.
+	 */
+	get basePath(): string {
+		return this._basePath
+	}
+
+	/**
+	 * Number of previously visited URLs to keep cached per page component.
+	 */
+	get loaderCacheSize(): number {
+		return this._loaderCacheSize
+	}
+
+	/**
+	 * Get the current router state.
+	 */
+	getState(): RouterState {
+		return this.state
+	}
+
+	/**
+	 * Subscribe to state changes. Returns an unsubscribe function.
+	 */
+	subscribe(subscriber: RouterSubscriber): () => void {
+		this.subscribers.add(subscriber)
+		return () => {
+			this.subscribers.delete(subscriber)
+		}
+	}
+
+	/**
+	 * Start intercepting navigations.
+	 * Call this once when the router is initialized.
+	 */
+	start(): () => void {
+		const handler = (event: import('./types.js').BuzolaNavigateEvent) => {
+			if (!event.canIntercept) return
+
+			const url = new URL(event.destination.url)
+			const matchUrl = this.createMatchUrl(url)
+			const matches = matchRoutes(this.routes, matchUrl)
+			if (!matches) return
+
+			const currentNavId = ++this.navigationId
+			const useViewTransition = event.viewTransition || this.viewTransitions
+			const scrollBehavior = this.pendingScrollBehavior
+			this.pendingScrollBehavior = 'after-transition'
+
+			// Abort any in-flight guard from a previous navigation
+			if (this.currentAbortController) {
+				this.currentAbortController.abort()
+			}
+			const controller = new AbortController()
+			this.currentAbortController = controller
+
+			event.intercept({
+				scroll: scrollBehavior,
+				handler: async () => {
+					// Check blockers before setting pending state
+					for (const blocker of this.blockers) {
+						if (this.navigationId !== currentNavId) return
+						const shouldProceed = await blocker()
+						if (!shouldProceed) {
+							throw new NavigationAbortedError()
+						}
+					}
+
+					// Set pending state
+					this.setState({
+						...this.state,
+						isPending: true,
+					})
+
+					// Run route guards (outer → inner)
+					for (const match of matches) {
+						// A newer navigation has started — abandon this one
+						if (this.navigationId !== currentNavId) return
+
+						if (match.node.beforeEnter) {
+							const result = await match.node.beforeEnter(match, { signal: controller.signal })
+							if (result === false) {
+								// Guard prevented navigation
+								if (this.navigationId === currentNavId) {
+									this.setState({
+										...this.state,
+										isPending: false,
+									})
+								}
+								throw new NavigationAbortedError()
+							}
+							if (isGuardRedirect(result)) {
+								// Guard requested redirect — don't reset isPending, the redirect
+								// navigation will take over the pending state.
+								if (this.navigationId === currentNavId) {
+									const redirectURL = new URL(result.redirect, url)
+									const redirectMatches = matchRoutes(this.routes, this.createMatchUrl(redirectURL))
+									if (!redirectMatches) {
+										throw new Error(`[buzola] Guard redirect target "${result.redirect}" does not match any route.`)
+									}
+									this.navigate(result.redirect, { replace: true })
+								}
+								throw new NavigationAbortedError()
+							}
+						}
+					}
+
+					// A newer navigation has started — abandon this one
+					if (this.navigationId !== currentNavId) return
+
+					// Perform the DOM update
+					const doUpdate = () => {
+						this.setState({
+							location: url,
+							matches,
+							isPending: false,
+							navigationState: this.adapter.getState(),
+						})
+					}
+
+					if (useViewTransition && typeof document !== 'undefined' && 'startViewTransition' in document) {
+						;(document as unknown as { startViewTransition: (cb: () => void) => void }).startViewTransition(doUpdate)
+					} else {
+						doUpdate()
+					}
+				},
+			})
+		}
+
+		this.adapter.addEventListener('navigate', handler)
+
+		const stop = () => {
+			this.adapter.removeEventListener('navigate', handler)
+		}
+		this.stopFn = stop
+
+		return stop
+	}
+
+	/**
+	 * Navigate programmatically.
+	 * The `to` path should not include the base path — it is prepended automatically.
+	 */
+	navigate(to: string, options?: NavigateOptions): void {
+		if (options?.resetScroll === false) {
+			this.pendingScrollBehavior = 'manual'
+		}
+		this.adapter.navigate(this._basePath + to, options)
+	}
+
+	/**
+	 * Navigate to a page by its page ID.
+	 * Looks up the route pattern from the page registry and builds the URL.
+	 */
+	navigateToPage(pageId: string, params?: Record<string, string>, options?: NavigateOptions): void {
+		const path = this.buildPagePath(pageId, params)
+		this.navigate(this.stripBasePath(path), options)
+	}
+
+	/**
+	 * Build a URL path for a page ID with the given params.
+	 * Path params are substituted into the route pattern; extra params become query string.
+	 */
+	buildPagePath(pageId: string, params?: Record<string, string>): string {
+		const pattern = this.pageRegistry[pageId]
+		if (!pattern) {
+			throw new Error(`[buzola] Unknown page "${pageId}". Is it registered in the page registry?`)
+		}
+		const resolved = this.resolveParams(pattern, params)
+		return this.buildPath(pattern, resolved)
+	}
+
+	/**
+	 * Go back in history.
+	 */
+	back(): void {
+		this.adapter.back()
+	}
+
+	/**
+	 * Go forward in history.
+	 */
+	forward(): void {
+		this.adapter.forward()
+	}
+
+	/**
+	 * Build a URL from a path pattern and params.
+	 * The returned path includes the base path prefix.
+	 */
+	buildPath(pattern: string, params?: Record<string, string>): string {
+		const segments = pattern.split('/')
+		const result: string[] = []
+		const missing: string[] = []
+
+		for (const segment of segments) {
+			if (segment.startsWith(':')) {
+				// Catch-all param (:slug+)
+				const isCatchAll = segment.endsWith('+')
+				const paramName = isCatchAll ? segment.slice(1, -1) : segment.slice(1)
+				const value = params?.[paramName]
+				if (value === undefined) {
+					missing.push(paramName)
+				} else {
+					if (isCatchAll) {
+						// Catch-all values may contain slashes — insert raw
+						result.push(value)
+					} else {
+						result.push(encodeURIComponent(value))
+					}
+				}
+			} else {
+				result.push(segment)
+			}
+		}
+
+		if (missing.length > 0) {
+			if (!params) {
+				throw new Error(`Missing params for path "${pattern}": ${missing.join(', ')}`)
+			}
+			throw new Error(`Missing param "${missing[0]}" for path "${pattern}"`)
+		}
+
+		// Extra params (not in path pattern) → query string
+		const pathParamNames = new Set(extractParamNames(pattern))
+		const search = new URLSearchParams()
+		if (params) {
+			for (const [key, value] of Object.entries(params)) {
+				if (!pathParamNames.has(key) && value !== undefined) {
+					search.set(key, value)
+				}
+			}
+		}
+
+		const path = this._basePath + result.join('/')
+		const qs = search.toString()
+		return qs ? `${path}?${qs}` : path
+	}
+
+	/**
+	 * Strip the base path prefix from a pathname.
+	 * Returns the pathname relative to the base path.
+	 */
+	stripBasePath(pathname: string): string {
+		if (this._basePath && pathname.startsWith(this._basePath)) {
+			return pathname.slice(this._basePath.length) || '/'
+		}
+		return pathname
+	}
+
+	/**
+	 * Resolve params for a route pattern by merging:
+	 * 1. Explicitly provided params (highest priority)
+	 * 2. Current URL match params
+	 * 3. persistentParams() callback (fallback)
+	 *
+	 * Only fills params that are present in the target pattern.
+	 */
+	resolveParams(pattern: string, explicitParams?: Record<string, string>): Record<string, string> {
+		const paramNames = this.extractParamNames(pattern)
+		const currentParams = this.getCurrentParams()
+		const fallbackParams = this.persistentParamsFn?.() ?? {}
+		const result: Record<string, string> = {}
+
+		for (const name of paramNames) {
+			const value = explicitParams?.[name] ?? currentParams[name] ?? fallbackParams[name]
+			if (value !== undefined) {
+				result[name] = value
+			}
+		}
+
+		// Pass through extra explicit params (not in pattern) for search params
+		if (explicitParams) {
+			const pathParamNames = new Set(paramNames)
+			for (const [key, value] of Object.entries(explicitParams)) {
+				if (!pathParamNames.has(key) && value !== undefined) {
+					result[key] = value
+				}
+			}
+		}
+
+		return result
+	}
+
+	/**
+	 * Extract parameter names from a route pattern.
+	 */
+	private extractParamNames(pattern: string): string[] {
+		return extractParamNames(pattern)
+	}
+
+	/**
+	 * Get merged params from all current route matches.
+	 */
+	private getCurrentParams(): Record<string, string> {
+		const params: Record<string, string> = {}
+		for (const match of this.state.matches) {
+			Object.assign(params, match.params)
+		}
+		return params
+	}
+
+	/**
+	 * Trigger all registered invalidation listeners.
+	 * Used to re-run page loaders in the background.
+	 */
+	invalidateAll(): void {
+		for (const listener of this.invalidationListeners) {
+			listener()
+		}
+	}
+
+	/**
+	 * Register an invalidation listener. Returns an unsubscribe function.
+	 */
+	onInvalidate(listener: () => void): () => void {
+		this.invalidationListeners.add(listener)
+		return () => {
+			this.invalidationListeners.delete(listener)
+		}
+	}
+
+	/**
+	 * Register a navigation blocker.
+	 * The blocker function is called before each navigation.
+	 * It must return a Promise that resolves to `true` to allow or `false` to block.
+	 * Returns an unsubscribe function.
+	 */
+	addBlocker(fn: BlockerFn): () => void {
+		this.blockers.add(fn)
+		return () => {
+			this.blockers.delete(fn)
+		}
+	}
+
+	/**
+	 * Dispose the router — clear all subscribers and reset state.
+	 */
+	dispose(): void {
+		this.stopFn?.()
+		this.stopFn = undefined
+		this.subscribers.clear()
+		this.invalidationListeners.clear()
+	}
+
+	/**
+	 * Update the route tree (for HMR).
+	 */
+	updateRoutes(routes: RouteNode[]): void {
+		this.routes = routes
+		// Re-match current URL with new routes
+		const matches = matchRoutes(this.routes, this.createMatchUrl(this.state.location)) ?? []
+		this.setState({
+			...this.state,
+			matches,
+		})
+	}
+
+	/**
+	 * Create a URL with basePath stripped for route matching.
+	 */
+	private createMatchUrl(url: URL): URL {
+		if (!this._basePath) return url
+		const stripped = new URL(url)
+		if (stripped.pathname.startsWith(this._basePath)) {
+			stripped.pathname = stripped.pathname.slice(this._basePath.length) || '/'
+		}
+		return stripped
+	}
+
+	private setState(newState: RouterState): void {
+		this.state = newState
+		for (const subscriber of this.subscribers) {
+			subscriber(this.state)
+		}
+	}
+}

package/src/engine/schema.ts

@@ -0,0 +1,130 @@
+import type { StandardSchema } from './types'
+
+/**
+ * Built-in minimal Standard Schema builders for route params.
+ * Use these when you don't need a full schema library like Zod or Valibot.
+ *
+ * @example
+ * ```ts
+ * import { s } from '@buzola/router'
+ *
+ * const page = createPage()
+ *   .params({ id: s.string(), tab: s.optional(s.string()) })
+ *   .route('/project/:id')
+ *   .render(({ params }) => <div>{params.id}</div>)
+ * ```
+ *
+ * Or use string literals for common types:
+ * ```ts
+ * createPage()
+ *   .params({ id: 'uuid', order: 'number', text: '?string', tags: '?string[]' })
+ * ```
+ */
+
+function string(): StandardSchema<string> {
+	return {
+		'~standard': {
+			version: 1,
+			vendor: 'buzola',
+			validate: (v) => typeof v === 'string' ? { value: v } : { issues: [{ message: 'expected string' }] },
+		},
+	}
+}
+
+function optional(schema: StandardSchema<string>): StandardSchema<string | undefined> {
+	return {
+		'~standard': {
+			version: 1,
+			vendor: 'buzola',
+			validate: (v) => v === undefined || v === '' ? { value: undefined } : schema['~standard'].validate(v) as { value: string | undefined },
+		},
+	}
+}
+
+export function isOptionalSchema(schema: StandardSchema): boolean {
+	const result = schema['~standard'].validate(undefined)
+	return !('issues' in result)
+}
+
+function object<T extends Record<string, StandardSchema>>(
+	shape: T,
+): StandardSchema<{ [K in keyof T]: T[K] extends StandardSchema<infer V> ? V : never }> & {
+	__buzolaKeys: { name: string; optional: boolean; array: boolean }[]
+} {
+	return {
+		__buzolaKeys: Object.entries(shape).map(([name, s]) => ({ name, optional: isOptionalSchema(s), array: false })),
+		'~standard': {
+			version: 1,
+			vendor: 'buzola',
+			validate: (v) => {
+				const input = (v ?? {}) as Record<string, unknown>
+				const result: Record<string, unknown> = {}
+				for (const [key, schema] of Object.entries(shape)) {
+					const r = schema['~standard'].validate(input[key])
+					if ('issues' in r) return r
+					result[key] = r.value
+				}
+				return { value: result } as { value: { [K in keyof T]: T[K] extends StandardSchema<infer V> ? V : never } }
+			},
+		},
+	}
+}
+
+export const s = { object, string, optional }
+
+// ─── Param literals ─────────────────────────────────────────────────────────
+
+export type ParamLiteral = 'string' | 'number' | 'uuid' | '?string' | '?number' | '?uuid' | 'string[]' | 'number[]' | '?string[]' | '?number[]'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+type ScalarValidator = (v: unknown) => { value: unknown } | { issues: readonly { message: string }[] }
+
+const scalarValidators: Record<string, ScalarValidator> = {
+	string: (v) => typeof v === 'string' ? { value: v } : { issues: [{ message: 'expected string' }] },
+	number: (v) => {
+		const n = Number(v)
+		return Number.isNaN(n) ? { issues: [{ message: 'expected number' }] } : { value: n }
+	},
+	uuid: (v) => typeof v === 'string' && UUID_RE.test(v) ? { value: v } : { issues: [{ message: 'expected UUID' }] },
+}
+
+export function resolveParamLiteral(literal: ParamLiteral): {
+	schema: StandardSchema
+	optional: boolean
+	array: boolean
+} {
+	const isOpt = literal.startsWith('?')
+	const rest = isOpt ? literal.slice(1) : literal
+	const isArr = rest.endsWith('[]')
+	const baseType = isArr ? rest.slice(0, -2) : rest
+
+	const validateScalar = scalarValidators[baseType]
+	if (!validateScalar) throw new Error(`Unknown param type: ${baseType}`)
+
+	let validate: StandardSchema['~standard']['validate']
+
+	if (isArr) {
+		validate = (v) => {
+			if (isOpt && (v === undefined || (Array.isArray(v) && v.length === 0))) return { value: undefined }
+			if (!Array.isArray(v)) return { issues: [{ message: `expected ${baseType}[]` }] }
+			const result: unknown[] = []
+			for (const item of v) {
+				const r = validateScalar(item)
+				if ('issues' in r) return r
+				result.push(r.value)
+			}
+			return { value: result }
+		}
+	} else if (isOpt) {
+		validate = (v) => v === undefined || v === '' ? { value: undefined } : validateScalar(v)
+	} else {
+		validate = validateScalar
+	}
+
+	return {
+		schema: { '~standard': { version: 1, vendor: 'buzola', validate } },
+		optional: isOpt,
+		array: isArr,
+	}
+}