@pyreon/router 0.3.1 → 0.5.0

package/lib/types/index2.d.ts

@@ -5,12 +5,16 @@ import { Computed, Signal } from "@pyreon/reactivity";
 //#region src/types.d.ts
 /**
  * Extracts typed params from a path string at compile time.
+ * Supports optional params via `:param?` — their type is `string | undefined`.
  *
  * @example
  * ExtractParams<'/user/:id/posts/:postId'>
  * // → { id: string; postId: string }
+ *
+ * ExtractParams<'/user/:id?'>
+ * // → { id?: string | undefined }
  */
-type ExtractParams<T extends string> = T extends `${string}:${infer Param}*/${infer Rest}` ? { [K in Param]: string } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}*` ? { [K in Param]: string } : T extends `${string}:${infer Param}/${infer Rest}` ? { [K in Param]: string } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}` ? { [K in Param]: string } : Record<never, never>;
+type ExtractParams<T extends string> = T extends `${string}:${infer Param}*/${infer Rest}` ? { [K in Param]: string } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}*` ? { [K in Param]: string } : T extends `${string}:${infer Param}?/${infer Rest}` ? { [K in Param]?: string | undefined } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}?` ? { [K in Param]?: string | undefined } : T extends `${string}:${infer Param}/${infer Rest}` ? { [K in Param]: string } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}` ? { [K in Param]: string } : Record<never, never>;
 /**
  * Route metadata interface. Extend it via module augmentation to add custom fields:
  *
@@ -33,7 +37,7 @@ interface RouteMeta {
   /** Scroll behavior for this route */
   scrollBehavior?: "top" | "restore" | "none";
 }
-interface ResolvedRoute<P extends Record<string, string> = Record<string, string>, Q extends Record<string, string> = Record<string, string>> {
+interface ResolvedRoute<P extends Record<string, string | undefined> = Record<string, string>, Q extends Record<string, string> = Record<string, string>> {
   path: string;
   params: P;
   query: Q;
@@ -63,6 +67,15 @@ type RouteComponent = ComponentFn$1 | LazyComponent;
 type NavigationGuardResult = boolean | string | undefined;
 type NavigationGuard = (to: ResolvedRoute, from: ResolvedRoute) => NavigationGuardResult | Promise<NavigationGuardResult>;
 type AfterEachHook = (to: ResolvedRoute, from: ResolvedRoute) => void;
+/**
+ * Called before each navigation. Return `true` to block, `false` to allow.
+ * Async blockers are supported (e.g. to show a confirmation dialog).
+ */
+type BlockerFn = (to: ResolvedRoute, from: ResolvedRoute) => boolean | Promise<boolean>;
+interface Blocker {
+  /** Unregister this blocker so future navigations proceed freely. */
+  remove(): void;
+}
 interface LoaderContext {
   params: Record<string, string>;
   query: Record<string, string>;
@@ -88,6 +101,14 @@ interface RouteRecord<TPath extends string = string> {
   beforeEnter?: NavigationGuard | NavigationGuard[];
   /** Guard(s) run before leaving this route. Return false to cancel. */
   beforeLeave?: NavigationGuard | NavigationGuard[];
+  /**
+   * Alternative path(s) for this route. Alias paths render the same component
+   * and share guards, loaders, and metadata with the primary path.
+   *
+   * @example
+   * { path: "/user/:id", alias: ["/profile/:id"], component: UserPage }
+   */
+  alias?: string | string[];
   /** Child routes rendered inside this route's component via <RouterView /> */
   children?: RouteRecord[];
   /**
@@ -96,6 +117,12 @@ interface RouteRecord<TPath extends string = string> {
    * Receives an AbortSignal that fires if a newer navigation supersedes this one.
    */
   loader?: RouteLoaderFn;
+  /**
+   * When true, the router shows cached loader data immediately (stale) and
+   * revalidates in the background. The component re-renders once fresh data arrives.
+   * Only applies when navigating to a route that already has cached loader data.
+   */
+  staleWhileRevalidate?: boolean;
   /** Component rendered when this route's loader throws an error */
   errorComponent?: ComponentFn$1;
 }
@@ -104,6 +131,13 @@ interface RouterOptions {
   routes: RouteRecord[];
   /** "hash" (default) uses location.hash; "history" uses pushState */
   mode?: "hash" | "history";
+  /**
+   * Base path for the application. Used when deploying to a sub-path
+   * (e.g. `"/app"` for `https://example.com/app/`).
+   * Only applies in history mode. Must start with `/`.
+   * Default: `""` (no base path).
+   */
+  base?: string;
   /**
    * Global scroll behavior. Per-route meta.scrollBehavior takes precedence.
    * Default: "top"
@@ -130,6 +164,13 @@ interface RouterOptions {
    * Default: 100.
    */
   maxCacheSize?: number;
