@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/href-client.ts

@@ -15,7 +15,7 @@
  */
 
 import type { GetRegisteredRoutes } from "./types.js";
-import type { ResponseEnvelope } from "./urls.js";
+import type { JsonSerialize } from "./serialize.js";
 
 /**
  * Parse constraint values into a union type for paths
@@ -103,29 +103,75 @@ type NameForPattern<TPattern extends string, TRoutes = GetRegisteredRoutes> = {
 }[keyof TRoutes];
 
 /**
- * Look up the response data type for a route pattern from RegisteredRoutes.
- *
- * Works by reverse-looking up the route name for the given pattern,
- * then extracting the response type from the route entry.
+ * 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`:
  *
- * For static routes (no params), pattern === path:
- *   PathResponse<"/api/health"> → { status: string; timestamp: number }
+ *   PathResponse<"/api/products/:id"> → Product   // by pattern
+ *   PathResponse<"/api/products/123"> → Product   // by concrete path
  *
- * For dynamic routes, use the pattern:
- *   PathResponse<"/api/products/:id"> → Product
+ * 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. JSON
+ * response routes send the handler's return value verbatim (bare), so the
+ * payload is wrapped only in `JsonSerialize` to describe the JSON **wire** value
+ * a consumer receives from `fetch().then(r => r.json())` — e.g. a handler
+ * returning `{ createdAt: Date }` resolves here to `{ createdAt: string }`.
  */
 export type PathResponse<
-  TPattern extends string,
+  TPath 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]
->;
+> = JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>;
 
 /**
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
@@ -140,7 +186,7 @@ type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/`
 /**
  * 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 = GetRegisteredRoutes> =
@@ -154,6 +200,76 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
         }[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>;
+
+/**
+ * Ambient path types on the `Rango` namespace.
+ *
+ * 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 `{ createdAt: string }` (bare, no envelope), 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
  *
@@ -182,11 +298,10 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
  */
 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;
   }
