@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/href-client.ts

@@ -15,6 +15,8 @@
  */
 
 import type { GetRegisteredRoutes } from "./types.js";
+import type { JsonSerialize } from "./serialize.js";
+import type { ResponseEnvelope } from "./urls.js";
 
 /**
  * Parse constraint values into a union type for paths
@@ -44,30 +46,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
@@ -81,48 +87,256 @@ type WithSuffix<T extends string> =
   | `${T}#${string}`
   | `${T}?${string}#${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;
+
+/**
+ * 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;
+}[keyof TRoutes];
+
+/**
+ * Strip a query (`?…`) and/or hash (`#…`) suffix before matching, so a concrete
+ * URL like `/api/health?ts=1` still resolves to its route's response. Removes
+ * from the earliest of `?`/`#`: a `#` before the first `?` (the query is part of
+ * a fragment, e.g. `/health#top?x=1`) is handled, as is a `/:` that only appears
+ * inside the query (e.g. `/health?next=/:id`).
+ */
+type StripPathSuffix<T extends string> = T extends `${infer Base}?${string}`
+  ? Base extends `${infer Frag}#${string}`
+    ? Frag
+    : Base
+  : T extends `${infer Base}#${string}`
+    ? Base
+    : T;
+
+/** Extract a route entry's response payload (or `never` for RSC routes). */
+type ResponsePayloadOf<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends {
+  readonly response: infer R;
+}
+  ? Exclude<R, Response>
+  : never;
+
+/**
+ * Look up the response payload for a route, keyed by either a route pattern
+ * (`/api/products/:id`) or a concrete path (`/api/products/123`). The same type
+ * serves a pattern lookup and a typed `fetch` wrapper that forwards a concrete
+ * `Rango.Path`:
+ *
+ *   PathResponse<"/api/products/:id"> → Product   // by pattern
+ *   PathResponse<"/api/products/123"> → Product   // by concrete path
+ *
+ * The query/hash suffix is stripped first; the stripped key is then treated as a
+ * pattern when it contains a `/:param` segment and matched exactly (precise even
+ * for nested dynamic routes), otherwise as a concrete path matched against each
+ * route's `PatternToPath` template. Because those holes are `${string}`
+ * (slash-greedy), a concrete path under a *nested* dynamic route can match several
+ * patterns and union their responses — pattern lookups do not have this
+ * looseness. RSC routes (no response) and unmatched keys resolve to `never`.
+ */
+type ResponsePayloadFor<
+  TPath extends string,
+  TRoutes = GetRegisteredRoutes,
+> = ResponsePayloadForKey<StripPathSuffix<TPath>, TRoutes>;
+
+type ResponsePayloadForKey<
+  TKey extends string,
+  TRoutes,
+> = TKey extends `${string}/:${string}`
+  ? {
+      [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TKey
+        ? ResponsePayloadOf<TRoutes, K>
+        : never;
+    }[keyof TRoutes]
+  : {
+      [K in keyof TRoutes]: TKey extends PatternToPath<RoutePattern<TRoutes, K>>
+        ? ResponsePayloadOf<TRoutes, K>
+        : never;
+    }[keyof TRoutes];
+
+/**
+ * Public response type for a route, keyed by pattern or concrete path. The
+ * payload is wrapped in `JsonSerialize` so it describes the JSON **wire** value a
+ * consumer receives from `fetch().then(r => r.json())`, not the handler's raw
+ * return type — e.g. a handler returning `{ createdAt: Date }` resolves here to
+ * `ResponseEnvelope<{ createdAt: string }>`.
+ */
+export type PathResponse<
+  TPath extends string,
+  TRoutes = GetRegisteredRoutes,
+> = ResponseEnvelope<JsonSerialize<ResponsePayloadFor<TPath, 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;
+
 /**
  * Union of all valid paths from registered routes
  *
- * Generated from RSCRouter.RegisteredRoutes via module augmentation.
+ * Generated from Rango.RegisteredRoutes via module augmentation.
  * Allows optional query strings and hash fragments.
  */
-export type ValidPaths<TRoutes extends Record<string, string> = GetRegisteredRoutes> =
-  WithSuffix<PatternToPath<TRoutes[keyof TRoutes]>>;
+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]
+      >;
+
+// Module-scoped alias so the ambient `Rango.PathResponse` below can reference
+// the module-level `PathResponse` without the global namespace shadowing the
+// name when both are called `PathResponse`.
+type GlobalPathResponse<
+  TPattern extends string,
+  TRoutes = GetRegisteredRoutes,
+> = PathResponse<TPattern, TRoutes>;
 
 /**
- * Type-safe href function for client-side use
- *
- * This is an identity function - it returns the path unchanged.
- * The value is in TypeScript validation: invalid paths cause compile errors.
+ * Ambient path types on the `Rango` namespace.
  *
- * Works with:
- * - Static paths: href("/about")
- * - Dynamic segments: href("/blog/my-post")
- * - Multiple segments: href("/shop/product/widget/reviews/123")
+ * These live on the same global namespace consumers already augment for
+ * `Rango.Env` / `Rango.Vars`, so they are reachable with no import wherever the
+ * router's types are in scope. They are the public, recommended surface for
+ * typing anything that wraps `href()`. `ValidPaths` / `PathResponse` stay as the
+ * internal building blocks behind them.
+ */
+declare global {
+  namespace Rango {
+    /**
+     * Union of every valid route path accepted by `href()`.
+     *
+     * Type a wrapper's path parameter as `Rango.Path` so it shares `href()`'s
+     * compile-time validation against the registered routes:
+     *
+     * ```ts
+     * import { href } from "@rangojs/router/client";
+     *
+     * export const appHref = (path: Rango.Path) => href(path);
+     * ```
+     *
+     * Resolves from `Rango.RegisteredRoutes` when augmented, otherwise the
+     * auto-generated `Rango.GeneratedRouteMap`, otherwise a permissive
+     * `/${string}` fallback.
+     */
+    type Path<TRoutes = GetRegisteredRoutes> = ValidPaths<TRoutes>;
+
+    /**
+     * Response payload for a route, looked up from the global route map by
+     * either a route pattern (`/api/products/:id`) or a concrete path
+     * (`/api/products/123`). Because it accepts a concrete `Rango.Path`, it
+     * doubles as the return type of a typed `fetch` wrapper:
+     *
+     * ```ts
+     * type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+     * type Same = Rango.PathResponse<"/api/products/42">;     // by concrete path
+     *
+     * const get = async <T extends Rango.Path>(
+     *   path: T,
+     * ): Promise<Rango.PathResponse<T>> =>
+     *   fetch(href(path)).then((r) => r.json());
+     * ```
+     *
+     * The payload is the JSON **wire** shape (via `Rango.JsonSerialize`), not the
+     * handler's raw return — a handler returning `{ createdAt: Date }` resolves
+     * here to `ResponseEnvelope<{ createdAt: string }>`, matching what
+     * `fetch().then(r => r.json())` actually yields.
+     *
+     * Only resolves once `Rango.RegisteredRoutes` carries response metadata (the
+     * generated map has paths and search but no payloads). Pass an explicit route
+     * map as the second argument to look up against a non-global map (rarely
+     * needed in app code).
+     */
+    type PathResponse<
+      TPath extends string,
+      TRoutes = GetRegisteredRoutes,
+    > = GlobalPathResponse<TPath, TRoutes>;
+  }
+}
+
+/**
+ * Type-safe href function for client-side use
  *
- * Does NOT validate:
- * - Query strings (passed through as-is)
- * - Hash fragments (passed through as-is)
+ * Without mount: identity function, validates absolute paths at compile time.
+ * With mount: prepends mount path, for use with useMount() inside include() scopes.
  *
  * @param path - A valid path matching one of the registered route patterns
- * @returns The path unchanged
+ * @param mount - Optional mount prefix from useMount() for include-scoped paths
+ * @returns The resolved path
  *
  * @example
  * ```typescript
- * // Valid paths (compile)
- * href("/blog/hello");                    // matches /blog/:slug
- * href("/shop/product/widget");           // matches /shop/product/:slug
- * href("/shop/product/widget/reviews");   // matches /shop/product/:slug/reviews
+ * // Absolute paths (type-safe)
+ * href("/blog/hello");           // "/blog/hello"
+ * href("/shop/product/widget");  // "/shop/product/widget"
  *
- * // Query strings and hashes pass through (not validated)
+ * // With mount (inside an include)
+ * const mount = useMount();      // "/articles"
+ * href("/", mount);              // "/articles/"
+ * href("/my-post", mount);       // "/articles/my-post"
+ *
+ * // Query strings and hashes pass through
  * href("/blog/hello?page=1");
  * href("/about#contact");
- *
- * // Invalid paths (TypeScript error)
- * href("/nonexistent");  // Error: not assignable to ValidPaths
  * ```
  */
