@rangojs/router 0.0.0-experimental.10

package/src/router/trie-matching.ts

@@ -0,0 +1,172 @@
+/**
+ * Runtime Trie Matching
+ *
+ * Walks the pre-built trie by path segments in O(path_length) time.
+ * Falls back to null when no match is found (caller uses regex fallback).
+ */
+
+import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+
+export interface TrieMatchResult {
+  /** Route name */
+  routeKey: string;
+  /** Static prefix of the matched entry */
+  sp: string;
+  /** Matched route params */
+  params: Record<string, string>;
+  /** Optional param names (absent params have empty string value) */
+  optionalParams?: string[];
+  /** Ancestry shortCodes for layout pruning */
+  ancestry: string[];
+  /** Redirect target if trailing slash requires it */
+  redirectTo?: string;
+  /** Route has pre-rendered data available */
+  pr?: true;
+  /** Passthrough: handler kept for live fallback on unknown params */
+  pt?: true;
+  /** Response type for non-RSC routes (json, text, image, any) */
+  responseType?: string;
+  /** Negotiate variants: response-type routes sharing this path */
+  negotiateVariants?: Array<{ routeKey: string; responseType: string }>;
+  /** RSC-first: RSC route was defined before response-type variants */
+  rscFirst?: true;
+}
+
+/**
+ * Try to match a pathname against the trie.
+ * Returns null if no match found (caller should fall back to regex).
+ */
+export function tryTrieMatch(
+  trie: TrieNode | null,
+  pathname: string,
+): TrieMatchResult | null {
+  if (!trie) return null;
+
+  // Split pathname into segments, filtering empty strings from leading/trailing slashes
+  const pathnameHasTrailingSlash = pathname.length > 1 && pathname.endsWith("/");
+  const normalizedPath = pathnameHasTrailingSlash ? pathname.slice(0, -1) : pathname;
+
+  // Handle root path
+  if (normalizedPath === "" || normalizedPath === "/") {
+    if (trie.r) {
+      return validateAndBuild(trie.r, {}, pathname, pathnameHasTrailingSlash);
+    }
+    return null;
+  }
+
+  // Remove leading slash and split
+  const segments = normalizedPath.slice(1).split("/");
+
+  // Try exact match with normalized path (no trailing slash)
+  const result = walkTrie(trie, segments, 0, {});
+  if (result) {
+    return validateAndBuild(result.leaf, result.params, pathname, pathnameHasTrailingSlash);
+  }
+
+  return null;
+}
+
+interface WalkResult {
+  leaf: TrieLeaf;
+  params: Record<string, string>;
+}
+
+/**
+ * Walk the trie by segments with priority: static > param > wildcard.
+ * Uses backtracking to try all possible matches.
+ */
+function walkTrie(
+  node: TrieNode,
+  segments: string[],
+  index: number,
+  params: Record<string, string>,
+): WalkResult | null {
+  // All segments consumed: check for terminal
+  if (index === segments.length) {
+    if (node.r) {
+      return { leaf: node.r, params };
+    }
+    return null;
+  }
+
+  const segment = segments[index];
+
+  // Priority 1: Static match
+  if (node.s?.[segment]) {
+    const result = walkTrie(node.s[segment], segments, index + 1, params);
+    if (result) return result;
+  }
+
+  // Priority 2: Param match
+  if (node.p) {
+    const result = walkTrie(node.p.c, segments, index + 1, {
+      ...params,
+      [node.p.n]: segment,
+    });
+    if (result) return result;
+  }
+
+  // Priority 3: Wildcard match (consumes rest)
+  if (node.w) {
+    const rest = segments.slice(index).join("/");
+    return {
+      leaf: node.w,
+      params: { ...params, [node.w.pn]: rest },
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Post-match: validate constraints and handle trailing slash logic.
+ */
+function validateAndBuild(
+  leaf: TrieLeaf,
+  params: Record<string, string>,
+  originalPathname: string,
+  pathnameHasTrailingSlash: boolean,
+): TrieMatchResult | null {
+  // Validate constraints
+  if (leaf.cv) {
+    for (const [paramName, allowed] of Object.entries(leaf.cv)) {
+      const value = params[paramName];
+      if (value !== undefined && value !== "" && !allowed.includes(value)) {
+        return null;
+      }
+    }
+  }
+
+  // Fill in empty strings for optional params that weren't matched
+  if (leaf.op) {
+    for (const name of leaf.op) {
+      if (!(name in params)) {
+        params[name] = "";
+      }
+    }
+  }
+
+  // Trailing slash handling
+  const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;
+  let redirectTo: string | undefined;
+
+  if (tsMode === "always" && !pathnameHasTrailingSlash && originalPathname !== "/") {
+    redirectTo = originalPathname + "/";
+  } else if (tsMode === "never" && pathnameHasTrailingSlash) {
+    redirectTo = originalPathname.slice(0, -1);
+  }
+
+  return {
+    routeKey: leaf.n,
+    sp: leaf.sp,
+    params,
+    optionalParams: leaf.op,
+    ancestry: leaf.a,
+    ...(redirectTo ? { redirectTo } : {}),
+    ...(leaf.pr ? { pr: true } : {}),
+    ...(leaf.pt ? { pt: true } : {}),
+    ...(leaf.rt ? { responseType: leaf.rt } : {}),
+    ...(leaf.nv ? { negotiateVariants: leaf.nv } : {}),
+    ...(leaf.rf ? { rscFirst: true } : {}),
+  };
+}

package/src/router/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Router Internal Types
+ *
+ * Shared types for router module utilities.
+ */
+
+import type { ReactNode } from "react";
+import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
+import type {
+  ErrorInfo,
+  ErrorPhase,
+  LoaderDataResult,
+  ResolvedSegment,
+  HandlerContext,
+  InternalHandlerContext,
+  ErrorBoundaryHandler,
+  NotFoundBoundaryHandler,
+  ShouldRevalidateFn,
+} from "../types";
+
+/**
+ * Result of resolving loaders with revalidation
+ * Contains both segments to render and all matched segment IDs
+ */
+export interface LoaderRevalidationResult {
+  segments: ResolvedSegment[];
+  matchedIds: string[];
+}
+
+/**
+ * Result of resolving segments with revalidation
+ * Contains both segments to render and all matched segment IDs
+ */
+export interface SegmentRevalidationResult {
+  segments: ResolvedSegment[];
+  matchedIds: string[];
+}
+
+/**
+ * Action context type for revalidation
+ */
+export type ActionContext = {
+  actionId?: string;
+  actionUrl?: URL;
+  actionResult?: any;
+  formData?: FormData;
+};
+
+/**
+ * Dependencies passed to segment resolution functions
+ * These are created within createRouter and passed to extracted utilities
+ */
+export interface RouterDependencies<TEnv> {
+  findNearestErrorBoundary: (
+    entry: EntryData | null
+  ) => ReactNode | ErrorBoundaryHandler | null;
+  findNearestNotFoundBoundary: (
+    entry: EntryData | null
+  ) => ReactNode | NotFoundBoundaryHandler | null;
+}
+
+/**
+ * Dependencies injected from createRouter closure into extracted segment resolution functions.
+ * These are the closure-bound helpers that cannot be imported directly.
+ */
+export interface SegmentResolutionDeps<TEnv = any> {
+  wrapLoaderPromise: <T>(
+    promise: Promise<T>,
+    entry: EntryData,
+    segmentId: string,
+    pathname: string,
+    errorContext?: {
+      request: Request;
+      url: URL;
+      routeKey?: string;
+      params?: Record<string, string>;
+      env?: TEnv;
+      isPartial?: boolean;
+      requestStartTime?: number;
+    },
+  ) => Promise<LoaderDataResult<T>>;
+  trackHandler: <T>(promise: Promise<T>) => Promise<T>;
+  findNearestErrorBoundary: (
+    entry: EntryData | null,
+  ) => ReactNode | ErrorBoundaryHandler | null;
+  findNearestNotFoundBoundary: (
+    entry: EntryData | null,
+  ) => ReactNode | NotFoundBoundaryHandler | null;
+  callOnError: (
+    error: unknown,
+    phase: ErrorPhase,
+    context: any,
+  ) => void;
+}
+
+/**
+ * Dependencies injected from createRouter closure into extracted intercept resolution functions.
+ */
+export interface InterceptResolutionDeps<TEnv = any> {
+  wrapLoaderPromise: SegmentResolutionDeps<TEnv>["wrapLoaderPromise"];
+  evaluateInterceptWhen: (
+    intercept: InterceptEntry,
+    selectorContext: InterceptSelectorContext | null,
+    isAction: boolean,
+  ) => boolean;
+}
+
+/**
+ * Dependencies injected from createRouter closure into extracted match API functions.
+ */
+export interface MatchApiDeps<TEnv = any> {
+  findMatch: (pathname: string, ms?: any) => any;
+  getMetricsStore: () => any;
+  findInterceptForRoute: (
+    routeKey: string,
+    parentEntry: EntryData | null,
+    selectorContext: InterceptSelectorContext | null,
+    isAction: boolean,
+  ) => { intercept: InterceptEntry; entry: EntryData } | null;
+  callOnError: SegmentResolutionDeps<TEnv>["callOnError"];
+  findNearestErrorBoundary: SegmentResolutionDeps<TEnv>["findNearestErrorBoundary"];
+}
+
+/**
+ * Title descriptor types for template support
+ */
+export type TitleDescriptor =
+  | string
+  | { template: string; default: string } // For layouts - template applied to child titles
+  | { absolute: string }; // Bypass parent template
+
+/**
+ * Unset descriptor to remove inherited meta
+ * Key format matches getMetaKey output: "title", "name:description", "property:og:image"
+ */
+export type UnsetDescriptor = { unset: string };
+
+/**
+ * Base meta descriptor types (sync values)
+ */
+export type MetaDescriptorBase =
+  | { charSet: "utf-8" }
+  | { title: TitleDescriptor }
+  | { name: string; content: string }
+  | { property: string; content: string }
+  | { httpEquiv: string; content: string }
+  | { "script:ld+json": LdJsonObject }
+  | { tagName: "meta" | "link"; [name: string]: string }
+  | UnsetDescriptor
+  | { [name: string]: unknown };
+
+/**
+ * Meta descriptor that can be sync or async.
+ * Use Promise<MetaDescriptorBase> for streaming meta that resolves after initial render.
+ */
+export type MetaDescriptor = MetaDescriptorBase | Promise<MetaDescriptorBase>;
+
+type LdJsonObject = { [Key in string]: LdJsonValue } & {
+  [Key in string]?: LdJsonValue | undefined;
+};
+type LdJsonArray = LdJsonValue[] | readonly LdJsonValue[];
+type LdJsonPrimitive = string | number | boolean | null;
+type LdJsonValue = LdJsonPrimitive | LdJsonObject | LdJsonArray;

package/src/router.gen.ts

@@ -0,0 +1,6 @@
+// Auto-generated by @rangojs/router - do not edit
+export const routes = {
+  about: "/about",
+  home: "/",
+} as const;
+export type routes = typeof routes;