@rangojs/router 0.4.0 → 0.4.1

package/dist/types.backup/reverse.d.ts

@@ -1,206 +0,0 @@
-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.backup/root-error-boundary.d.ts

@@ -1,32 +0,0 @@
-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.backup/route-content-wrapper.d.ts

@@ -1,40 +0,0 @@
-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.backup/route-definition/dsl-helpers.d.ts

@@ -1,130 +0,0 @@
-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.backup/route-definition/helper-factories.d.ts

@@ -1,22 +0,0 @@
-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>;