-  return path;
+  return path as string;
 }
 
 /**

package/src/index.rsc.ts

@@ -18,6 +18,7 @@ export {
   MiddlewareError,
   HandlerError,
   BuildError,
+  DslContextError,
   InvalidHandlerError,
   RouterError,
   Skip,
@@ -43,6 +44,7 @@ export type {
   // Revalidation types
   RevalidateParams,
   Revalidate,
+  ActionRef,
   RouteKeys,
   // Loader types
   LoaderDefinition,
@@ -63,16 +65,29 @@ export type {
   ErrorPhase,
   OnErrorContext,
   OnErrorCallback,
+  // View transition types (also exported from the default entry; route
+  // definitions resolve to this react-server entry, so they must be here too)
+  TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
+  ViewTransitionClass,
 } from "./types.js";
 
 // Router options type (server-only, so import directly)
 export type {
-  RSCRouterOptions,
+  RangoOptions,
   SSRStreamMode,
   SSROptions,
   ResolveStreamingContext,
 } from "./router.js";
 
+// Origin-check callback types (referenced by the RangoOptions.originCheck JSDoc)
+export type {
+  OriginCheckConfig,
+  OriginCheckContext,
+  OriginCheckPhase,
+} from "./rsc/origin-guard.js";
+
 // Server-side createLoader and redirect
 export {
   createLoader,
@@ -88,7 +103,6 @@ export {
   loading,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
   transition,
@@ -105,6 +119,13 @@ export type {
 
 // Handle API
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type DeferredHandleEntry,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
 
 // Context variable API (typed ctx.set/ctx.get tokens)
 export { createVar, type ContextVar } from "./context-var.js";
@@ -122,10 +143,15 @@ export {
   type BuildContext,
   type StaticBuildContext,
   type GetParamsContext,
+  type PrerenderPassthroughResult,
 } from "./prerender.js";
 
 // Static handler API
-export { Static, type StaticHandlerDefinition } from "./static-handler.js";
+export {
+  Static,
+  type StaticHandlerDefinition,
+  type StaticHandlerOptions,
+} from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
@@ -136,8 +162,7 @@ export {
   type IncludeOptions,
   type IncludeItem,
   type RouteResponse,
-  type ResponseError,
-  type ResponseEnvelope,
+  type ProblemDetails,
   type ResponseHandler,
   type ResponseHandlerContext,
   type JsonResponseHandler,
@@ -151,7 +176,7 @@ export {
 // Core router (server-side)
 export {
   createRouter,
-  type RSCRouter,
+  type Rango,
   type RootLayoutProps,
   type RouterRequestInput,
 } from "./router.js";
@@ -161,6 +186,11 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
 
 // Built-in handles (server-side)
 export { Meta } from "./handles/meta.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 // Request context (for accessing request data in server actions/components).
@@ -172,6 +202,9 @@ export type { PublicRequestContext as RequestContext } from "./server/request-co
 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;
@@ -180,16 +213,31 @@ export const getRequestContext: <
 export {
   cookies,
   headers,
+  invalidateClientCache,
+  keepClientCache,
   type CookieStore,
   type Cookie,
   type ReadonlyHeaders,
 } from "./server/cookie-store.js";
 
+// Cache tag APIs (server-only)
+// cacheTag: tag the current "use cache" entry at runtime.
+// updateTag: read-your-own-writes invalidation (awaitable, for Server Actions).
+// revalidateTag: background hard-purge invalidation (not awaited, for route handlers / webhooks).
+export { cacheTag } from "./cache/cache-tag.js";
+export { updateTag, revalidateTag } from "./cache/tag-invalidation.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,
+  // The function type of a middleware. Public so the documented "extract the
+  // middleware and unit-test it with runMiddleware" pattern has a nameable type.
+  MiddlewareFn,
+} from "./router/middleware.js";
 
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
 export type {
@@ -217,14 +265,50 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.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
+// Telemetry sink (event-shaped facts)
 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";
+// OTel phase-span adapter for the `tracing` slot (the canonical span layer).
+export { createOTelTracing } from "./router/telemetry-otel.js";
+export type {
+  OTelTracer,
+  OTelActiveSpanTracer,
+  OTelSpan,
+  OTelTracingOptions,
+} from "./router/telemetry-otel.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
+export type {
+  TelemetrySink,
+  TelemetryEvent,
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
+} from "./router/telemetry.js";
+
+// Span tracing config types a consumer annotates. SpanRunner/TraceSpan are the
+// internal runner contract (consumers go through createOTelTracing /
+// createCloudflareTracing, which return a ready RouterTracingConfig) and are not
+// exported.
+export type {
+  RouterTracingConfig,
+  TracePhase,
+  TracePhaseToggles,
+} from "./router/tracing.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/index.ts

@@ -18,6 +18,7 @@ export {
   MiddlewareError,
   HandlerError,
   BuildError,
+  DslContextError,
   InvalidHandlerError,
   RouterError,
   Skip,
@@ -43,6 +44,7 @@ export type {
   // Revalidation types
   RevalidateParams,
   Revalidate,
+  ActionRef,
   RouteKeys,
   // Loader types
   LoaderDefinition,
@@ -80,7 +82,12 @@ export { createLoader } from "./loader.js";
 
 // Route definition types (safe to import anywhere)
 export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
-export type { TransitionConfig, ViewTransitionClass } from "./types.js";
+export type {
+  TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
+  ViewTransitionClass,
+} from "./types.js";
 
 // Composition types for reusable callback factories
 export type {
@@ -102,8 +109,7 @@ export type {
   JsonResponsePathFn,
   TextResponsePathFn,
   RouteResponse,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
 } from "./urls.js";
 
 // Middleware context types
@@ -139,6 +145,13 @@ export function redirect(): never {
 
 // Handle API (universal - works on both server and client)
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type DeferredHandleEntry,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
 
 // Context variable API (typed ctx.set/ctx.get tokens)
 export { createVar, type ContextVar } from "./context-var.js";
@@ -216,6 +229,17 @@ export function headers(): never {
   throw serverOnlyStubError("headers");
 }
 
+/**
+ * Client implementation of `invalidateClientCache()`. Unlike the server-only
+ * stubs above this is a REAL function under the `default` condition (it marks
+ * the client's caches stale); the `react-server` condition (index.rsc.ts)
+ * selects the server implementation that writes a rotated `Set-Cookie`.
+ */
+export {
+  invalidateClientCache,
+  keepClientCache,
+} from "./browser/invalidate-client-cache.js";
+
 /**
  * Error-throwing stub for server-only `createReverse` function.
  */
