@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.13221847

package/src/href-client.ts

@@ -45,30 +45,34 @@ type ParseConstraintPath<T extends string> =
 export type PatternToPath<T extends string> =
   // Optional + constrained param in middle: /:param(a|b)?/rest
   T extends `${infer Before}:${infer _Name}(${infer Constraint})?/${infer After}`
-    ? PatternToPath<`${Before}${After}`> | `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
-  // Optional + constrained param at end: /path/:param(a|b)?
-  : T extends `${infer Before}:${infer _Name}(${infer Constraint})?`
-    ? Before | `${Before}${ParseConstraintPath<Constraint>}`
-  // Constrained param in middle: /:param(a|b)/rest
-  : T extends `${infer Before}:${infer _Name}(${infer Constraint})/${infer After}`
-    ? `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
-  // Constrained param at end: /path/:param(a|b)
-  : T extends `${infer Before}:${infer _Name}(${infer Constraint})`
-    ? `${Before}${ParseConstraintPath<Constraint>}`
-  // Optional param in middle: /:param?/rest
-  : T extends `${infer Before}:${infer _Param}?/${infer After}`
-    ? PatternToPath<`${Before}${After}`> | `${Before}${string}/${PatternToPath<After>}`
-  // Optional param at end: /path/:param?
-  : T extends `${infer Before}:${infer _Param}?`
-    ? Before | `${Before}${string}`
-  // Required param in middle: /:param/rest
-  : T extends `${infer Before}:${infer _Param}/${infer After}`
-    ? `${Before}${string}/${PatternToPath<After>}`
-  // Required param at end: /path/:param
-  : T extends `${infer Before}:${infer _Param}`
-    ? `${Before}${string}`
-  // Static path
-  : T;
+    ?
+        | PatternToPath<`${Before}${After}`>
+        | `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+    : // Optional + constrained param at end: /path/:param(a|b)?
+      T extends `${infer Before}:${infer _Name}(${infer Constraint})?`
+      ? Before | `${Before}${ParseConstraintPath<Constraint>}`
+      : // Constrained param in middle: /:param(a|b)/rest
+        T extends `${infer Before}:${infer _Name}(${infer Constraint})/${infer After}`
+        ? `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+        : // Constrained param at end: /path/:param(a|b)
+          T extends `${infer Before}:${infer _Name}(${infer Constraint})`
+          ? `${Before}${ParseConstraintPath<Constraint>}`
+          : // Optional param in middle: /:param?/rest
+            T extends `${infer Before}:${infer _Param}?/${infer After}`
+            ?
+                | PatternToPath<`${Before}${After}`>
+                | `${Before}${string}/${PatternToPath<After>}`
+            : // Optional param at end: /path/:param?
+              T extends `${infer Before}:${infer _Param}?`
+              ? Before | `${Before}${string}`
+              : // Required param in middle: /:param/rest
+                T extends `${infer Before}:${infer _Param}/${infer After}`
+                ? `${Before}${string}/${PatternToPath<After>}`
+                : // Required param at end: /path/:param
+                  T extends `${infer Before}:${infer _Param}`
+                  ? `${Before}${string}`
+                  : // Static path
+                    T;
 
 /**
  * Allow optional query string (?...) and/or hash fragment (#...) suffix
@@ -85,19 +89,17 @@ type WithSuffix<T extends string> =
 /**
  * Helper type to get pattern from routes, handling string values and { path, response } objects
  */
-type RoutePattern<TRoutes, K extends keyof TRoutes> =
-  TRoutes[K] extends string ? TRoutes[K]
-  : TRoutes[K] extends { readonly path: infer P extends string } ? P
-  : string;
+type RoutePattern<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends string
+  ? TRoutes[K]
+  : TRoutes[K] extends { readonly path: infer P extends string }
+    ? P
+    : string;
 
 /**
  * Reverse lookup: find route name where the pattern matches TPattern
  */
