@buzola/router 0.0.1

package/src/define/create-page.tsx

@@ -0,0 +1,472 @@
+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'
+
+export interface PageProps<TParams> {
+	params: TParams
+}
+
+export interface CatchContext {
+	error: Error
+	retry: () => void
+}
+
+type CatchHandler = React.ReactNode | ((ctx: CatchContext) => React.ReactNode)
+
+export interface ParamMeta {
+	name: string
+	optional: boolean
+	array: boolean
+}
+
+export interface PageDefinition<TParams = Record<string, never>> {
+	__buzolaPage: true
+	component: RouteComponent
+	route?: string
+	paramsSchema?: StandardSchema
+	paramsMeta: ParamMeta[]
+	loader?: (ctx: { params: any }) => Promise<unknown>
+}
+
+// ─── Route pattern type safety ──────────────────────────────────────────────
+
+/**
+ * Extract dynamic parameter names from a route pattern at the type level.
+ * "/users/:userId/posts/:postId" → "userId" | "postId"
+ * "/:slug+" → "slug"
+ */
+type ExtractRouteParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}`
+	? (Param extends `${infer P}+` ? P : Param) | ExtractRouteParams<Rest>
+	: T extends `${string}:${infer Param}` ? (Param extends `${infer P}+` ? P : Param)
+	: never
+
+// ─── Schema helpers ──────────────────────────────────────────────────────────
+
+type ParamField = StandardSchema | ParamLiteral
+type ParamsShape = Record<string, ParamField>
+
+type ScalarType<T extends string> = T extends 'string' ? string
+	: T extends 'number' ? number
+	: T extends 'uuid' ? string
+	: never
+
+type LiteralToType<L extends string> = L extends `?${infer Base}[]` ? ScalarType<Base>[] | undefined
+	: L extends `${infer Base}[]` ? ScalarType<Base>[]
+	: L extends `?${infer Base}` ? ScalarType<Base> | undefined
+	: ScalarType<L>
+
+type InferShape<T extends ParamsShape> = {
+	[K in keyof T]: T[K] extends StandardSchema<infer V> ? V : T[K] extends string ? LiteralToType<T[K]> : never
+}
+
+function isStandardSchema(value: StandardSchema | ParamsShape): value is StandardSchema {
+	return '~standard' in value
+}
+
+function resolveParamsInput<T>(input: StandardSchema<T> | ParamsShape): {
+	schema: StandardSchema<T>
+	paramsMeta: ParamMeta[]
+} {
+	if (isStandardSchema(input)) {
+		return {
+			schema: input,
+			paramsMeta: (input as any).__buzolaKeys ?? [],
+		}
+	}
+
+	const shape = input
+	const paramsMeta: ParamMeta[] = []
+	const fieldSchemas: Record<string, StandardSchema> = {}
+
+	for (const [name, field] of Object.entries(shape)) {
+		if (typeof field === 'string') {
+			const resolved = resolveParamLiteral(field)
+			fieldSchemas[name] = resolved.schema
+			paramsMeta.push({ name, optional: resolved.optional, array: resolved.array })
+		} else {
+			fieldSchemas[name] = field
+			paramsMeta.push({ name, optional: isOptionalSchema(field), array: false })
+		}
+	}
+
+	const schema: StandardSchema<T> = {
+		'~standard': {
+			version: 1,
+			vendor: 'buzola',
+			validate: (v) => {
+				const record = (v ?? {}) as Record<string, unknown>
+				const result: Record<string, unknown> = {}
+				for (const [key, fs] of Object.entries(fieldSchemas)) {
+					const r = fs['~standard'].validate(record[key])
+					if ('issues' in r) return r
+					result[key] = r.value
+				}
+				return { value: result } as { value: T }
+			},
+		},
+	}
+
+	return { schema, paramsMeta }
+}
+
+// ─── Loader helpers ─────────────────────────────────────────────────────────
+
+type LoaderFn = (ctx: { params: any }) => 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))))
+}
+
+// ─── Component factory ──────────────────────────────────────────────────────
+
+function createPageComponent<TParams>(
+	schema: StandardSchema<TParams> | undefined,
+	paramsMeta: ParamMeta[],
+	loaderFn: LoaderFn | undefined,
+	routePattern: string | undefined,
+	RenderComponent: ComponentType<any>,
+	catchHandler?: CatchHandler,
+): PageDefinition<TParams> {
+	const arrayParams = new Set(paramsMeta.filter(m => m.array).map(m => m.name))
+
+	// Loader promise cache lives in the closure, outside React's render cycle.
+	// This is critical: when use() suspends during the initial render, React
+	// discards all uncommitted hook state (useRef, useState, useMemo).
+	// On retry, hooks reinitialize, and useMemo/useRef would create a new promise,
+	// causing an infinite suspend loop. The closure cache survives this.
+
+	// Active load state (current URL)
+	let activeUrlHref: string | null = null
+	let activeCacheKey: string | null = null
+	let activePromise: Promise<unknown> | null = null
+	let activeResolvedData: unknown = undefined
+	let hasResolved = false
+	let pendingBackgroundKey: string | null = null
+
+	// LRU cache for previously visited URLs (url → resolved data)
+	const staleDataCache = new Map<string, unknown>()
+
+	function evictStaleCache(maxSize: number): void {
+		while (staleDataCache.size > maxSize) {
+			const first = staleDataCache.keys().next().value!
+			staleDataCache.delete(first)
+		}
+	}
+
+	function BuzolaPage(): ReactElement | null {
+		const routeContext = use(RouteContext)
+		if (!routeContext) {
+			throw new Error('createPage component must be used within a <BuzolaProvider>')
+		}
+
+		const router = use(RouterContext)
+
+		const params = useMemo(() => {
+			const { state, matches, params: pathParams } = routeContext
+
+			const currentMatch = matches.find(m => m.node.component === BuzolaPage)
+			const pathParamNames = new Set(
+				currentMatch ? extractParamNames(currentMatch.node.fullPath) : [],
+			)
+
+			const merged: Record<string, string | string[]> = {}
+
+			if (arrayParams.size > 0) {
+				for (const name of arrayParams) {
+					if (pathParamNames.has(name)) continue
+					const values = [
+						...state.location.searchParams.getAll(name),
+						...state.location.searchParams.getAll(`${name}[]`),
+					]
+					if (values.length > 0) merged[name] = values
+				}
+			}
+
+			state.location.searchParams.forEach((value, key) => {
+				const cleanKey = key.endsWith('[]') ? key.slice(0, -2) : key
+				if (!pathParamNames.has(cleanKey) && !(cleanKey in merged)) {
+					merged[cleanKey] = value
+				}
+			})
+
+			for (const [key, value] of Object.entries(pathParams)) {
+				if (arrayParams.has(key)) {
+					merged[key] = value.split(',')
+				} else {
+					merged[key] = value
+				}
+			}
+
+			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 merged as TParams
+		}, [routeContext])
+
+		const [loaderKey, setLoaderKey] = useState(0)
+		const [, forceUpdate] = useReducer(x => x + 1, 0)
+		const invalidate = useCallback(() => setLoaderKey(k => k + 1), [])
+
+		// Subscribe to router-level invalidation
+		useEffect(() => {
+			if (!router) return
+			return router.onInvalidate(() => setLoaderKey(k => k + 1))
+		}, [router])
+
+		const cacheSize = router?.loaderCacheSize ?? 0
+
+		let data: unknown = undefined
+		let isLoading = false
+
+		if (loaderFn) {
+			const currentUrlHref = routeContext.state.location.href
+			const cacheKey = `${currentUrlHref}:${loaderKey}`
+
+			// 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 (staleDataCache.has(currentUrlHref)) {
+					activeResolvedData = staleDataCache.get(currentUrlHref)
+					staleDataCache.delete(currentUrlHref)
+					hasResolved = true
+				} else {
+					hasResolved = false
+					activeResolvedData = undefined
+				}
+				pendingBackgroundKey = null
+			} else if (activeUrlHref === null && staleDataCache.has(currentUrlHref)) {
+				// Remount — restore from stale cache
+				activeResolvedData = staleDataCache.get(currentUrlHref)
+				staleDataCache.delete(currentUrlHref)
+				hasResolved = true
+			}
+			activeUrlHref = currentUrlHref
+
+			if (activeCacheKey === cacheKey) {
+				// Cache hit — check if background load is pending
+				if (pendingBackgroundKey === cacheKey) {
+					data = activeResolvedData
+					isLoading = true
+				} else {
+					// Either resolved or first-time suspend
+					if (hasResolved) {
+						data = activeResolvedData
+					} else {
+						data = use(activePromise!)
+						activeResolvedData = data
+						hasResolved = true
+					}
+				}
+			} else if (hasResolved) {
+				// Cache key changed + we have stale data → background reload (SWR)
+				const promise = loaderFn({ params })
+				activeCacheKey = cacheKey
+				activePromise = promise
+				pendingBackgroundKey = cacheKey
+				data = activeResolvedData
+				isLoading = true
+
+				promise.then(
+					(result) => {
+						// Only apply if this is still the active load
+						if (activeCacheKey === cacheKey) {
+							activeResolvedData = result
+							pendingBackgroundKey = null
+							forceUpdate()
+						}
+					},
+					(error) => {
+						// Store rejected promise so use() triggers ErrorBoundary
+						if (activeCacheKey === cacheKey) {
+							activePromise = promise
+							hasResolved = false
+							pendingBackgroundKey = null
+							forceUpdate()
+						}
+					},
+				)
+			} else {
+				// No stale data — first load, suspend via use()
+				const promise = loaderFn({ params })
+				activeCacheKey = cacheKey
+				activePromise = promise
+				data = use(promise)
+				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)
+				}
+				hasResolved = false
+				activeResolvedData = undefined
+				activeCacheKey = null
+				activePromise = null
+				pendingBackgroundKey = null
+				activeUrlHref = null
+			}
+		}, [])
+
+		return <RenderComponent params={params} data={data} invalidate={invalidate} isLoading={isLoading} />
+	}
+
+	function BuzolaPageWithCatch(): ReactElement | null {
+		const routeContext = use(RouteContext)
+		const [retryCount, setRetryCount] = useState(0)
+		const retry = useCallback(() => setRetryCount(c => c + 1), [])
+		const resetKey = `${routeContext?.state.location.href ?? ''}:${retryCount}`
+		const boundFallback = typeof catchHandler === 'function'
+			? (error: Error) => (catchHandler as (ctx: CatchContext) => React.ReactNode)({ error, retry })
+			: catchHandler
+		return (
+			<ErrorBoundary fallback={boundFallback} resetKey={resetKey}>
+				<BuzolaPage key={retryCount} />
+			</ErrorBoundary>
+		)
+	}
+
+	const component = catchHandler ? BuzolaPageWithCatch : BuzolaPage
+
+	return {
+		__buzolaPage: true,
+		component: component as unknown as RouteComponent,
+		route: routePattern,
+		paramsSchema: schema as StandardSchema | undefined,
+		paramsMeta,
+		loader: loaderFn,
+	}
+}
+
+// ─── Builder ────────────────────────────────────────────────────────────────
+
+interface WithCatch<TParams, TRenderProps> {
+	route<R extends string>(
+		pattern: [ExtractRouteParams<R>] extends [keyof TParams & string] ? R : never,
+	): { render(fn: ComponentType<TRenderProps>): PageDefinition<TParams> }
+	render(fn: ComponentType<TRenderProps>): PageDefinition<TParams>
+}
+
+interface WithRoute<TParams, TRenderProps> {
+	catch(handler: CatchHandler): WithCatch<TParams, TRenderProps>
+	route<R extends string>(
+		pattern: [ExtractRouteParams<R>] extends [keyof TParams & string] ? R : never,
+	): {
+		catch(handler: CatchHandler): { render(fn: ComponentType<TRenderProps>): PageDefinition<TParams> }
+		render(fn: ComponentType<TRenderProps>): PageDefinition<TParams>
+	}
+	render(fn: ComponentType<TRenderProps>): PageDefinition<TParams>
+}
+
+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>,
+	): WithLoaderChain<TParams, TData & TNew>
+}
+
+interface WithLoader<TParams> extends WithRoute<TParams, PageProps<TParams>> {
+	loader<TData extends Record<string, unknown>>(
+		fn: (ctx: { params: TParams }) => Promise<TData>,
+	): WithLoaderChain<TParams, TData>
+}
+
+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>,
+	): WithLoaderChain<Record<string, never>, TData>
+	catch(handler: CatchHandler): WithCatch<Record<string, never>, PageProps<Record<string, never>>>
+	route<R extends string>(
+		pattern: [ExtractRouteParams<R>] extends [never] ? R : never,
+	): {
+		catch(handler: CatchHandler): { render(fn: ComponentType<PageProps<Record<string, never>>>): PageDefinition }
+		render(fn: ComponentType<PageProps<Record<string, never>>>): PageDefinition
+	}
+	render(fn: ComponentType<PageProps<Record<string, never>>>): PageDefinition
+}
+
+function withCatchAndRender(
+	schema: StandardSchema | undefined,
+	paramsMeta: ParamMeta[],
+	loaders: LoaderFn[],
+	catchHandler: CatchHandler,
+) {
+	return {
+		route(pattern: string) {
+			return {
+				render(fn: ComponentType<any>) {
+					return createPageComponent(schema, paramsMeta, combineLoaders(loaders), pattern, fn, catchHandler)
+				},
+			}
+		},
+		render(fn: ComponentType<any>) {
+			return createPageComponent(schema, paramsMeta, combineLoaders(loaders), undefined, fn, catchHandler)
+		},
+	}
+}
+
+function withRouteAndRender(
+	schema: StandardSchema | undefined,
+	paramsMeta: ParamMeta[],
+	loaders: LoaderFn[],
+) {
+	return {
+		loader(loaderFn: LoaderFn) {
+			return withRouteAndRender(schema, paramsMeta, [...loaders, loaderFn])
+		},
+		catch(handler: CatchHandler) {
+			return withCatchAndRender(schema, paramsMeta, loaders, handler)
+		},
+		route(pattern: string) {
+			return {
+				catch(handler: CatchHandler) {
+					return {
+						render(fn: ComponentType<any>) {
+							return createPageComponent(schema, paramsMeta, combineLoaders(loaders), pattern, fn, handler)
+						},
+					}
+				},
+				render(fn: ComponentType<any>) {
+					return createPageComponent(schema, paramsMeta, combineLoaders(loaders), pattern, fn)
+				},
+			}
+		},
+		render(fn: ComponentType<any>) {
+			return createPageComponent(schema, paramsMeta, combineLoaders(loaders), undefined, fn)
+		},
+	}
+}
+
+export function createPage(): PageBuilder {
+	return {
+		params(input: StandardSchema | ParamsShape) {
+			const { schema, paramsMeta } = resolveParamsInput(input)
+			return withRouteAndRender(schema, paramsMeta, [])
+		},
+		...withRouteAndRender(undefined, [], []),
+	} as PageBuilder
+}

package/src/engine/matcher.ts

@@ -0,0 +1,88 @@
+import type { RouteMatch, RouteNode } from './types'
+
+/**
+ * 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.
+ */
+export function matchRoutes(nodes: RouteNode[], url: URL): RouteMatch[] | null {
+	const pathname = url.pathname
+
+	for (const node of nodes) {
+		const result = matchNode(node, pathname)
+		if (result) return result
+	}
+
+	return null
+}
+
+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]
+			}
+		}
+		return null
+	}
+
+	// Leaf/index nodes: try to match the URLPattern
+	if (node.pattern) {
+		const result = node.pattern.exec({ pathname })
+		if (result) {
+			const params = extractParamsFromResult(result)
+			const match: RouteMatch = { 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]
+					}
+				}
+			}
+
+			return [match]
+		}
+	}
+
+	return null
+}
+
+/**
+ * Extract params from a URLPattern exec result.
+ */
+function extractParamsFromResult(result: URLPatternResult): Record<string, string> {
+	const params: Record<string, string> = {}
+	const groups = result.pathname.groups
+	for (const [key, value] of Object.entries(groups)) {
+		// Skip unnamed groups (numeric keys from wildcards/optionals)
+		if (value !== undefined && !/^\d+$/.test(key)) {
+			params[key] = value
+		}
+	}
+	return params
+}
+
+/**
+ * Extract params from a layout node using its prefix URLPattern.
+ * Falls back to empty params if no prefix pattern is available.
+ */
+function extractLayoutParams(node: RouteNode, pathname: string): Record<string, string> {
+	if (node.prefixPattern) {
+		const result = node.prefixPattern.exec({ pathname })
+		if (result) {
+			return extractParamsFromResult(result)
+		}
+	}
+	return {}
+}