+  /**
+   * Trailing slash handling:
+   *   - `"strip"` — removes trailing slashes before matching (default)
+   *   - `"add"` — ensures paths always end with `/`
+   *   - `"ignore"` — no normalization
+   */
+  trailingSlash?: "strip" | "add" | "ignore";
 }
 interface Router {
   /** Navigate to a path */
@@ -142,8 +183,18 @@ interface Router {
   }): Promise<void>;
   /** Replace current history entry */
   replace(path: string): Promise<void>;
-  /** Go back */
+  /** Replace current history entry using a named route */
+  replace(location: {
+    name: string;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+  }): Promise<void>;
+  /** Go back one step in history */
   back(): void;
+  /** Go forward one step in history */
+  forward(): void;
+  /** Navigate forward or backward by `delta` steps in the history stack */
+  go(delta: number): void;
   /** Register a global before-navigation guard. Returns an unregister function. */
   beforeEach(guard: NavigationGuard): () => void;
   /** Register a global after-navigation hook. Returns an unregister function. */
@@ -152,12 +203,19 @@ interface Router {
   readonly currentRoute: () => ResolvedRoute;
   /** True while a navigation (guards + loaders) is in flight */
   readonly loading: () => boolean;
+  /**
+   * Promise that resolves once the initial navigation is complete.
+   * Useful for SSR and for delaying rendering until the first route is resolved.
+   */
+  isReady(): Promise<void>;
   /** Remove all event listeners, clear caches, and abort in-flight navigations. */
   destroy(): void;
 }
 interface RouterInstance extends Router {
   routes: RouteRecord[];
   mode: "hash" | "history";
+  /** Normalized base path (e.g. "/app"), empty string if none */
+  _base: string;
   _currentPath: Signal<string>;
   _currentRoute: Computed<ResolvedRoute>;
   _componentCache: Map<RouteRecord, ComponentFn$1>;
@@ -179,6 +237,12 @@ interface RouterInstance extends Router {
   _loaderData: Map<RouteRecord, unknown>;
   /** AbortController for the in-flight loader batch — aborted when a newer navigation starts */
   _abortController: AbortController | null;
+  /** Registered navigation blockers */
+  _blockers: Set<BlockerFn>;
+  /** Resolves the isReady() promise after initial navigation completes */
+  _readyResolve: (() => void) | null;
+  /** The isReady() promise instance */
+  _readyPromise: Promise<void>;
 }
 //#endregion
 //#region src/components.d.ts
@@ -315,8 +379,57 @@ declare function findRouteByName(name: string, routes: RouteRecord[]): RouteReco
 //#region src/router.d.ts
 declare const RouterContext: _pyreon_core0.Context<RouterInstance | null>;
 declare function useRouter(): Router;
-declare function useRoute<TPath extends string = string>(): () => ResolvedRoute<ExtractParams<TPath>, Record<string, string>>;
+declare function useRoute<TPath extends string = string>(): () => ResolvedRoute<ExtractParams<TPath> & Record<string, string>, Record<string, string>>;
+/**
+ * In-component guard: called before the component's route is left.
+ * Return `false` to cancel, a string to redirect, or `undefined`/`true` to proceed.
+ * Automatically removed on component unmount.
+ *
+ * @example
+ * onBeforeRouteLeave((to, from) => {
+ *   if (hasUnsavedChanges()) return false
+ * })
+ */
+declare function onBeforeRouteLeave(guard: NavigationGuard): () => void;
+/**
+ * In-component guard: called when the route changes but the component is reused
+ * (e.g. `/user/1` → `/user/2`). Useful for reacting to param changes.
+ * Automatically removed on component unmount.
+ *
+ * @example
+ * onBeforeRouteUpdate((to, from) => {
+ *   if (!isValidId(to.params.id)) return false
+ * })
+ */
+declare function onBeforeRouteUpdate(guard: NavigationGuard): () => void;
+/**
+ * Register a navigation blocker. The `fn` callback is called before each
+ * navigation — return `true` (or resolve to `true`) to block it.
+ *
+ * Automatically removed on component unmount if called during component setup.
+ * Also installs a `beforeunload` handler so the browser shows a confirmation
+ * dialog when the user tries to close the tab while a blocker is active.
+ *
+ * @example
+ * const blocker = useBlocker((to, from) => {
+ *   return hasUnsavedChanges() && !confirm("Discard changes?")
+ * })
+ * // later: blocker.remove()
+ */
+declare function useBlocker(fn: BlockerFn): Blocker;
+/**
+ * Reactive read/write access to the current route's query parameters.
+ *
+ * Returns `[get, set]` where `get` is a reactive signal producing the merged
+ * query object and `set` navigates to the current path with updated params.
+ *
+ * @example
+ * const [params, setParams] = useSearchParams({ page: "1", sort: "name" })
+ * params().page  // "1" if not in URL
+ * setParams({ page: "2" })  // navigates to ?page=2&sort=name
+ */
+declare function useSearchParams<T extends Record<string, string>>(defaults?: T): [get: () => T, set: (updates: Partial<T>) => Promise<void>];
 declare function createRouter(options: RouterOptions | RouteRecord[]): Router;
 //#endregion
-export { type AfterEachHook, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useLoaderData, useRoute, useRouter };
+export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useLoaderData, useRoute, useRouter, useSearchParams };
 //# sourceMappingURL=index2.d.ts.map

