@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/dist/types/reverse.d.ts

@@ -0,0 +1,206 @@
+import type { ExtractParams } from "./types.js";
+import type { SearchSchema, ResolveSearchSchema } from "./search-params.js";
+/**
+ * Sanitize prefix string by removing leading slash
+ * "/shop" -> "shop", "blog" -> "blog", "" -> ""
+ */
+export type SanitizePrefix<T extends string> = T extends `/${infer P}` ? P : T;
+/**
+ * Helper type to merge multiple route definitions into a single accumulated type.
+ *
+ * @example
+ * ```typescript
+ * type AppRoutes = MergeRoutes<[typeof siteRoutes, typeof apiRoutes]>;
+ * ```
+ */
+export type MergeRoutes<T extends unknown[]> = T extends [
+    infer First,
+    ...infer Rest
+] ? First & MergeRoutes<Rest> : {};
+/**
+ * Helper to safely extract route patterns from a routes object
+ * Handles string values, { path, response } objects, and interface types (like RegisteredRoutes)
+ */
+type RoutePatternFor<TRoutes, TName extends keyof TRoutes> = TRoutes[TName] extends string ? TRoutes[TName] : TRoutes[TName] extends {
+    readonly path: infer P extends string;
+} ? P : string;
+/**
+ * Extract params type for a route
+ */
+export type ParamsFor<TRoutes, TName extends keyof TRoutes> = ExtractParams<RoutePatternFor<TRoutes, TName>>;
+/**
+ * Check if an object type has any keys
+ */
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+/**
+ * Extract search schema from a route entry.
+ * Returns {} if no search schema is defined.
+ */
+type ExtractSearchSchema<TRoutes, TName extends keyof TRoutes> = TRoutes[TName] extends {
+    readonly search: infer S extends SearchSchema;
+} ? S : {};
+/**
+ * Type-safe reverse function signature (Django-style URL reversal)
+ *
+ * Validates route names and params at compile time.
+ * Use route names instead of raw paths for full type safety.
+ *
+ * @example
+ * ```typescript
+ * reverse("cart")                           // ✓ Validates route exists
+ * reverse("product.detail", { id: "123" })  // ✓ Validates route + params
+ * ```
+ */
+export type ReverseFunction<TRoutes> = {
+    /**
+     * Route without params - validates route name exists
+     */
+    <TName extends keyof TRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TRoutes, TName>>> extends true ? TName : never): string;
+    /**
+     * Route with params - validates both route name and params
+     */
+    <TName extends keyof TRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TRoutes, TName>>): string;
+    /**
+     * Route with params and search - validates route name, params, and search
+     */
+    <TName extends keyof TRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TRoutes, TName>>): string;
+    /**
+     * Dot-prefixed route without params - strictly local resolution
+     */
+    <TName extends keyof TRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TRoutes, TName>>> extends true ? `.${TName}` : never): string;
+    /**
+     * Dot-prefixed route with params - strictly local resolution
+     */
+    <TName extends keyof TRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TRoutes, TName>>): string;
+    /**
+     * Dot-prefixed route with params and search - strictly local resolution
+     */
+    <TName extends keyof TRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TRoutes, TName>>): string;
+};
+/**
+ * Type-safe scoped reverse function with separate local and global namespaces.
+ *
+ * - `.name` — local resolution within the current include() scope
+ * - `name` — global resolution against the named-routes definition
+ *
+ * @example
+ * ```typescript
+ * reverse(".article", { slug: "hello" })     // ✓ Local route (resolves with mount prefix)
+ * reverse(".index")                           // ✓ Local route (no params)
+ * reverse("magazine.index")                   // ✓ Global route (fully qualified)
+ * reverse("blog.post", { slug: "hello" })     // ✓ Global route + params
+ * reverse(".typo")                            // ✗ Compile error (not in local routes)
+ * reverse("typo")                             // ✗ Compile error (not in global routes)
+ * ```
+ */
+export type ScopedReverseFunction<TLocalRoutes, TGlobalRoutes = TLocalRoutes> = {
+    /**
+     * Global route without params
+     */
+    <TName extends keyof TGlobalRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>> extends true ? TName : never): string;
+    /**
+     * Global route with params
+     */
+    <TName extends keyof TGlobalRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>): string;
+    /**
+     * Global route with params and search
+     */
+    <TName extends keyof TGlobalRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TGlobalRoutes, TName>>): string;
+    /**
+     * Dot-prefixed local route without params
+     */
+    <TName extends keyof TLocalRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TLocalRoutes, TName>>> extends true ? `.${TName}` : never): string;
+    /**
+     * Dot-prefixed local route with params
+     */
+    <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>): string;
+    /**
+     * Dot-prefixed local route with params and search
+     */
+    <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>): string;
+};
+/**
+ * Extract local routes type from UrlPatterns
+ * Used with scopedReverse() to get the routes type from patterns
+ */
+export type ExtractLocalRoutes<TPatterns> = TPatterns extends {
+    readonly _routes?: infer TRoutes;
+} ? TRoutes : TPatterns extends Record<string, string> ? TPatterns : Record<string, string>;
+/**
+ * Params accepted by `useReverse(routes)`. The route's own params are
+ * required, and additional string keys are permitted so callers can
+ * override values that would otherwise be auto-filled from the matched
+ * route's `useParams()` (e.g. an enclosing `:tenantId` mount segment).
+ */
+export type LocalReverseParams<TPattern extends string> = ExtractParams<TPattern> & {
+    readonly [extra: string]: string | undefined;
+};
+/**
+ * Type-safe local reverse function.
+ *
+ * Returned by `useReverse(routes)` on the client. The route map is the
+ * exposure boundary (a generated `routes` from a `urls()` module) and the
+ * scope is implicit from that import. Names may be written with or without a
+ * leading dot — `reverse("post")` and `reverse(".post")` are identical. The dot
+ * is a cosmetic readability convention (and parity with `ctx.reverse(".name")`);
+ * there is no separate global namespace here, so it carries no meaning.
+ *
+ * @example
+ * ```typescript
+ * const reverse = useReverse(blogRoutes);
+ * reverse("index");                          // ✓ no params (dot optional)
+ * reverse(".index");                         // ✓ identical to the above
+ * reverse("post", { postId: "hello" });      // ✓ with params
+ * reverse("search", {}, { q: "hi" });        // ✓ with search schema
+ * reverse("typo");                           // ✗ compile error
+ * ```
+ */
+export type LocalReverseFunction<TLocalRoutes> = {
+    /**
+     * Route without params (leading dot optional)
+     */
+    <TName extends keyof TLocalRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TLocalRoutes, TName>>> extends true ? TName | `.${TName}` : never): string;
+    /**
+     * Route with params (leading dot optional)
+     */
+    <TName extends keyof TLocalRoutes & string>(name: TName | `.${TName}`, params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>): string;
+    /**
+     * Route with params and search (leading dot optional)
+     */
+    <TName extends keyof TLocalRoutes & string>(name: TName | `.${TName}`, params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>): string;
+};
+/**
+ * Extract the response data type for a named route from a UrlPatterns instance.
+ * Re-exported from urls.ts for consumer convenience.
+ */
+export type { RouteResponse } from "./urls.js";
+/**
+ * Get a locally-typed reverse function from ctx.reverse for composable modules.
+ *
+ * This is a type-only cast - ctx.reverse already resolves names at runtime.
+ * Provides type safety: `.name` validates against local routes,
+ * `name` validates against global named-routes.
+ *
+ * @param reverse - The ctx.reverse function from HandlerContext
+ * @returns The same reverse function, typed with local + global routes
+ *
+ * @example
+ * ```typescript
+ * // urls/blog.tsx
+ * export const blogPatterns = urls(({ path }) => [
+ *   path("/", (ctx) => {
+ *     const reverse = scopedReverse<typeof blogPatterns>(ctx.reverse);
+ *
+ *     reverse(".index");              // ✓ Local route
+ *     reverse(".post", { slug: "x" }); // ✓ Local with params
+ *     reverse("shop.cart");           // ✓ Global route
+ *
+ *     return <BlogIndex />;
+ *   }, { name: "index" }),
+ *
+ *   path("/:slug", BlogPost, { name: "post" }),
+ * ]);
+ * ```
+ */
+export declare function scopedReverse<TPatterns>(reverse: (...args: any[]) => string): ScopedReverseFunction<ExtractLocalRoutes<TPatterns>>;
+export declare function createReverse<TRoutes extends Record<string, string>>(routeMap: TRoutes): ReverseFunction<TRoutes & Record<string, string>>;

