@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/host/router.ts

@@ -32,27 +32,16 @@ import {
   InvalidHandlerError,
 } from "./errors.js";
 
-/**
- * Registry entry for a host router instance.
- * Stores references to the live routes array and fallback, so the discovery
- * plugin can iterate handlers registered after createHostRouter() returns.
- */
 export interface HostRouterRegistryEntry {
   routes: RouteEntry[];
   fallback: RouteEntry | null;
 }
 
-/**
- * Global registry for host routers (parallel to RouterRegistry for RSC routers).
- * Populated by createHostRouter() so the build-time discovery plugin can find
- * host routers and resolve their lazy handlers to trigger sub-app createRouter() calls.
- */
 export const HostRouterRegistry: Map<string, HostRouterRegistryEntry> =
   new Map();
 
 let hostRouterAutoId = 0;
 
-/** Whether a value is thenable (a Promise or Promise-like). */
 function isThenable(value: unknown): value is PromiseLike<unknown> {
   return (
     value !== null &&
@@ -61,12 +50,6 @@ function isThenable(value: unknown): value is PromiseLike<unknown> {
   );
 }
 
-/**
- * Whether a resolved value looks like a module namespace from a lazy import -
- * an object with a `default` export that is a function (a Handler) or a host
- * router (an object with `match`). Used to detect a `.map(() => import(...))`
- * misuse: an inline handler should return a Response, not a module.
- */
 function looksLikeLazyModule(value: unknown): boolean {
   if (value === null || typeof value !== "object" || !("default" in value)) {
     return false;
@@ -80,9 +63,6 @@ function looksLikeLazyModule(value: unknown): boolean {
   );
 }
 
-/**
- * Create a host router
- */
 export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
   const routes: RouteEntry[] = [];
   const globalMiddleware: Middleware[] = [];
@@ -96,9 +76,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     }
   }
 
-  /**
-   * Create a route builder for chaining
-   */
   function createRouteBuilder(
     patterns: string[],
     isFallback = false,
@@ -147,9 +124,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     };
   }
 
-  /**
-   * Find matching route for hostname and path
-   */
   function findMatchingRoute(
     hostname: string,
     pathname: string,
@@ -168,9 +142,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     return null;
   }
 
-  /**
-   * Execute middleware chain
-   */
   async function executeMiddleware(
     middleware: Middleware[],
     request: Request,
@@ -189,8 +160,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         return finalHandler();
       }
 
-      // Guard against double next() calls — a second call would
-      // re-enter the downstream chain and run handlers/side-effects twice.
       let nextCalled = false;
       const guardedNext = (): Promise<Response> => {
         if (nextCalled) {
@@ -208,15 +177,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     return next();
   }
 
-  /**
-   * Execute a route entry, branching on its declared kind:
-   *   - "lazy": await the loader, then delegate to the default export
-   *     (a nested HostRouter via `.match`, or a request Handler directly).
-   *   - "handler": call the inline handler with the request. A `.map()` handler
-   *     that resolves to a module namespace (`{ default }`) is almost certainly
-   *     a misused lazy import, so it is rejected with a clear message rather
-   *     than silently returning a module object as the response.
-   */
   async function executeHandler(
     entry: RouteEntry,
     request: Request,
@@ -236,8 +196,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
 
     const result = (handler as Handler)(request, input);
 
-    // Inline handlers may be async; await to obtain the Response and to run the
-    // misuse guard below.
     if (isThenable(result)) {
       const awaited = await result;
       if (looksLikeLazyModule(awaited)) {
@@ -251,10 +209,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     return result;
   }
 
-  /**
-   * Resolve a `.lazy()` mount: invoke the zero-arg loader, then dispatch to the
-   * module's default export.
-   */
   async function executeLazyMount(
     loader: LazyHandler,
     request: Request,
@@ -266,7 +220,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
       const defaultExport = (module as { default: Handler | HostRouter })
         .default;
 
-      // Default export is a nested host router
       if (
         typeof defaultExport === "object" &&
         defaultExport !== null &&
@@ -275,7 +228,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         return (defaultExport as HostRouter).match(request, input);
       }
 
-      // Otherwise treat the default export as a request handler
       return (defaultExport as Handler)(request, input);
     }
 
@@ -288,14 +240,10 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     });
   }
 