-type NameForPattern<
-  TPattern extends string,
-  TRoutes = GetRegisteredRoutes
-> = {
-  [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern ? K : never
+type NameForPattern<TPattern extends string, TRoutes = GetRegisteredRoutes> = {
+  [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern ? K : never;
 }[keyof TRoutes];
 
 /**
@@ -112,19 +114,28 @@ type NameForPattern<
  * For dynamic routes, use the pattern:
  *   PathResponse<"/api/products/:id"> → Product
  */
-export type PathResponse<TPattern extends string, TRoutes = GetRegisteredRoutes> =
-  ResponseEnvelope<{
+export type PathResponse<
+  TPattern extends string,
+  TRoutes = GetRegisteredRoutes,
+> = ResponseEnvelope<
+  {
     [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern
-      ? TRoutes[K] extends { readonly response: infer R } ? Exclude<R, Response> : never
-      : never
-  }[keyof TRoutes]>;
+      ? TRoutes[K] extends { readonly response: infer R }
+        ? Exclude<R, Response>
+        : never
+      : never;
+  }[keyof TRoutes]
+>;
 
 /**
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
  * Allows navigation to include() prefixes without requiring trailing slash
  */
-type OptionalTrailingSlash<T extends string> =
-  T extends `${infer Base}/` ? (Base extends "" ? T : Base | T) : T;
+type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/`
+  ? Base extends ""
+    ? T
+    : Base | T
+  : T;
 
 /**
  * Union of all valid paths from registered routes
@@ -135,9 +146,13 @@ type OptionalTrailingSlash<T extends string> =
 export type ValidPaths<TRoutes = GetRegisteredRoutes> =
   keyof TRoutes extends never
     ? `/${string}` // Fallback when no routes are registered
-    : WithSuffix<{
-        [K in keyof TRoutes]: OptionalTrailingSlash<PatternToPath<RoutePattern<TRoutes, K>>>
-      }[keyof TRoutes]>;
+    : WithSuffix<
+        {
+          [K in keyof TRoutes]: OptionalTrailingSlash<
+            PatternToPath<RoutePattern<TRoutes, K>>
+          >;
+        }[keyof TRoutes]
+      >;
 
 /**
  * Type-safe href function for client-side use
@@ -167,7 +182,9 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
  */
 export function href<T extends ValidPaths>(path: T, mount?: string): string {
   if (mount && mount !== "/") {
-    return mount + path;
+    // Strip trailing slash from mount to avoid double-slash when joining
+    const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
+    return normalizedMount + path;
   }
   return path;
 }
@@ -181,7 +198,10 @@ export interface ResponseHrefProps {
   "data-external": "";
 }
 
-type ResponseHrefFn = <T extends ValidPaths>(path: T, mount?: string) => ResponseHrefProps;
+type ResponseHrefFn = <T extends ValidPaths>(
+  path: T,
+  mount?: string,
+) => ResponseHrefProps;
 
 function createResponseHrefTag(): ResponseHrefFn {
   return (path, mount) => ({

package/src/index.rsc.ts

@@ -11,8 +11,6 @@
 
 // Re-export all universal exports from index.ts
 export {
-  // Universal rendering utilities
-  renderSegments,
   // Error classes
   RouteNotFoundError,
   DataNotFoundError,
@@ -21,17 +19,15 @@ export {
   HandlerError,
   BuildError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
+  Skip,
+  isSkip,
 } from "./index.js";
 
 // Re-export all types from types.ts (user-facing types only)
 export type {
   // Configuration types
   DocumentProps,
-  RouterEnv,
   DefaultEnv,
   RouteDefinition,
   RouteConfig,
@@ -39,7 +35,6 @@ export type {
   TrailingSlashMode,
   // Handler types
   Handler,
-  ScopedRouteMap,
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -55,9 +50,6 @@ export type {
   LoaderContext,
   FetchableLoaderOptions,
   LoadOptions,
-  LoaderActionContext,
-  LoaderAction,
-  LoaderMiddlewareFn,
   // Error boundary types
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -67,37 +59,75 @@ export type {
   NotFoundInfo,
   NotFoundBoundaryFallbackProps,
   NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
 } from "./types.js";
 
 // Router options type (server-only, so import directly)
-export type { RSCRouterOptions } from "./router.js";
+export type {
+  RSCRouterOptions,
+  SSRStreamMode,
+  SSROptions,
+  ResolveStreamingContext,
+} from "./router.js";
 
 // Server-side createLoader and redirect
-export { createLoader, redirect } from "./route-definition.js";
+export {
+  createLoader,
+  redirect,
+  type RouteHelpers,
+  type RouteHandlers,
+  // Globally importable route helpers for composition
+  layout,
+  cache,
+  middleware,
+  revalidate,
+  loader,
+  loading,
+  parallel,
+  intercept,
+  when,
+  errorBoundary,
+  notFoundBoundary,
+  transition,
+} from "./route-definition.js";
+
+// Composition types for reusable callback factories
+export type {
+  RouteUseItem,
+  LayoutUseItem,
+  AllUseItems,
+  UseItems,
+} from "./route-types.js";
 
 // Handle API
 export { createHandle, isHandle, type Handle } from "./handle.js";
 
+// Context variable API (typed ctx.set/ctx.get tokens)
+export { createVar, type ContextVar } from "./context-var.js";
+
+// CSP nonce token (use with ctx.get(nonce) in middleware/handlers)
+export { nonce } from "./rsc/nonce.js";
+
 // Pre-render handler API
 export {
   Prerender,
-  isPrerenderHandler,
   type PrerenderHandlerDefinition,
+  type PrerenderPassthroughContext,
   type PrerenderOptions,
   type BuildContext,
+  type StaticBuildContext,
+  type GetParamsContext,
 } from "./prerender.js";
 
 // Static handler API
-export {
-  Static,
-  isStaticHandler,
-  type StaticHandlerDefinition,
-} from "./static-handler.js";
+export { Static, type StaticHandlerDefinition } from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
   urls,
-  RESPONSE_TYPE,
   type PathHelpers,
   type PathOptions,
   type UrlPatterns,
@@ -121,6 +151,7 @@ export {
   createRouter,
   type RSCRouter,
   type RootLayoutProps,
+  type RouterRequestInput,
 } from "./router.js";
 
 // RSC handler types (server-side)
@@ -128,42 +159,75 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
 
 // Built-in handles (server-side)
 export { Meta } from "./handles/meta.js";
-
-// Request context (for accessing request data in server actions/components)
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
+
+// Request context (for accessing request data in server actions/components).
+// Re-exported with a narrowed return type so that public consumers only see
+// public members. Internal code imports from "./server/request-context.js"
+// directly and gets the full type.
+import { getRequestContext as _getRequestContextInternal } from "./server/request-context.js";
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+import type { PublicRequestContext } from "./server/request-context.js";
+import type { DefaultEnv } from "./types/global-namespace.js";
+
+export const getRequestContext: <
+  TEnv = DefaultEnv,
+>() => PublicRequestContext<TEnv> = _getRequestContextInternal;
+
+// Request-scoped shorthands
 export {
-  getRequestContext,
-  requireRequestContext,
-  type RequestContext,
-} from "./server/request-context.js";
+  cookies,
+  headers,
+  type CookieStore,
+  type Cookie,
+  type ReadonlyHeaders,
+} from "./server/cookie-store.js";
 
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
 // Middleware context types
-export type {
-  MiddlewareContext,
-  CookieOptions,
-} from "./router/middleware.js";
+export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
 
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
-export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes, PrefixedRoutes, PrefixRoutePatterns, ParamsFor, SanitizePrefix, MergeRoutes } from "./reverse.js";
+export type {
+  ScopedReverseFunction,
+  ReverseFunction,
+  ExtractLocalRoutes,
+  ParamsFor,
+} from "./reverse.js";
 export { scopedReverse, createReverse } from "./reverse.js";
 
 // Search params schema types
-export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams } from "./search-params.js";
-
-// Performance tracking (server-only)
-export { track } from "./server/context.js";
-
-// Debug utilities for route matching (development only)
-export {
-  enableMatchDebug,
-  getMatchDebugStats,
-} from "./router/pattern-matching.js";
+export type {
+  SearchSchema,
+  SearchSchemaValue,
+  ResolveSearchSchema,
+  RouteSearchParams,
+  RouteParams,
+} from "./search-params.js";
 
 // Location state (universal)
 export {
   createLocationState,
   type LocationStateDefinition,
   type LocationStateEntry,
+  type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
+
+// Path-based response type lookup from RegisteredRoutes
+export type { PathResponse } from "./href-client.js";
+
+// Telemetry sink
+export { createConsoleSink } from "./router/telemetry.js";
+export { createOTelSink } from "./router/telemetry-otel.js";
+export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+
+// Timeout types and error class
+export { RouterTimeoutError } from "./router/timeout.js";
+export type {
+  RouterTimeouts,
+  TimeoutPhase,
+  TimeoutContext,
+} from "./router/timeout.js";