package/dist/types/root-error-boundary.d.ts

@@ -0,0 +1,32 @@
+import { Component, type ReactNode } from "react";
+interface RootErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Root error boundary component
+ *
+ * Wraps the entire segment tree to catch any unhandled errors that bubble up.
+ * This prevents the entire app from crashing with a white screen.
+ *
+ * This is a client component with an inline fallback to avoid the
+ * "Functions cannot be passed to Client Components" RSC error.
+ */
+export declare class RootErrorBoundary extends Component<{
+    children: ReactNode;
+}, RootErrorBoundaryState> {
+    constructor(props: {
+        children: ReactNode;
+    });
+    static getDerivedStateFromError(error: Error): RootErrorBoundaryState;
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    componentDidUpdate(prevProps: {
+        children: ReactNode;
+    }): void;
+    handlePopState: () => void;
+    reset: () => void;
+    render(): ReactNode;
+}
+export {};

package/dist/types/route-content-wrapper.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Stable async wrapper component for route content
+ * Using a module-level component ensures React sees the same component reference
+ * across renders, preventing unnecessary remounts during actions.
+ *
+ * When content is a pending promise, React suspends and shows the nearest
+ * Suspense fallback. When content is already resolved, it renders immediately
+ * without suspension.
+ *
+ * @param segmentId - Stable ID from segment, used for consistent keys across renders
+ */
+export declare function RouteContentWrapper({ content, fallback, segmentId, }: {
+    content: Promise<ReactNode> | ReactNode;
+    fallback?: ReactNode;
+    segmentId?: string;
+}): ReactNode;
+/**
+ * LoaderBoundary - Client component that resolves loader promises and renders OutletProvider
+ *
+ * This component enables streaming with loaders by:
+ * 1. Receiving loader promises (serializable across RSC boundary)
+ * 2. Using React's use() to resolve them (triggers Suspense)
+ * 3. Rendering OutletProvider with resolved data
+ *
+ * The callback logic lives inside this client component, avoiding the
+ * "Functions are not valid as a child of Client Components" error.
+ */
+export interface LoaderBoundaryProps {
+    loaderDataPromise: Promise<any[]> | any[];
+    loaderIds: string[];
+    fallback?: ReactNode;
+    outletKey: string;
+    outletContent: ReactNode;
+    segment: ResolvedSegment;
+    parallel?: ResolvedSegment[];
+    children: ReactNode;
+}
+export declare function LoaderBoundary({ loaderDataPromise, loaderIds, fallback, outletKey, outletContent, segment, parallel, children, }: LoaderBoundaryProps): ReactNode;