package/lib/types/index2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index2.d.ts","names":[],"sources":["../../src/types.ts","../../src/components.tsx","../../src/loader.ts","../../src/match.ts","../../src/router.ts"],"mappings":"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"}
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../src/types.ts","../../src/components.tsx","../../src/loader.ts","../../src/match.ts","../../src/router.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/router",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Official router for Pyreon",
   "license": "MIT",
   "repository": {
@@ -39,9 +39,9 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.3.1",
-    "@pyreon/reactivity": "^0.3.1",
-    "@pyreon/runtime-dom": "^0.3.1"
+    "@pyreon/core": "^0.5.0",
+    "@pyreon/reactivity": "^0.5.0",
+    "@pyreon/runtime-dom": "^0.5.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.3",

package/src/components.tsx

@@ -146,7 +146,8 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
     prefetchRoute(router as RouterInstance, props.to)
   }
 
-  const href = router?.mode === "history" ? props.to : `#${props.to}`
+  const inst = router as RouterInstance | null
+  const href = inst?.mode === "history" ? `${inst._base}${props.to}` : `#${props.to}`
 
   const activeClass = (): string => {
     if (!router) return ""

package/src/index.ts

@@ -55,11 +55,22 @@ export {
   stringifyQuery,
 } from "./match"
 // Router factory + hooks
-export { createRouter, RouterContext, useRoute, useRouter } from "./router"
+export {
+  createRouter,
+  onBeforeRouteLeave,
+  onBeforeRouteUpdate,
+  RouterContext,
+  useBlocker,
+  useRoute,
+  useRouter,
+  useSearchParams,
+} from "./router"
 // Types
 // Data loaders
 export type {
   AfterEachHook,
+  Blocker,
+  BlockerFn,
   ExtractParams,
   LazyComponent,
   LoaderContext,

package/src/match.ts

@@ -78,7 +78,9 @@ interface CompiledSegment {
   isParam: boolean
   /** true if this segment is a `:param*` splat */
   isSplat: boolean
-  /** Param name (without leading `:` and trailing `*`) — empty for static segments */
+  /** true if this segment is a `:param?` optional */
+  isOptional: boolean
+  /** Param name (without leading `:` and trailing `*`/`?`) — empty for static segments */
   paramName: string
 }
 
@@ -122,6 +124,10 @@ interface FlattenedRoute {
   hasSplat: boolean
   /** true if this is a wildcard catch-all route (`*` or `(.*)`) */
   isWildcard: boolean
+  /** true if any segment is optional (`:param?`) */
+  hasOptional: boolean
+  /** Minimum number of segments that must be present (excluding trailing optionals) */
+  minSegments: number
 }
 
 /** WeakMap cache: compile each RouteRecord[] once */
@@ -129,12 +135,15 @@ const _compiledCache = new WeakMap<RouteRecord[], CompiledRoute[]>()
 
 function compileSegment(raw: string): CompiledSegment {
   if (raw.endsWith("*") && raw.startsWith(":")) {
-    return { raw, isParam: true, isSplat: true, paramName: raw.slice(1, -1) }
+    return { raw, isParam: true, isSplat: true, isOptional: false, paramName: raw.slice(1, -1) }
+  }
+  if (raw.endsWith("?") && raw.startsWith(":")) {
+    return { raw, isParam: true, isSplat: false, isOptional: true, paramName: raw.slice(1, -1) }
   }
   if (raw.startsWith(":")) {
-    return { raw, isParam: true, isSplat: false, paramName: raw.slice(1) }
+    return { raw, isParam: true, isSplat: false, isOptional: false, paramName: raw.slice(1) }
   }
-  return { raw, isParam: false, isSplat: false, paramName: "" }
+  return { raw, isParam: false, isSplat: false, isOptional: false, paramName: "" }
 }
 
 function compileRoute(route: RouteRecord): CompiledRoute {
@@ -172,17 +181,32 @@ function compileRoute(route: RouteRecord): CompiledRoute {
   }
 }
 
+/** Expand alias paths into additional compiled entries sharing the original RouteRecord */
+function expandAliases(r: RouteRecord, c: CompiledRoute): CompiledRoute[] {
+  if (!r.alias) return []
+  const aliases = Array.isArray(r.alias) ? r.alias : [r.alias]
+  return aliases.map((aliasPath) => {
+    const { alias: _, ...withoutAlias } = r
+    const ac = compileRoute({ ...withoutAlias, path: aliasPath })
+    ac.children = c.children
+    ac.route = r
+    return ac
+  })
+}
+
 function compileRoutes(routes: RouteRecord[]): CompiledRoute[] {
   const cached = _compiledCache.get(routes)
   if (cached) return cached
 
-  const compiled = routes.map((r) => {
+  const compiled: CompiledRoute[] = []
+  for (const r of routes) {
     const c = compileRoute(r)
     if (r.children && r.children.length > 0) {
       c.children = compileRoutes(r.children)
     }
-    return c
-  })
+    compiled.push(c)
+    compiled.push(...expandAliases(r, c))
+  }
   _compiledCache.set(routes, compiled)
   return compiled
 }
@@ -204,6 +228,12 @@ function makeFlatEntry(
   isWildcard: boolean,
 ): FlattenedRoute {
   const isStatic = !isWildcard && segments.every((s) => !s.isParam)
+  const hasOptional = segments.some((s) => s.isOptional)
+  // minSegments: count of segments up to and not including trailing optionals
+  let minSegs = segments.length
+  if (hasOptional) {
+    while (minSegs > 0 && segments[minSegs - 1]?.isOptional) minSegs--
+  }
   return {
     segments,
     segmentCount: segments.length,
@@ -214,6 +244,8 @@ function makeFlatEntry(
     firstSegment: getFirstSegment(segments),
     hasSplat: segments.some((s) => s.isSplat),
     isWildcard,
+    hasOptional,
+    minSegments: minSegs,
   }
 }
 
@@ -372,8 +404,31 @@ function decodeSafe(s: string): string {
  *   - Param segments: "/user/:id"
  *   - Wildcard: "(.*)" matches everything
  */
+/** Match a single pattern segment against a path segment, extracting params. Returns false on mismatch. */
+function matchPatternSegment(
+  pp: string,
+  pt: string | undefined,
+  params: Record<string, string>,
+  pathParts: string[],
+  i: number,
+): "splat" | "continue" | "fail" {
+  if (pp.endsWith("*") && pp.startsWith(":")) {
+    params[pp.slice(1, -1)] = pathParts.slice(i).map(decodeURIComponent).join("/")
+    return "splat"
+  }
+  if (pp.endsWith("?") && pp.startsWith(":")) {
+    if (pt !== undefined) params[pp.slice(1, -1)] = decodeURIComponent(pt)
+    return "continue"
+  }
+  if (pt === undefined) return "fail"
+  if (pp.startsWith(":")) {
+    params[pp.slice(1)] = decodeURIComponent(pt)
+    return "continue"
+  }
+  return pp === pt ? "continue" : "fail"
+}
+
 export function matchPath(pattern: string, path: string): Record<string, string> | null {
-  // Wildcard pattern
   if (pattern === "(.*)" || pattern === "*") return {}
 
   const patternParts = pattern.split("/").filter(Boolean)
@@ -381,22 +436,18 @@ export function matchPath(pattern: string, path: string): Record<string, string>
 
   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
-    }
+    const result = matchPatternSegment(
+      patternParts[i] as string,
+      pathParts[i],
+      params,
+      pathParts,
+      i,
+    )
+    if (result === "splat") return params
+    if (result === "fail") return null
   }
 
-  if (patternParts.length !== pathParts.length) return null
+  if (pathParts.length > patternParts.length) return null
   return params
 }
 
@@ -414,16 +465,21 @@ function captureSplat(pathParts: string[], from: number, pathLen: number): strin
 
 // ─── Flattened route matching ─────────────────────────────────────────────────
 
+/** Check whether a flattened route's segment count is compatible with the path length */
+function isSegmentCountCompatible(f: FlattenedRoute, pathLen: number): boolean {
+  if (f.segmentCount === pathLen) return true
+  if (f.hasSplat && pathLen >= f.segmentCount) return true
+  if (f.hasOptional && pathLen >= f.minSegments && pathLen <= f.segmentCount) return true
+  return false
+}
+
 /** Try to match a flattened route against path parts */
 function matchFlattened(
   f: FlattenedRoute,
   pathParts: string[],
   pathLen: number,
 ): Record<string, string> | null {
-  if (f.segmentCount !== pathLen) {
-    // Could still match if route has a splat
-    if (!f.hasSplat || pathLen < f.segmentCount) return null
-  }
+  if (!isSegmentCountCompatible(f, pathLen)) return null
 
   const params: Record<string, string> = {}
   const segments = f.segments
@@ -431,11 +487,15 @@ function matchFlattened(
   for (let i = 0; i < count; i++) {
     const seg = segments[i]
     const pt = pathParts[i]
-    if (!seg || pt === undefined) return null
+    if (!seg) return null
     if (seg.isSplat) {
       params[seg.paramName] = captureSplat(pathParts, i, pathLen)
       return params
     }
+    if (pt === undefined) {
+      if (!seg.isOptional) return null
+      continue
+    }
     if (seg.isParam) {
       params[seg.paramName] = decodeSafe(pt)
     } else if (seg.raw !== pt) {
@@ -564,7 +624,13 @@ function mergeMeta(matched: RouteRecord[]): RouteMeta {
 
 /** 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 built = pattern.replace(/\/:([^/]+)\?/g, (_match, key) => {
+    const val = params[key]
+    // Optional param — omit the entire segment if no value provided
+    if (!val) return ""
+    return `/${encodeURIComponent(val)}`
+  })
+  return built.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("/")