-  /**
-   * Router instance
-   */
   const router: HostRouter = {
     host(patterns: HostPattern): HostRouteBuilder {
       const patternsArray = Array.isArray(patterns) ? patterns : [patterns];
 
-      // Validate and normalize patterns
       const normalized = patternsArray.map((p) => {
         validatePattern(p);
         return normalizePattern(p);
@@ -314,9 +262,8 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
       return createRouteBuilder([], true);
     },
 
-    test(hostname: string): HostMatchResult | null {
+    test(hostname: string, pathname = "/"): HostMatchResult | null {
       const parts = hostname.split(".");
-      const pathname = "/";
 
       for (const route of routes) {
         for (const pattern of route.patterns) {
@@ -342,14 +289,11 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
       let effectiveHostname: string;
 
       try {
-        // Handle cookie override (may throw HostRouterError)
         effectiveHostname = handleCookieOverride(request, hostOverride, input);
       } catch (error) {
-        // If it's a HostRouterError from cookie override
         if (error instanceof HostRouterError) {
           log(`Cookie override error: ${error.message}`);
 
-          // If fallback exists, use it
           if (fallbackRoute) {
             const fallbackInput = { ...input, error };
             const allMiddleware = [
@@ -365,7 +309,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
             );
           }
 
-          // Otherwise return error response with cookie deletion
           if (hostOverride) {
             return createCookieErrorResponse(
               hostOverride.cookieName,
@@ -374,7 +317,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
           }
         }
 
-        // Re-throw non-HostRouterErrors
         throw error;
       }
 
@@ -384,7 +326,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         log(`Cookie override: ${effectiveHostname}`);
       }
 
-      // Find matching route
       const matchedRoute = findMatchingRoute(effectiveHostname, pathname);
 
       if (!matchedRoute) {
@@ -397,19 +338,14 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         });
       }
 
-      // Combine global and route-specific middleware
       const allMiddleware = [...globalMiddleware, ...matchedRoute.middleware];
 
-      // Execute middleware chain and handler
       return executeMiddleware(allMiddleware, request, input, () =>
         executeHandler(matchedRoute, request, input),
       );
     },
   };
 
-  // Register in the global HostRouterRegistry for build-time discovery.
-  // The routes array and fallbackRoute ref are live - they reflect routes
-  // added via .host().map()/.lazy() after this point.
   const registryId = `host-router-${hostRouterAutoId++}`;
   HostRouterRegistry.set(registryId, {
     get routes() {

package/src/host/testing.ts

@@ -4,7 +4,7 @@
  * Helper functions for testing host routing.
  */
 
-import { matchPattern } from "./pattern-matcher.js";
+import { matchPattern, parseRequest } from "./pattern-matcher.js";
 
 export interface CreateTestRequestOptions {
   host: string;
@@ -14,18 +14,6 @@ export interface CreateTestRequestOptions {
   headers?: Record<string, string>;
 }
 
-/**
- * Create a test request with specific host and cookies
- *
- * @example
- * ```ts
- * const request = createTestRequest({
- *   host: 'admin.example.com',
- *   path: '/dashboard',
- *   cookies: { 'x-requested-host': 'api.example.com' }
- * });
- * ```
- */
 export function createTestRequest(options: CreateTestRequestOptions): Request {
   const {
     host,
@@ -38,7 +26,6 @@ export function createTestRequest(options: CreateTestRequestOptions): Request {
   const url = `http://${host}${path}`;
   const requestHeaders = new Headers(headers);
 
-  // Add cookies if provided
   if (Object.keys(cookies).length > 0) {
     const cookieString = Object.entries(cookies)
       .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
@@ -52,28 +39,54 @@ export function createTestRequest(options: CreateTestRequestOptions): Request {
   });
 }
 
+function matchPatterns(
+  pattern: string | string[],
+  hostname: string,
+  pathname: string,
+  parts: string[],
+): boolean {
+  const patterns = Array.isArray(pattern) ? pattern : [pattern];
+  return patterns.some((p) => matchPattern(p, hostname, pathname, parts));
+}
+
 /**
- * Test if a pattern matches a hostname
+ * Test if a pattern matches a hostname (and, for path-based patterns, a pathname).
+ *
+ * `pathname` defaults to `"/"`, so a host-only pattern works with two args. Pass
+ * the third arg to test a path-based pattern (`**.workers.dev/admin`,
+ * `localhost/shop`) — without it those patterns can never match.
  *
  * @example
  * ```ts
- * expect(testPattern('admin.*', 'admin.example.com')).toBe(true);
- * expect(testPattern(['*', 'www.*'], 'example.com')).toBe(true);
+ * expect(testPattern("admin.*", "admin.example.com")).toBe(true);
+ * expect(testPattern(["*", "www.*"], "example.com")).toBe(true);
+ * expect(testPattern("**.workers.dev/admin", "foo.workers.dev", "/admin")).toBe(true);
  * ```
  */
 export function testPattern(
   pattern: string | string[],
   hostname: string,
+  pathname: string = "/",
 ): boolean {
-  const patterns = Array.isArray(pattern) ? pattern : [pattern];
-  const parts = hostname.split(".");
-  const pathname = "/";
-
-  for (const p of patterns) {
-    if (matchPattern(p, hostname, pathname, parts)) {
-      return true;
-    }
-  }
+  return matchPatterns(pattern, hostname, pathname, hostname.split("."));
+}
 
-  return false;
+/**
+ * Test if a pattern matches a `Request` — the hostname AND pathname are taken
+ * from the request URL (via the same `parseRequest` the host router uses), so a
+ * path-based pattern is tested against a real request without splitting the URL
+ * by hand.
+ *
+ * @example
+ * ```ts
+ * const req = new Request("https://foo.workers.dev/admin");
+ * expect(matchesHost("**.workers.dev/admin", req)).toBe(true);
+ * ```
+ */
+export function matchesHost(
+  pattern: string | string[],
+  request: Request,
+): boolean {
+  const { hostname, pathname, parts } = parseRequest(request);
+  return matchPatterns(pattern, hostname, pathname, parts);
 }

package/src/host/types.ts

@@ -110,9 +110,13 @@ export interface HostRouter {
   fallback(): HostRouteBuilder;
 
   /**
-   * Test which handler would match a hostname
+   * Test which handler would match a hostname (and optional pathname).
+   *
+   * `pathname` defaults to `"/"`. Pass it to probe path-prefixed patterns
+   * such as `host(["example.com/admin"])`, which only match when the request
+   * path is under the prefix.
    */
-  test(hostname: string): HostMatchResult | null;
+  test(hostname: string, pathname?: string): HostMatchResult | null;
 }
 
 /**

package/src/href-client.ts

@@ -16,7 +16,6 @@
 
 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
@@ -163,16 +162,16 @@ type ResponsePayloadForKey<
     }[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 }>`.
+ * 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<
   TPath extends string,
   TRoutes = GetRegisteredRoutes,
-> = ResponseEnvelope<JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>>;
+> = JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>;
 
 /**
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
@@ -256,7 +255,7 @@ declare global {
      *
      * 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
+     * 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
@@ -299,13 +298,9 @@ declare global {
  */
 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;
 }
 

package/src/index.rsc.ts

@@ -75,6 +75,13 @@ export type {
   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,
@@ -107,6 +114,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";
@@ -124,10 +138,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 {
@@ -138,8 +157,7 @@ export {
   type IncludeOptions,
   type IncludeItem,
   type RouteResponse,
-  type ResponseError,
-  type ResponseEnvelope,
+  type ProblemDetails,
   type ResponseHandler,
   type ResponseHandlerContext,
   type JsonResponseHandler,
@@ -163,6 +181,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).
@@ -185,6 +208,8 @@ export const getRequestContext: <
 export {
   cookies,
   headers,
+  invalidateClientCache,
+  keepClientCache,
   type CookieStore,
   type Cookie,
   type ReadonlyHeaders,
@@ -193,7 +218,7 @@ export {
 // 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: stale-while-revalidate invalidation (background, for webhooks).
+// 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";
 
@@ -201,7 +226,13 @@ export { updateTag, revalidateTag } from "./cache/tag-invalidation.js";
 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 {
@@ -232,11 +263,47 @@ export {
 // 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

@@ -104,8 +104,7 @@ export type {
   JsonResponsePathFn,
   TextResponsePathFn,
   RouteResponse,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
 } from "./urls.js";
 
 // Middleware context types
@@ -141,6 +140,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";
@@ -218,6 +224,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.
  */
@@ -290,6 +307,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
@@ -327,8 +349,42 @@ export {
 // 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, OTelSpan } from "./router/telemetry-otel.js";
-export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.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/internal-debug.ts

@@ -1,7 +1,5 @@
-// 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).
+// Vite define for compile-time injection; falls back to process.env (tests, Node).
+// Works in all runtimes including Cloudflare Workers where process.env is unavailable.
 export const INTERNAL_RANGO_DEBUG: boolean =
   typeof __RANGO_DEBUG__ !== "undefined"
     ? __RANGO_DEBUG__