package/dist/types/route-definition/dsl-helpers.d.ts

@@ -0,0 +1,130 @@
+import type { TransitionConfig } from "../types.js";
+import { getContext, type EntryData, type EntryPropDatas, type EntryPropSegments, type InterceptConfig } from "../server/context";
+import type { AllUseItems, InterceptItem, TransitionItem, UseItems } from "../route-types.js";
+import type { RouteHelpers } from "./helpers-types.js";
+/**
+ * Fresh empty collections shared by every from-scratch segment entry. Returns
+ * new arrays/objects per call so no two entries share mutable references.
+ * mountPath is intentionally NOT included here — each call site adds it from
+ * getUrlPrefix() where applicable: the route() and transition() helpers add
+ * none, while path() (which also builds a `type: "route"` entry) and the
+ * structural helpers (layout/cache/middleware/parallel) do.
+ */
+declare const emptySegmentBase: () => EntryPropDatas & EntryPropSegments & {
+    loading: undefined;
+};
+/**
+ * Run a children/use callback as a nested scope, flatten the result, and assert
+ * every item is a valid use item. `kind` preserves the existing error wording
+ * ("use()" vs "children" callback).
+ */
+declare function runAndValidateUseItems(store: ReturnType<typeof getContext>, namespace: string, entry: EntryData, cb: () => any, label: string, kind: "use" | "children"): AllUseItems[];
+declare const revalidate: RouteHelpers<any, any>["revalidate"];
+/**
+ * Error boundary helper - attaches an error fallback to the current entry
+ *
+ * When an error occurs during rendering of this segment or its children,
+ * the fallback will be rendered instead. The fallback can be:
+ * - A static ReactNode (e.g., <ErrorPage />)
+ * - A handler function that receives error info and reset function
+ *
+ * Error boundaries catch errors from:
+ * - Middleware execution
+ * - Loader execution
+ * - Handler/component rendering
+ *
+ * @example
+ * ```typescript
+ * layout(<ShopLayout />, () => [
+ *   errorBoundary(<ShopErrorFallback />),
+ *   route("products.detail", ProductDetail),
+ * ])
+ *
+ * // Or with handler for dynamic error UI:
+ * route("products.detail", ProductDetail, () => [
+ *   errorBoundary(({ error, reset }) => (
+ *     <div>
+ *       <h2>Product failed to load</h2>
+ *       <p>{error.message}</p>
+ *       <button onClick={reset}>Retry</button>
+ *     </div>
+ *   )),
+ * ])
+ * ```
+ */
+declare const errorBoundary: RouteHelpers<any, any>["errorBoundary"];
+/**
+ * NotFound boundary helper - attaches a not-found fallback to the current entry
+ *
+ * When a DataNotFoundError is thrown (via notFound()) during rendering of this
+ * segment or its children, the fallback will be rendered instead. The fallback can be:
+ * - A static ReactNode (e.g., <ProductNotFound />)
+ * - A handler function that receives not found info
+ *
+ * NotFound boundaries catch DataNotFoundError from:
+ * - Loader execution
+ * - Handler/component rendering
+ *
+ * @example
+ * ```typescript
+ * layout(<ShopLayout />, () => [
+ *   notFoundBoundary(<ProductNotFound />),
+ *   route("products.detail", ProductDetail),
+ * ])
+ *
+ * // Or with handler for dynamic not found UI:
+ * route("products.detail", ProductDetail, () => [
+ *   notFoundBoundary(({ notFound }) => (
+ *     <div>
+ *       <h2>Product not found</h2>
+ *       <p>{notFound.message}</p>
+ *       <a href="/products">Browse all products</a>
+ *     </div>
+ *   )),
+ * ])
+ * ```
+ */
+declare const notFoundBoundary: RouteHelpers<any, any>["notFoundBoundary"];
+/**
+ * Cache helper - defines caching configuration for segments
+ *
+ * Creates a cache boundary that applies to all children unless overridden.
+ * When used without children, attaches cache config to the parent entry
+ * (e.g., for loader-specific caching).
+ *
+ * Supports these call signatures:
+ * - cache() - no args, uses app-level defaults (for loader caching)
+ * - cache(() => [...]) - wraps children with app-level defaults
+ * - cache({ ttl: 60 }, () => [...]) - with explicit options
+ *
+ * Named cache profiles are applied via the `"use cache: <profile>"` directive,
+ * not a `cache("profileName")` form in the route tree.
+ */
+declare const cache: RouteHelpers<any, any>["cache"];
+declare const middleware: RouteHelpers<any, any>["middleware"];
+declare const parallel: RouteHelpers<any, any>["parallel"];
+/**
+ * Intercept helper - defines an intercepting route for soft navigation
+ */
+declare const intercept: (slotName: `@${string}`, routeName: string, handler: any, configOrUse?: InterceptConfig | (() => any[]), use?: () => any[]) => InterceptItem;
+/**
+ * Loader helper - attaches a loader to the current entry
+ */
+declare const loader: RouteHelpers<any, any>["loader"];
+/**
+ * Loading helper - attaches a loading component to the current entry
+ * Loading components are static (no context) and shown during navigation
+ */
+declare const loading: RouteHelpers<any, any>["loading"];
+/**
+ * Transition helper - opts the entry (or a wrapped group of routes) into
+ * transition-driven navigation by attaching a TransitionConfig. This drives the
+ * commit through startTransition (content hold on all React versions) and, on
+ * experimental React, places a `<ViewTransition>` boundary unless
+ * `viewTransition: false`. See skills/view-transitions for the matrix.
+ */
+declare const transition: (configOrChildren?: TransitionConfig | (() => UseItems<AllUseItems>), maybeChildren?: () => UseItems<AllUseItems>) => TransitionItem;
+declare const route: RouteHelpers<any, any>["route"];
+declare const layout: RouteHelpers<any, any>["layout"];
+declare const isValidUseItem: (item: any) => item is AllUseItems | undefined | null;
+export { layout, cache, middleware, revalidate, parallel, intercept, errorBoundary, notFoundBoundary, route, loader, loading, transition, isValidUseItem, emptySegmentBase, runAndValidateUseItems, };

package/dist/types/route-definition/helper-factories.d.ts

@@ -0,0 +1,22 @@
+import type { RouteDefinition, DefaultEnv } from "../types.js";
+import type { AllUseItems } from "../route-types.js";
+import type { RouteHelpers } from "./helpers-types.js";
+/**
+ * Branded type for route handlers that carries the route type info.
+ * This enables type-safe verification that imported handlers match route definitions.
+ */
+export interface RouteHandlers<T extends RouteDefinition> {
+    (): Array<AllUseItems>;
+    /** Brand to carry route type info for type checking */
+    readonly __routes: T;
+}
+/**
+ * Type-safe handler definition helper
+ *
+ */
+export declare function map<const T extends RouteDefinition, TEnv = DefaultEnv>(builder: (helpers: RouteHelpers<T, TEnv>) => Array<AllUseItems>): RouteHandlers<T>;
+/**
+ * Create RouteHelpers for inline route definitions
+ * Used internally by router.map() for inline handler syntax
+ */
+export declare function createRouteHelpers<T extends RouteDefinition, TEnv>(): RouteHelpers<T, TEnv>;