@rangojs/router 0.0.0-experimental.84 → 0.0.0-experimental.86

package/src/types/request-scope.ts

@@ -0,0 +1,126 @@
+/**
+ * RequestScope: the fields every user-facing context shares.
+ *
+ * A handler, middleware, loader, response handler, and the ALS-bound
+ * RequestContext are all different phases of the same request, and they
+ * all carry the same set of request-scoped capabilities: the raw Request,
+ * the parsed URL pair (`url` is cleaned of internal `_rsc*` params,
+ * `originalUrl` retains them), pathname/searchParams, platform bindings
+ * (`env`), and two escape hatches for work that outlives the response
+ * (`waitUntil`) or needs the raw Cloudflare runtime object
+ * (`executionContext`).
+ *
+ * Each public context type intersects `RequestScope<TEnv>` with its own
+ * phase-specific fields (e.g. `params`/`reverse` on HandlerContext,
+ * `headers`/`header()` on MiddlewareContext). That keeps platform surface
+ * in one place and lets the next runtime escape hatch we need land in
+ * one file instead of four.
+ */
+
+import type { DefaultEnv } from "./global-namespace.js";
+
+/**
+ * Minimal subset of Cloudflare Workers' ExecutionContext that the router
+ * uses. Defined locally so the package does not depend on
+ * `@cloudflare/workers-types`. Consumers that want the full type can cast.
+ *
+ * On non-Cloudflare runtimes (Node, dev server, tests), this is undefined
+ * — portable apps should prefer `ctx.waitUntil(...)`, which degrades
+ * gracefully. `ctx.executionContext` is the escape hatch for libraries
+ * (MCP, Durable Object routing, etc.) that type their arguments as the
+ * raw ExecutionContext.
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<any>): void;
+  passThroughOnException(): void;
+}
+
+/**
+ * Fallback `waitUntil` body used when no Cloudflare `ExecutionContext`
+ * is available (Node, dev, tests). Runs the work fire-and-forget and
+ * logs errors so they don't silently swallow.
+ *
+ * Exported so every `waitUntil` call site degrades identically instead
+ * of inventing its own fallback policy.
+ */
+export function fireAndForgetWaitUntil(fn: () => Promise<void>): void {
+  fn().catch((err) =>
+    console.error("[waitUntil] Background task failed:", err),
+  );
+}
+
+/**
+ * Fields present on every user-facing request context.
+ *
+ * @template TEnv - Platform bindings type (Cloudflare env, etc.).
+ */
+export interface RequestScope<TEnv = DefaultEnv> {
+  /**
+   * The original incoming Request object (transport URL intact).
+   * Use `url` / `searchParams` for application logic — those have
+   * internal `_rsc*` params stripped. `request` preserves the raw URL
+   * when you need original headers, method, or body.
+   */
+  request: Request;
+
+  /**
+   * The request URL with internal `_rsc*` transport params stripped.
+   * Use this for routing, link generation, and display.
+   */
+  url: URL;
+
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params. Use `url` for application logic
+   * — this is only needed for advanced cases like debugging or custom
+   * cache keying.
+   */
+  originalUrl: URL;
+
+  /** URL pathname (same as `url.pathname`). */
+  pathname: string;
+
+  /**
+   * Query parameters from the URL (system params like `_rsc*` are
+   * filtered). Always a standard `URLSearchParams` instance.
+   */
+  searchParams: URLSearchParams;
+
+  /**
+   * Platform bindings (DB, KV, secrets, etc.). On Cloudflare Workers
+   * these are the `env` object passed to the Worker's `fetch()` handler.
+   */
+  env: TEnv;
+
+  /**
+   * Schedule work to run after the response is sent.
+   * On Cloudflare Workers, delegates to `executionContext.waitUntil()`.
+   * On Node / dev / tests, runs as fire-and-forget with error logging.
+   *
+   * @example
+   * ```typescript
+   * ctx.waitUntil(async () => {
+   *   await cacheStore.set(key, data, ttl);
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<void>): void;
+
+  /**
+   * Raw Cloudflare Workers `ExecutionContext`, when running on a
+   * Cloudflare-compatible runtime. Undefined elsewhere.
+   *
+   * Escape hatch for libraries that type their arguments as
+   * `ExecutionContext` (MCP `fetch`, `routeAgentRequest`, etc.).
+   * For the common "do work after the response" case, prefer
+   * `ctx.waitUntil(...)` — it is platform-neutral.
+   *
+   * @example
+   * ```typescript
+   * path.any("/mcp", (ctx) =>
+   *   emailMcp.fetch(ctx.request, ctx.env, ctx.executionContext!),
+   * );
+   * ```
+   */
+  executionContext?: ExecutionContext;
+}

package/src/urls/response-types.ts

@@ -5,6 +5,7 @@ import type {
   DefaultVars,
 } from "../types/global-namespace.js";
 import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
+import type { RequestScope } from "../types/request-scope.js";
 
 /**
  * Reverse function for response handler contexts.
@@ -93,19 +94,10 @@ export type TextResponseHandler<
 export interface ResponseHandlerContext<
   TParams = Record<string, string>,
   TEnv = any,
-> {
-  request: Request;
+> extends RequestScope<TEnv> {
   params: TParams;
   /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
   readonly _paramCheck?: (params: TParams) => TParams;
-  /** Platform bindings (DB, KV, secrets, etc.). */
-  env: TEnv;
-  /** Query parameters from the URL (system params like `_rsc*` are filtered). */
-  searchParams: URLSearchParams;
-  /** The full URL object (with system params filtered). */
-  url: URL;
-  /** The pathname portion of the request URL. */
-  pathname: string;
   reverse: ResponseReverseFunction;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {

package/src/vite/rango.ts

@@ -12,6 +12,7 @@ import { VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import {
   getExcludeDeps,
   getPackageAliases,
+  getPublishedPackageName,
 } from "./utils/package-resolution.js";
 import { findRouterFiles } from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
@@ -72,6 +73,13 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
   ];
 
+  // Vite supports a nested `A > B` syntax in optimizeDeps.include that resolves
+  // B from A's location. We anchor transitive deps (rsc-html-stream,
+  // @vitejs/plugin-rsc/vendor/*) to @rangojs/router so pnpm consumers — where
+  // these aren't visible at the app root — can still pre-bundle them.
+  const pkg = getPublishedPackageName();
+  const nested = (spec: string) => `${pkg} > ${spec}`;
+
   // Mutable ref for router path (node preset only).
   // Set immediately when user-specified, or populated by the auto-discover
   // config() hook using Vite's resolved root.
@@ -126,7 +134,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               // Pre-bundle rsc-html-stream to prevent discovery during first request
               // Exclude rsc-router modules to ensure same Context instance
               optimizeDeps: {
-                include: ["rsc-html-stream/client"],
+                include: [nested("rsc-html-stream/client")],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
               },
@@ -151,8 +159,10 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom/static.edge",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "rsc-html-stream/server",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  nested("rsc-html-stream/server"),
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -167,7 +177,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -280,7 +292,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "rsc-html-stream/client",
+                  nested("rsc-html-stream/client"),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -297,7 +309,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom/static.edge",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -310,7 +324,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  ),
                 ],
                 esbuildOptions: sharedEsbuildOptions,
               },

package/src/vite/utils/banner.ts

@@ -1,4 +1,4 @@
-import packageJson from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json";
 
 export const rangoVersion: string = packageJson.version;
 

package/src/vite/utils/package-resolution.ts

@@ -7,7 +7,7 @@
 
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import packageJson from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json";
 
 /**
  * The canonical name used in virtual entries (without scope)