@@ -236,6 +260,18 @@ export function middleware(): never {
 export function revalidate(): never {
   throw serverOnlyStubError("revalidate");
 }
+// Cache tag APIs are server-only (real implementations in index.rsc.ts). These
+// stubs keep the named-export shape identical under the default/non-react-server
+// condition so SSR/client/default bundles that encounter the import link cleanly.
+export function cacheTag(): never {
+  throw serverOnlyStubError("cacheTag");
+}
+export function updateTag(): never {
+  throw serverOnlyStubError("updateTag");
+}
+export function revalidateTag(): never {
+  throw serverOnlyStubError("revalidateTag");
+}
 export function loader(): never {
   throw serverOnlyStubError("loader");
 }
@@ -248,9 +284,6 @@ export function parallel(): never {
 export function intercept(): never {
   throw serverOnlyStubError("intercept");
 }
-export function when(): never {
-  throw serverOnlyStubError("when");
-}
 export function errorBoundary(): never {
   throw serverOnlyStubError("errorBoundary");
 }
@@ -264,6 +297,9 @@ export function transition(): never {
 // Request context type (safe for client)
 export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
 
+// Shared base for every user-facing request context.
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 // Cookie store types (safe for client)
 export type {
   CookieStore,
@@ -273,6 +309,11 @@ export type {
 
 // Built-in handles (universal — work on both server and client)
 export { Meta } from "./handles/meta.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
 export { Breadcrumbs } from "./handles/breadcrumbs.js";
 
 // Meta types
@@ -299,14 +340,53 @@ export {
   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";
+// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
+// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
+
+// Telemetry types only — the createConsoleSink/createOTelSink values are
+// server-only and live in index.rsc.ts (the `react-server` condition of the
+// bare `@rangojs/router` import). Re-exporting them as values from this
+// (default/client) entry would pull telemetry.ts and telemetry-otel.ts into
+// the client module graph; both tree-shake to zero bytes but still appear in
+// bundle analysis output and slow build-time module resolution. Consumers
+// who need the values in non-RSC contexts can import from
+// `@rangojs/router/server`.
+export type {
+  OTelTracer,
+  OTelActiveSpanTracer,
+  OTelSpan,
+  OTelTracingOptions,
+} from "./router/telemetry-otel.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
+export type {
+  TelemetrySink,
+  TelemetryEvent,
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
+} from "./router/telemetry.js";
+
+// Span tracing config types a consumer annotates. SpanRunner/TraceSpan are the
+// internal runner contract (consumers go through createOTelTracing /
+// createCloudflareTracing, which return a ready RouterTracingConfig) and are not
+// exported.
+export type {
+  RouterTracingConfig,
+  TracePhase,
+  TracePhaseToggles,
+} from "./router/tracing.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/internal-debug.ts

@@ -1,11 +1,12 @@
-// Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
-// Uses a Vite define (__RANGO_DEBUG__) for compile-time injection so it works
-// in all runtimes including Cloudflare Workers where process.env is unavailable.
-// Falls back to process.env for non-Vite contexts (tests, direct Node usage).
+// Runtime fallback for non-Vite contexts (Node, tests, raw imports). In the Vite
+// pipeline -- dev and build, every environment -- the router discovery plugin's
+// transform replaces this module with the build-time-resolved flag (see
+// vite/inject-client-debug.ts), so the CLIENT debug flag no longer depends on a
+// `__RANGO_DEBUG__` define being delivered to the browser (which dev did only as
+// an injected global whose presence varied across consumer setups).
+//
+// Keep this module to the single INTERNAL_RANGO_DEBUG export: the transform
+// replaces the whole file, so a second export would be dropped from the bundle.
 export const INTERNAL_RANGO_DEBUG: boolean =
-  typeof __RANGO_DEBUG__ !== "undefined"
-    ? __RANGO_DEBUG__
-    : typeof process !== "undefined" &&
-      Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);
-
-declare const __RANGO_DEBUG__: boolean;
+  typeof process !== "undefined" &&
+  Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);