-export function href<T extends ValidPaths>(path: T): T {
-  return path;
+export function href<T extends ValidPaths>(path: T, mount?: string): string {
+  if (mount && mount !== "/") {
+    // Strip trailing slash from mount to avoid double-slash when joining
+    const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
+    return normalizedMount + path;
+  }
+  // ValidPaths is built from template literals so T does extend string at
+  // runtime, but the inference can fail past a certain route-union complexity
+  // and TypeScript reports T as not assignable to string.
+  return path as string;
+}
+
+/**
+ * Props shape returned by href.json() etc. for spreading on <Link>.
+ * Sets data-external to trigger hard navigation (skips RSC fetch).
+ */
+export interface ResponseHrefProps {
+  to: string;
+  "data-external": "";
+}
+
+type ResponseHrefFn = <T extends ValidPaths>(
+  path: T,
+  mount?: string,
+) => ResponseHrefProps;
+
+function createResponseHrefTag(): ResponseHrefFn {
+  return (path, mount) => ({
+    to: href(path, mount),
+    "data-external": "" as const,
+  });
+}
+
+export namespace href {
+  export const json: ResponseHrefFn = createResponseHrefTag();
+  export const text: ResponseHrefFn = createResponseHrefTag();
+  export const html: ResponseHrefFn = createResponseHrefTag();
+  export const xml: ResponseHrefFn = createResponseHrefTag();
+  export const md: ResponseHrefFn = createResponseHrefTag();
+  export const image: ResponseHrefFn = createResponseHrefTag();
+  export const stream: ResponseHrefFn = createResponseHrefTag();
+  export const any: ResponseHrefFn = createResponseHrefTag();
 }

package/src/index.rsc.ts

@@ -1,9 +1,9 @@
 /**
- * rsc-router (react-server environment)
+ * @rangojs/router (react-server environment)
  *
- * This file is used when importing "rsc-router" from RSC (server components).
+ * This file is used when importing "@rangojs/router" from RSC (server components).
  * It re-exports everything from the universal index.ts plus adds server-side
- * createLoader that includes the actual loader function.
+ * implementations that replace the client-side error stubs.
  *
  * The bundler uses the "react-server" export condition to select this file
  * in RSC context, while the regular index.ts is used in client components.
@@ -11,8 +11,6 @@
 
 // Re-export all universal exports from index.ts
 export {
-  // Universal rendering utilities
-  renderSegments,
   // Error classes
   RouteNotFoundError,
   DataNotFoundError,
@@ -20,53 +18,116 @@ export {
   MiddlewareError,
   HandlerError,
   BuildError,
+  DslContextError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
-  // Route pattern definition
-  route,
+  RouterError,
+  Skip,
+  isSkip,
 } from "./index.js";
 
-// Re-export all types from index.ts
+// Re-export all types from types.ts (user-facing types only)
 export type {
-  RouterEnv,
+  // Configuration types
+  DocumentProps,
   DefaultEnv,
   RouteDefinition,
-  ResolvedRouteMap,
+  RouteConfig,
+  RouteDefinitionOptions,
+  TrailingSlashMode,
+  // Handler types
   Handler,
   HandlerContext,
-  HandlersForRouteMap,
-  ResolvedSegment,
-  SegmentMetadata,
-  MatchResult,
   ExtractParams,
   GenericParams,
+  // Middleware types
+  Middleware,
+  // Revalidation types
   RevalidateParams,
-  ShouldRevalidateFn,
-  MiddlewareFn,
+  Revalidate,
+  ActionRef,
   RouteKeys,
-  RouteHandler,
-  RouteRevalidateFn,
-  RouteMiddlewareFn,
+  // Loader types
   LoaderDefinition,
   LoaderFn,
   LoaderContext,
+  FetchableLoaderOptions,
+  LoadOptions,
+  // Error boundary types
   ErrorInfo,
   ErrorBoundaryFallbackProps,
   ErrorBoundaryHandler,
   ClientErrorBoundaryFallbackProps,
+  // NotFound boundary types
   NotFoundInfo,
   NotFoundBoundaryFallbackProps,
   NotFoundBoundaryHandler,
-  RSCRouterOptions,
-  PerformanceMetric,
-  MetricsStore,
-} from "./index.js";
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
+} from "./types.js";
+
+// Router options type (server-only, so import directly)
+export type {
+  RangoOptions,
+  SSRStreamMode,
+  SSROptions,
+  ResolveStreamingContext,
+} from "./router.js";
+
+// Server-side createLoader and redirect
+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,
+  HandlerUseItem,
+} 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";
 
-// Server-side createLoader - includes the actual loader function
-// This is the key addition for RSC context
-export { createLoader } from "./route-definition.js";
+// CSP nonce token (use with ctx.get(nonce) in middleware/handlers)
+export { nonce } from "./rsc/nonce.js";
+
+// Pre-render handler API
+export {
+  Prerender,
+  Passthrough,
+  type PrerenderHandlerDefinition,
+  type PassthroughHandlerDefinition,
+  type PrerenderOptions,
+  type BuildContext,
+  type StaticBuildContext,
+  type GetParamsContext,
+} from "./prerender.js";
+
+// Static handler API
+export { Static, type StaticHandlerDefinition } from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
@@ -76,4 +137,104 @@ export {
   type UrlPatterns,
   type IncludeOptions,
   type IncludeItem,
+  type RouteResponse,
+  type ResponseError,
+  type ResponseEnvelope,
+  type ResponseHandler,
+  type ResponseHandlerContext,
+  type JsonResponseHandler,
+  type TextResponseHandler,
+  type JsonValue,
+  type ResponsePathFn,
+  type JsonResponsePathFn,
+  type TextResponsePathFn,
 } from "./urls.js";
+
+// Core router (server-side)
+export {
+  createRouter,
+  type Rango,
+  type RootLayoutProps,
+  type RouterRequestInput,
+} from "./router.js";
+
+// RSC handler types (server-side)
+export type { HandlerCacheConfig } from "./rsc/types.js";
+
+// Built-in handles (server-side)
+export { Meta } from "./handles/meta.js";
+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";
+
+// Shared base for every user-facing request context (mirrors index.ts).
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
+export const getRequestContext: <
+  TEnv = DefaultEnv,
+>() => PublicRequestContext<TEnv> = _getRequestContextInternal;
+
+// Request-scoped shorthands
+export {
+  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";
+
+// Reverse type utilities for type-safe URL generation (Django-style URL reversal)
+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";
+
+// Location state (universal)
+export {
+  createLocationState,
+  type LocationStateDefinition,
+  type LocationStateEntry,
+  type LocationStateOptions,
+} from "./browser/react/location-state-shared.js";
+
+// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
+// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
+
+// 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";