@pyreon/router 0.1.0

package/src/match.ts

@@ -0,0 +1,264 @@
+import type { ResolvedRoute, RouteMeta, RouteRecord } from "./types"
+
+// ─── Query string ─────────────────────────────────────────────────────────────
+
+/**
+ * Parse a query string into key-value pairs. Duplicate keys are overwritten
+ * (last value wins). Use `parseQueryMulti` to preserve duplicates as arrays.
+ */
+export function parseQuery(qs: string): Record<string, string> {
+  if (!qs) return {}
+  const result: Record<string, string> = {}
+  for (const part of qs.split("&")) {
+    const eqIdx = part.indexOf("=")
+    if (eqIdx < 0) {
+      const key = decodeURIComponent(part)
+      if (key) result[key] = ""
+    } else {
+      const key = decodeURIComponent(part.slice(0, eqIdx))
+      const val = decodeURIComponent(part.slice(eqIdx + 1))
+      if (key) result[key] = val
+    }
+  }
+  return result
+}
+
+/**
+ * Parse a query string preserving duplicate keys as arrays.
+ *
+ * @example
+ * parseQueryMulti("color=red&color=blue&size=lg")
+ * // → { color: ["red", "blue"], size: "lg" }
+ */
+export function parseQueryMulti(qs: string): Record<string, string | string[]> {
+  if (!qs) return {}
+  const result: Record<string, string | string[]> = {}
+  for (const part of qs.split("&")) {
+    const eqIdx = part.indexOf("=")
+    let key: string
+    let val: string
+    if (eqIdx < 0) {
+      key = decodeURIComponent(part)
+      val = ""
+    } else {
+      key = decodeURIComponent(part.slice(0, eqIdx))
+      val = decodeURIComponent(part.slice(eqIdx + 1))
+    }
+    if (!key) continue
+    const existing = result[key]
+    if (existing === undefined) {
+      result[key] = val
+    } else if (Array.isArray(existing)) {
+      existing.push(val)
+    } else {
+      result[key] = [existing, val]
+    }
+  }
+  return result
+}
+
+export function stringifyQuery(query: Record<string, string>): string {
+  const parts: string[] = []
+  for (const [k, v] of Object.entries(query)) {
+    parts.push(v ? `${encodeURIComponent(k)}=${encodeURIComponent(v)}` : encodeURIComponent(k))
+  }
+  return parts.length ? `?${parts.join("&")}` : ""
+}
+
+// ─── Path matching ────────────────────────────────────────────────────────────
+
+/**
+ * Match a single route pattern against a path segment.
+ * Returns extracted params or null if no match.
+ *
+ * Supports:
+ *   - Exact segments: "/about"
+ *   - Param segments: "/user/:id"
+ *   - Wildcard: "(.*)" matches everything
+ */
+export function matchPath(pattern: string, path: string): Record<string, string> | null {
+  // Wildcard pattern
+  if (pattern === "(.*)" || pattern === "*") return {}
+
+  const patternParts = pattern.split("/").filter(Boolean)
+  const pathParts = path.split("/").filter(Boolean)
+
+  const params: Record<string, string> = {}
+  for (let i = 0; i < patternParts.length; i++) {
+    const pp = patternParts[i] as string
+    const pt = pathParts[i] as string
+    // Splat param — captures the rest of the path (e.g. ":path*")
+    if (pp.endsWith("*") && pp.startsWith(":")) {
+      const paramName = pp.slice(1, -1)
+      params[paramName] = pathParts.slice(i).map(decodeURIComponent).join("/")
+      return params
+    }
+    if (pp.startsWith(":")) {
+      params[pp.slice(1)] = decodeURIComponent(pt)
+    } else if (pp !== pt) {
+      return null
+    }
+  }
+
+  if (patternParts.length !== pathParts.length) return null
+  return params
+}
+
+/**
+ * Check if a path starts with a route's prefix (for nested route matching).
+ * Returns the remaining path suffix, or null if no match.
+ */
+function matchPrefix(
+  pattern: string,
+  path: string,
+): { params: Record<string, string>; rest: string } | null {
+  if (pattern === "(.*)" || pattern === "*") return { params: {}, rest: path }
+
+  const patternParts = pattern.split("/").filter(Boolean)
+  const pathParts = path.split("/").filter(Boolean)
+
+  if (pathParts.length < patternParts.length) return null
+
+  const params: Record<string, string> = {}
+  for (let i = 0; i < patternParts.length; i++) {
+    const pp = patternParts[i] as string
+    const pt = pathParts[i] as string
+    // Splat param in prefix — captures the rest
+    if (pp.endsWith("*") && pp.startsWith(":")) {
+      const paramName = pp.slice(1, -1)
+      params[paramName] = pathParts.slice(i).map(decodeURIComponent).join("/")
+      return { params, rest: "/" }
+    }
+    if (pp.startsWith(":")) {
+      params[pp.slice(1)] = decodeURIComponent(pt)
+    } else if (pp !== pt) {
+      return null
+    }
+  }
+
+  const rest = `/${pathParts.slice(patternParts.length).join("/")}`
+  return { params, rest }
+}
+
+// ─── Route resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a raw path (including query string and hash) against the route tree.
+ * Handles nested routes recursively.
+ */
+export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRoute {
+  const qIdx = rawPath.indexOf("?")
+  const pathAndHash = qIdx >= 0 ? rawPath.slice(0, qIdx) : rawPath
+  const queryPart = qIdx >= 0 ? rawPath.slice(qIdx + 1) : ""
+
+  const hIdx = pathAndHash.indexOf("#")
+  const cleanPath = hIdx >= 0 ? pathAndHash.slice(0, hIdx) : pathAndHash
+  const hash = hIdx >= 0 ? pathAndHash.slice(hIdx + 1) : ""
+
+  const query = parseQuery(queryPart)
+
+  const match = matchRoutes(cleanPath, routes, [])
+  if (match) {
+    return {
+      path: cleanPath,
+      params: match.params,
+      query,
+      hash,
+      matched: match.matched,
+      meta: mergeMeta(match.matched),
+    }
+  }
+
+  return { path: cleanPath, params: {}, query, hash, matched: [], meta: {} }
+}
+
+interface MatchResult {
+  params: Record<string, string>
+  matched: RouteRecord[]
+}
+
+function matchRoutes(
+  path: string,
+  routes: RouteRecord[],
+  parentMatched: RouteRecord[],
+  parentParams: Record<string, string> = {},
+): MatchResult | null {
+  for (const route of routes) {
+    const result = matchSingleRoute(path, route, parentMatched, parentParams)
+    if (result) return result
+  }
+  return null
+}
+
+function matchSingleRoute(
+  path: string,
+  route: RouteRecord,
+  parentMatched: RouteRecord[],
+  parentParams: Record<string, string>,
+): MatchResult | null {
+  if (!route.children || route.children.length === 0) {
+    const params = matchPath(route.path, path)
+    if (params === null) return null
+    return { params: { ...parentParams, ...params }, matched: [...parentMatched, route] }
+  }
+
+  const prefix = matchPrefix(route.path, path)
+  if (prefix === null) return null
+
+  const allParams = { ...parentParams, ...prefix.params }
+  const matched = [...parentMatched, route]
+
+  const childMatch = matchRoutes(prefix.rest, route.children, matched, allParams)
+  if (childMatch) return childMatch
+
+  const exactParams = matchPath(route.path, path)
+  if (exactParams === null) return null
+  return { params: { ...parentParams, ...exactParams }, matched }
+}
+
+/** Merge meta from matched routes (leaf takes precedence) */
+function mergeMeta(matched: RouteRecord[]): RouteMeta {
+  const meta: RouteMeta = {}
+  for (const record of matched) {
+    if (record.meta) Object.assign(meta, record.meta)
+  }
+  return meta
+}
+
+/** Build a path string from a named route's pattern and params */
+export function buildPath(pattern: string, params: Record<string, string>): string {
+  return pattern.replace(/:([^/]+)\*?/g, (match, key) => {
+    const val = params[key] ?? ""
+    // Splat params contain slashes — don't encode them
+    if (match.endsWith("*")) return val.split("/").map(encodeURIComponent).join("/")
+    return encodeURIComponent(val)
+  })
+}
+
+/** Find a route record by name (recursive, O(n)). Prefer buildNameIndex for repeated lookups. */
+export function findRouteByName(name: string, routes: RouteRecord[]): RouteRecord | null {
+  for (const route of routes) {
+    if (route.name === name) return route
+    if (route.children) {
+      const found = findRouteByName(name, route.children)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+/**
+ * Pre-build a name → RouteRecord index from a route tree for O(1) named navigation.
+ * Called once at router creation time; avoids O(n) depth-first search per push({ name }).
+ */
+export function buildNameIndex(routes: RouteRecord[]): Map<string, RouteRecord> {
+  const index = new Map<string, RouteRecord>()
+  function walk(list: RouteRecord[]): void {
+    for (const route of list) {
+      if (route.name) index.set(route.name, route)
+      if (route.children) walk(route.children)
+    }
+  }
+  walk(routes)
+  return index
+}

package/src/router.ts

@@ -0,0 +1,451 @@
+import { createContext, useContext } from "@pyreon/core"
+import { computed, signal } from "@pyreon/reactivity"
+import { buildNameIndex, buildPath, resolveRoute } from "./match"
+import { ScrollManager } from "./scroll"
+import {
+  type AfterEachHook,
+  type ComponentFn,
+  isLazy,
+  type LoaderContext,
+  type NavigationGuard,
+  type NavigationGuardResult,
+  type ResolvedRoute,
+  type RouteRecord,
+  type Router,
+  type RouterInstance,
+  type RouterOptions,
+} from "./types"
+
+// Evaluated once at module load — collapses to `true` in browser / happy-dom,
+// `false` on the server. Using a constant avoids per-call `typeof` branches
+// that are uncoverable in test environments.
+const _isBrowser = typeof window !== "undefined"
+
+// ─── Router context ───────────────────────────────────────────────────────────
+// Context-based access: isolated per request in SSR (ALS-backed via
+// @pyreon/runtime-server), isolated per component tree in CSR.
+// Falls back to the module-level singleton for code running outside a component
+// tree (e.g. programmatic navigation from event handlers).
+
+export const RouterContext = createContext<RouterInstance | null>(null)
+
+// Module-level fallback — safe for CSR (single-threaded), not for concurrent SSR.
+// RouterProvider also sets this so legacy useRouter() calls outside the tree work.
+let _activeRouter: RouterInstance | null = null
+
+export function getActiveRouter(): RouterInstance | null {
+  return useContext(RouterContext) ?? _activeRouter
+}
+
+export function setActiveRouter(router: RouterInstance | null): void {
+  if (router) router._viewDepth = 0
+  _activeRouter = router
+}
+
+// ─── Hooks ────────────────────────────────────────────────────────────────────
+
+export function useRouter(): Router {
+  const router = useContext(RouterContext) ?? _activeRouter
+  if (!router)
+    throw new Error(
+      "[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.",
+    )
+  return router
+}
+
+export function useRoute<TPath extends string = string>(): () => ResolvedRoute<
+  import("./types").ExtractParams<TPath>,
+  Record<string, string>
+> {
+  const router = useContext(RouterContext) ?? _activeRouter
+  if (!router)
+    throw new Error(
+      "[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.",
+    )
+  return router.currentRoute as never
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createRouter(options: RouterOptions | RouteRecord[]): Router {
+  const opts: RouterOptions = Array.isArray(options) ? { routes: options } : options
+  const { routes, mode = "hash", scrollBehavior, onError, maxCacheSize = 100 } = opts
+
+  // Pre-built O(1) name → record index. Computed once at startup.
+  const nameIndex = buildNameIndex(routes)
+
+  const guards: NavigationGuard[] = []
+  const afterHooks: AfterEachHook[] = []
+  const scrollManager = new ScrollManager(scrollBehavior)
+
+  // Navigation generation counter — cancels in-flight navigations when a newer
+  // one starts. Prevents out-of-order completion from stale async guards.
+  let _navGen = 0
+
+  // ── Initial location ──────────────────────────────────────────────────────
+
+  const getInitialLocation = (): string => {
+    // SSR: use explicitly provided url
+    if (opts.url) return opts.url
+    if (!_isBrowser) return "/"
+    if (mode === "history") {
+      return window.location.pathname + window.location.search
+    }
+    const hash = window.location.hash
+    return hash.startsWith("#") ? hash.slice(1) || "/" : "/"
+  }
+
+  const getCurrentLocation = (): string => {
+    if (!_isBrowser) return currentPath()
+    if (mode === "history") {
+      return window.location.pathname + window.location.search
+    }
+    const hash = window.location.hash
+    return hash.startsWith("#") ? hash.slice(1) || "/" : "/"
+  }
+
+  // ── Signals ───────────────────────────────────────────────────────────────
+
+  const currentPath = signal(getInitialLocation())
+  const currentRoute = computed<ResolvedRoute>(() => resolveRoute(currentPath(), routes))
+
+  // Browser event listeners — stored so destroy() can remove them
+  let _popstateHandler: (() => void) | null = null
+  let _hashchangeHandler: (() => void) | null = null
+
+  if (_isBrowser) {
+    if (mode === "history") {
+      _popstateHandler = () => currentPath.set(getCurrentLocation())
+      window.addEventListener("popstate", _popstateHandler)
+    } else {
+      _hashchangeHandler = () => currentPath.set(getCurrentLocation())
+      window.addEventListener("hashchange", _hashchangeHandler)
+    }
+  }
+
+  const componentCache = new Map<RouteRecord, ComponentFn>()
+  const loadingSignal = signal(0)
+
+  // ── Navigation ────────────────────────────────────────────────────────────
+
+  type GuardOutcome =
+    | { action: "continue" }
+    | { action: "cancel" }
+    | { action: "redirect"; target: string }
+
+  async function evaluateGuard(
+    guard: NavigationGuard,
+    to: ResolvedRoute,
+    from: ResolvedRoute,
+    gen: number,
+  ): Promise<GuardOutcome> {
+    const result = await runGuard(guard, to, from)
+    if (gen !== _navGen) return { action: "cancel" }
+    if (result === false) return { action: "cancel" }
+    if (typeof result === "string") return { action: "redirect", target: result }
+    return { action: "continue" }
+  }
+
+  async function runRouteGuards(
+    records: RouteRecord[],
+    guardKey: "beforeLeave" | "beforeEnter",
+    to: ResolvedRoute,
+    from: ResolvedRoute,
+    gen: number,
+  ): Promise<GuardOutcome> {
+    for (const record of records) {
+      const raw = record[guardKey]
+      if (!raw) continue
+      const routeGuards = Array.isArray(raw) ? raw : [raw]
+      for (const guard of routeGuards) {
+        const outcome = await evaluateGuard(guard, to, from, gen)
+        if (outcome.action !== "continue") return outcome
+      }
+    }
+    return { action: "continue" }
+  }
+
+  async function runGlobalGuards(
+    globalGuards: NavigationGuard[],
+    to: ResolvedRoute,
+    from: ResolvedRoute,
+    gen: number,
+  ): Promise<GuardOutcome> {
+    for (const guard of globalGuards) {
+      const outcome = await evaluateGuard(guard, to, from, gen)
+      if (outcome.action !== "continue") return outcome
+    }
+    return { action: "continue" }
+  }
+
+  function processLoaderResult(
+    result: PromiseSettledResult<unknown>,
+    record: RouteRecord,
+    ac: AbortController,
+    to: ResolvedRoute,
+  ): boolean {
+    if (result.status === "fulfilled") {
+      router._loaderData.set(record, result.value)
+      return true
+    }
+    if (ac.signal.aborted) return true
+    if (router._onError) {
+      const cancel = router._onError(result.reason, to)
+      if (cancel === false) return false
+    }
+    router._loaderData.set(record, undefined)
+    return true
+  }
+
+  function syncBrowserUrl(path: string, replace: boolean): void {
+    if (!_isBrowser) return
+    const url = mode === "history" ? path : `#${path}`
+    if (replace) {
+      window.history.replaceState(null, "", url)
+    } else {
+      window.history.pushState(null, "", url)
+    }
+  }
+
+  function resolveRedirect(to: ResolvedRoute): string | null {
+    const leaf = to.matched[to.matched.length - 1]
+    if (!leaf?.redirect) return null
+    return sanitizePath(typeof leaf.redirect === "function" ? leaf.redirect(to) : leaf.redirect)
+  }
+
+  async function runAllGuards(
+    to: ResolvedRoute,
+    from: ResolvedRoute,
+    gen: number,
+  ): Promise<GuardOutcome> {
+    const leaveOutcome = await runRouteGuards(from.matched, "beforeLeave", to, from, gen)
+    if (leaveOutcome.action !== "continue") return leaveOutcome
+
+    const enterOutcome = await runRouteGuards(to.matched, "beforeEnter", to, from, gen)
+    if (enterOutcome.action !== "continue") return enterOutcome
+
+    return runGlobalGuards(guards, to, from, gen)
+  }
+
+  async function runLoaders(to: ResolvedRoute, gen: number, ac: AbortController): Promise<boolean> {
+    const loadableRecords = to.matched.filter((r) => r.loader)
+    if (loadableRecords.length === 0) return true
+
+    const loaderCtx: LoaderContext = { params: to.params, query: to.query, signal: ac.signal }
+    const results = await Promise.allSettled(
+      loadableRecords.map((r) => {
+        if (!r.loader) return Promise.resolve(undefined)
+        return r.loader(loaderCtx)
+      }),
+    )
+    if (gen !== _navGen) return false
+
+    for (let i = 0; i < loadableRecords.length; i++) {
+      const result = results[i]
+      const record = loadableRecords[i]
+      if (!result || !record) continue
+      if (!processLoaderResult(result, record, ac, to)) return false
+    }
+    return true
+  }
+
+  function commitNavigation(
+    path: string,
+    replace: boolean,
+    to: ResolvedRoute,
+    from: ResolvedRoute,
+  ): void {
+    scrollManager.save(from.path)
+    currentPath.set(path)
+    syncBrowserUrl(path, replace)
+
+    if (_isBrowser && to.meta.title) {
+      document.title = to.meta.title
+    }
+
+    for (const record of router._loaderData.keys()) {
+      if (!to.matched.includes(record)) {
+        router._loaderData.delete(record)
+      }
+    }
+
+    for (const hook of afterHooks) {
+      try {
+        hook(to, from)
+      } catch (_err) {
+        /* hook errors silently ignored */
+      }
+    }
+
+    if (_isBrowser) {
+      queueMicrotask(() => scrollManager.restore(to, from))
+    }
+  }
+
+  async function navigate(path: string, replace: boolean, redirectDepth = 0): Promise<void> {
+    if (redirectDepth > 10) return
+
+    const gen = ++_navGen
+    loadingSignal.update((n) => n + 1)
+
+    const to = resolveRoute(path, routes)
+    const from = currentRoute()
+
+    const redirectTarget = resolveRedirect(to)
+    if (redirectTarget !== null) {
+      loadingSignal.update((n) => n - 1)
+      return navigate(redirectTarget, replace, redirectDepth + 1)
+    }
+
+    const guardOutcome = await runAllGuards(to, from, gen)
+    if (guardOutcome.action !== "continue") {
+      loadingSignal.update((n) => n - 1)
+      if (guardOutcome.action === "redirect") {
+        return navigate(sanitizePath(guardOutcome.target), replace, redirectDepth + 1)
+      }
+      return
+    }
+
+    router._abortController?.abort()
+    const ac = new AbortController()
+    router._abortController = ac
+
+    const loadersOk = await runLoaders(to, gen, ac)
+    if (!loadersOk) {
+      loadingSignal.update((n) => n - 1)
+      return
+    }
+
+    commitNavigation(path, replace, to, from)
+    loadingSignal.update((n) => n - 1)
+  }
+
+  // ── Public router object ──────────────────────────────────────────────────
+
+  const router: RouterInstance = {
+    routes,
+    mode,
+    currentRoute,
+    _currentPath: currentPath,
+    _currentRoute: currentRoute,
+    _componentCache: componentCache,
+    _loadingSignal: loadingSignal,
+    _scrollPositions: new Map(),
+    _scrollBehavior: scrollBehavior,
+    _viewDepth: 0,
+    _erroredChunks: new Set(),
+    _loaderData: new Map(),
+    _abortController: null,
+    _onError: onError,
+    _maxCacheSize: maxCacheSize,
+
+    async push(
+      location:
+        | string
+        | { name: string; params?: Record<string, string>; query?: Record<string, string> },
+    ) {
+      if (typeof location === "string") return navigate(sanitizePath(location), false)
+      const path = resolveNamedPath(
+        location.name,
+        location.params ?? {},
+        location.query ?? {},
+        nameIndex,
+      )
+      return navigate(path, false)
+    },
+
+    async replace(path: string) {
+      return navigate(sanitizePath(path), true)
+    },
+
+    back() {
+      if (_isBrowser) window.history.back()
+    },
+
+    beforeEach(guard: NavigationGuard) {
+      guards.push(guard)
+      return () => {
+        const idx = guards.indexOf(guard)
+        if (idx >= 0) guards.splice(idx, 1)
+      }
+    },
+
+    afterEach(hook: AfterEachHook) {
+      afterHooks.push(hook)
+      return () => {
+        const idx = afterHooks.indexOf(hook)
+        if (idx >= 0) afterHooks.splice(idx, 1)
+      }
+    },
+
+    loading: () => loadingSignal() > 0,
+
+    destroy() {
+      if (_popstateHandler) {
+        window.removeEventListener("popstate", _popstateHandler)
+        _popstateHandler = null
+      }
+      if (_hashchangeHandler) {
+        window.removeEventListener("hashchange", _hashchangeHandler)
+        _hashchangeHandler = null
+      }
+      guards.length = 0
+      afterHooks.length = 0
+      componentCache.clear()
+      router._loaderData.clear()
+      router._abortController?.abort()
+      router._abortController = null
+    },
+
+    _resolve: (rawPath: string) => resolveRoute(rawPath, routes),
+  }
+
+  return router
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function runGuard(
+  guard: NavigationGuard,
+  to: ResolvedRoute,
+  from: ResolvedRoute,
+): Promise<NavigationGuardResult> {
+  try {
+    return await guard(to, from)
+  } catch (_err) {
+    return false
+  }
+}
+
+function resolveNamedPath(
+  name: string,
+  params: Record<string, string>,
+  query: Record<string, string>,
+  index: Map<string, RouteRecord>,
+): string {
+  const record = index.get(name)
+  if (!record) {
+    return "/"
+  }
+  let path = buildPath(record.path, params)
+  const qs = Object.entries(query)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&")
+  if (qs) path += `?${qs}`
+  return path
+}
+
+/** Block unsafe navigation targets: javascript/data/vbscript URIs and absolute URLs. */
+function sanitizePath(path: string): string {
+  const trimmed = path.trim()
+  if (/^(?:javascript|data|vbscript):/i.test(trimmed)) {
+    return "/"
+  }
+  // Block absolute URLs and protocol-relative URLs — router only handles same-origin paths
+  if (/^\/\/|^https?:/i.test(trimmed)) {
+    return "/"
+  }
+  return path
+}
+
+export { isLazy }