@rshono/core 1.0.0-rc.2 → 1.0.0-rc.4

package/dist/runtime/context.d.ts

@@ -1,5 +1,5 @@
 /**
- * The request context: {@link getContext} and the {@link Ctx} wrapper it returns,
+ * The request context: {@link getRequestContext} and the {@link RequestContext} wrapper it returns,
  * the {@link redirect} / {@link notFound} control-flow helpers, and the
  * {@link onServerError} reporting funnel — plus the `@internal` plumbing that binds
  * a request to the async context in the first place.
@@ -9,7 +9,7 @@
  * here is safe in a `'use client'` module — those run in the browser, with no bound
  * request context.
  */
-import type { Context, Env, HonoRequest } from 'hono';
+import type { Context, Env } from 'hono';
 import type { CookieOptions } from 'hono/utils/cookie';
 /**
  * HTTP status codes accepted by {@link redirect}.
@@ -22,21 +22,21 @@ import type { CookieOptions } from 'hono/utils/cookie';
 export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
 /**
  * Runs `fn` with the given Hono {@link Context} bound as the ambient request
- * context, so that {@link getContext} resolves to it anywhere in the call tree.
+ * context, so that {@link getRequestContext} resolves to it anywhere in the call tree.
  *
  * Framework internal — the request handler wraps every render and action in
- * this. Application code should reach for {@link getContext} instead.
+ * this. Application code should reach for {@link getRequestContext} instead.
  *
  * @internal
  */
 export declare function runWithContext<T>(c: Context, fn: () => T): T;
 /**
  * Reads the matched route params, returning an empty object when there is no
- * active route match (rather than throwing). Shared by {@link Ctx.params} and the
- * request renderer so the fallback behaviour stays in one place.
+ * active route match (rather than throwing), so the fallback behaviour stays in
+ * one place.
  *
- * Framework internal — read params from {@link Ctx.params} or a page's
- * `PageProps` instead.
+ * Framework internal — the request renderer calls this to build a page's `params`
+ * prop. Read them from that prop (or `ctx.raw.req.param()` outside a page) instead.
  *
  * @internal
  */
@@ -51,7 +51,7 @@ export declare function readParams(c: Context): Record<string, string>;
  * dictate the origin of every absolute URL the app builds — canonical tags, emails, redirects — and
  * poison a shared cache with them. So the default is to ignore them entirely.
  *
- * Framework internal — prefer {@link Ctx.url}, which caches the result per request.
+ * Framework internal — prefer {@link RequestContext.url}, which caches the result per request.
  *
  * @internal
  */
@@ -59,49 +59,52 @@ export declare function publicUrl(c: Context): URL;
 /**
  * The environment available to a request: Cloudflare/Workers `Bindings` merged
  * with process env vars. Values not declared in `Bindings` are typed as
- * `string | undefined`. See {@link Ctx.env}.
+ * `string | undefined`. See {@link RequestContext.env}.
  */
 export type EnvVars<E extends Env> = E['Bindings'] & Record<string, string | undefined>;
 /**
  * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside
  * server components and server actions.
  *
- * Obtain one with {@link getContext}, or — in a page component — take it straight
+ * Obtain one with {@link getRequestContext}, or — in a page component — take it straight
  * off the `ctx` prop, which is this same object. Never construct it yourself. One
  * instance is reused for the lifetime of a request, so its lazy getters
- * ({@link Ctx.url}, {@link Ctx.env}) are computed at most once.
+ * ({@link RequestContext.url}, {@link RequestContext.env}) are computed at most once.
  *
  * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and
- *   `Variables`, so {@link Ctx.var} and {@link Ctx.env} stay typed.
+ *   `Variables`, so {@link RequestContext.var} and {@link RequestContext.env} stay typed.
  *
  * @example
  * ```tsx
- * import { getContext } from '@rshono/core/server';
+ * import { getRequestContext } from '@rshono/core/server';
  *
  * export default async function Whoami() {
- *   const ctx = getContext();
+ *   const ctx = getRequestContext();
  *   const session = ctx.cookies.get('session');
  *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;
  * }
  * ```
  */
-export declare class Ctx<E extends Env = Env> {
+export declare class RequestContext<E extends Env = Env> {
     #private;
     constructor(c: Context<E>);
     /**
-     * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose.
+     * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose — and
+     * deliberately most things. `req`, `method`, `params` and a `header()` setter used to sit on this class
+     * as one-line pass-throughs to `c.req`, `c.req.method`, `c.req.param()` and `c.header()`; they are
+     * reachable through here (`ctx.raw.req`, `ctx.raw.header(…)`) and adding no name of their own is the
+     * point. What stays below is what this wrapper actually *does*: a proxy-aware cached URL, an env that
+     * merges runtime bindings over process env, and cookies without a second import.
      *
      * A getter over a private field rather than a plain property, so it is not an *own enumerable*
      * one — which matters more than it looks. React's diagnostic for a value that cannot be sent to a
      * client component (`describeObjectForErrorMessage`) walks `Object.keys` recursively with no depth
      * limit and no cycle guard, and the Hono context graph reaches the socket and the whole server
-     * through `req.raw` and `env`. While this was a plain property, passing a `Ctx` to a `'use client'`
+     * through `req.raw` and `env`. While this was a plain property, passing a `RequestContext` to a `'use client'`
      * component blew the stack *inside that message builder* — so React's actual, accurate "you cannot
      * pass this" error never got printed. Hidden from `Object.keys`, the walk stops here.
      */
     get raw(): Context<E>;
-    /** The parsed Hono request (`c.req`) — headers, body parsing, param access, etc. */
-    get req(): HonoRequest;
     /**
      * The browser-facing request URL, proxy-header aware (see {@link publicUrl}) —
      * read `url.pathname`, `url.searchParams` and the rest off it. Parsed once and
@@ -109,13 +112,6 @@ export declare class Ctx<E extends Env = Env> {
      * it as read-only for that reason.
      */
     get url(): URL;
-    /** The HTTP method of the request, e.g. `GET` or `POST`. */
-    get method(): string;
-    /**
-     * Matched route params, e.g. `{ id }` for a `/users/[id]` route. Returns an
-     * empty object when there is no active route match (rather than throwing).
-     */
-    get params(): Record<string, string>;
     /**
      * Typed variables set by middleware via `c.set('user', …)`, read here as
      * `ctx.var.user`. Type them by parameterising this class's {@link Env}.
@@ -125,17 +121,15 @@ export declare class Ctx<E extends Env = Env> {
      * Environment for the request: process env vars merged with runtime bindings
      * (bindings win on conflict). Computed once and cached.
      *
-     * @example `const key = getContext().env.STRIPE_SECRET_KEY;`
+     * @example `const key = getRequestContext().env.STRIPE_SECRET_KEY;`
      */
     get env(): EnvVars<E>;
-    /** Sets a response header. Thin pass-through to `c.header(name, value)`. */
-    header(name: string, value: string): void;
     /**
      * Read and write request/response cookies.
      *
      * @example
      * ```ts
-     * const ctx = getContext();
+     * const ctx = getRequestContext();
      * ctx.cookies.get('session');                       // string | undefined
      * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });
      * ctx.cookies.delete('session', { path: '/' });
@@ -153,7 +147,7 @@ export declare class Ctx<E extends Env = Env> {
     };
 }
 /**
- * Returns the {@link Ctx} for the current request.
+ * Returns the {@link RequestContext} for the current request.
  *
  * This is the primary entry point for reading request data from a server
  * component or server action — the URL, cookies, params, env, and middleware
@@ -164,7 +158,7 @@ export declare class Ctx<E extends Env = Env> {
  * import is for everywhere else: a nested server component, or a `'use server'`
  * action module — neither of which receives props from the framework.
  *
- * @typeParam E - The app's Hono {@link Env}, to type {@link Ctx.var} and {@link Ctx.env}.
+ * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and {@link RequestContext.env}.
  * @throws If called at module load, where there is no ambient context to resolve.
  * @throws If called while prerendering a `render: 'static'` route, which has no
  *   per-request context at build time — mark the route `render: 'dynamic'` instead.
@@ -172,15 +166,15 @@ export declare class Ctx<E extends Env = Env> {
  * @example
  * ```ts
  * 'use server';
- * import { getContext, redirect } from '@rshono/core/server';
+ * import { getRequestContext, redirect } from '@rshono/core/server';
  *
  * export async function login(form: FormData) {
- *   getContext().cookies.set('session', String(form.get('email')), { httpOnly: true });
+ *   getRequestContext().cookies.set('session', String(form.get('email')), { httpOnly: true });
  *   redirect('/dashboard');
  * }
  * ```
  */
-export declare function getContext<E extends Env = Env>(): Ctx<E>;
+export declare function getRequestContext<E extends Env = Env>(): RequestContext<E>;
 /**
  * Redirects the request to `location` by throwing a control signal that the
  * framework catches and turns into an HTTP redirect response.
@@ -195,7 +189,7 @@ export declare function getContext<E extends Env = Env>(): Ctx<E>;
  *
  * @example
  * ```ts
- * const session = getContext().cookies.get('session');
+ * const session = getRequestContext().cookies.get('session');
  * if (!session) redirect('/login');
  * // session is defined below this line
  * ```
@@ -209,9 +203,11 @@ export declare function redirect(location: string, status?: RedirectStatus): nev
  *
  * @example
  * ```tsx
- * const user = await db.user.find(getContext().params.id);
- * if (!user) notFound();
- * return <Profile user={user} />; // user is non-null here
+ * export default async function Page({ params }: PageProps<'/users/:id'>) {
+ *   const user = await db.user.find(params.id);
+ *   if (!user) notFound();
+ *   return <Profile user={user} />; // user is non-null here
+ * }
  * ```
  */
 export declare function notFound(): never;

package/dist/runtime/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,MAAM,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAkCzD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7D;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,GAAG,CAmBzC;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,GAAG,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;;IAKlC,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAExB;IAED;;;;;;;;;;OAUG;IACH,IAAI,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAEpB;IAED,oFAAoF;IACpF,IAAI,GAAG,IAAI,WAAW,CAErB;IAED;;;;;OAKG;IACH,IAAI,GAAG,IAAI,GAAG,CAEb;IAED,4DAA4D;IAC5D,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEnC;IAED;;;OAGG;IACH,IAAI,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAElC;IAED;;;;;OAKG;IACH,IAAI,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAKpB;IAED,4EAA4E;IAC5E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAExC;IAED;;;;;;;;;;OAUG;IACH,OAAO;QACL,+DAA+D;QAC/D,GAAG,SAAS,MAAM,KAAG,MAAM,GAAG,SAAS;QACvC,wDAAwD;QACxD,GAAG,QAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;QAC/B,6GAA6G;QAC7G,GAAG,SAAS,MAAM,SAAS,MAAM,YAAY,aAAa,KAAG,IAAI;QACjE,gGAAgG;QAChG,MAAM,SAAS,MAAM,YAAY,aAAa,KAAG,IAAI;MAGrD;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAqBxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,cAAoB,GAAG,KAAK,CAE9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAEhC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAExE,0FAA0F;AAC1F,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,MAAM,EAAE,iBAAiB,CAAC;IAC1B,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8GAA8G;AAC9G,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAIvF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQtG"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAkCzD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7D;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,GAAG,CAmBzC;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;;IAK7C,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAExB;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAI,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAEpB;IAED;;;;;OAKG;IACH,IAAI,GAAG,IAAI,GAAG,CAEb;IAED;;;OAGG;IACH,IAAI,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAElC;IAED;;;;;OAKG;IACH,IAAI,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAKpB;IAED;;;;;;;;;;OAUG;IACH,OAAO;QACL,+DAA+D;QAC/D,GAAG,SAAS,MAAM,KAAG,MAAM,GAAG,SAAS;QACvC,wDAAwD;QACxD,GAAG,QAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;QAC/B,6GAA6G;QAC7G,GAAG,SAAS,MAAM,SAAS,MAAM,YAAY,aAAa,KAAG,IAAI;QACjE,gGAAgG;QAChG,MAAM,SAAS,MAAM,YAAY,aAAa,KAAG,IAAI;MAGrD;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,KAAK,cAAc,CAAC,CAAC,CAAC,CAqB1E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,cAAoB,GAAG,KAAK,CAE9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAEhC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAExE,0FAA0F;AAC1F,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,MAAM,EAAE,iBAAiB,CAAC;IAC1B,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8GAA8G;AAC9G,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAIvF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQtG"}

package/dist/runtime/context.js

@@ -1,6 +1,6 @@
 /// <reference path="../types/rshono-config.d.ts" />
 /**
- * The request context: {@link getContext} and the {@link Ctx} wrapper it returns,
+ * The request context: {@link getRequestContext} and the {@link RequestContext} wrapper it returns,
  * the {@link redirect} / {@link notFound} control-flow helpers, and the
  * {@link onServerError} reporting funnel — plus the `@internal` plumbing that binds
  * a request to the async context in the first place.
@@ -14,13 +14,13 @@ import { deleteCookie, getCookie, setCookie } from 'hono/cookie';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { NotFoundSignal, RedirectSignal } from './control.js';
 const contextStorage = new AsyncLocalStorage();
-/** One {@link Ctx} per Hono {@link Context}, so repeated `getContext()` calls in a request share its lazy getters. */
+/** One {@link RequestContext} per Hono {@link Context}, so repeated `getRequestContext()` calls in a request share its lazy getters. */
 const wrappers = new WeakMap();
 /**
  * `process.env`, snapshotted on first read.
  *
  * It is not a plain object — every enumeration crosses into the host environment, which made
- * spreading it (~20µs) by far the most expensive thing {@link Ctx.env} did, once per request that
+ * spreading it (~20µs) by far the most expensive thing {@link RequestContext.env} did, once per request that
  * touched it. Snapshotted lazily rather than at module load because `loadEnvFiles()` runs *after*
  * this module is imported, so an eager copy would miss everything from `.env`. The trade-off: a
  * `process.env` mutation after the first `ctx.env` read is not picked up.
@@ -34,7 +34,7 @@ function processEnv() {
  * rather than a server handling real requests. `build.ts` sets `RSHONO_PRERENDER`
  * before importing the app bundle and starting the prerender pass; the app bundle
  * inlines its own copy of this module, so a shared `process.env` (not a module-level
- * flag) is what reliably crosses that boundary. Read by {@link getContext} to turn a
+ * flag) is what reliably crosses that boundary. Read by {@link getRequestContext} to turn a
  * static route's request-context read into a clear build-time error instead of
  * silently baking synthetic build-time values (a `localhost` URL, no cookies, build
  * env) into the snapshot.
@@ -42,10 +42,10 @@ function processEnv() {
 const prerendering = typeof process !== 'undefined' && !!process.env?.RSHONO_PRERENDER;
 /**
  * Runs `fn` with the given Hono {@link Context} bound as the ambient request
- * context, so that {@link getContext} resolves to it anywhere in the call tree.
+ * context, so that {@link getRequestContext} resolves to it anywhere in the call tree.
  *
  * Framework internal — the request handler wraps every render and action in
- * this. Application code should reach for {@link getContext} instead.
+ * this. Application code should reach for {@link getRequestContext} instead.
  *
  * @internal
  */
@@ -54,11 +54,11 @@ export function runWithContext(c, fn) {
 }
 /**
  * Reads the matched route params, returning an empty object when there is no
- * active route match (rather than throwing). Shared by {@link Ctx.params} and the
- * request renderer so the fallback behaviour stays in one place.
+ * active route match (rather than throwing), so the fallback behaviour stays in
+ * one place.
  *
- * Framework internal — read params from {@link Ctx.params} or a page's
- * `PageProps` instead.
+ * Framework internal — the request renderer calls this to build a page's `params`
+ * prop. Read them from that prop (or `ctx.raw.req.param()` outside a page) instead.
  *
  * @internal
  */
@@ -89,7 +89,7 @@ const trustProxy = typeof __RSHONO_CONFIG__ !== 'undefined' && __RSHONO_CONFIG__
  * dictate the origin of every absolute URL the app builds — canonical tags, emails, redirects — and
  * poison a shared cache with them. So the default is to ignore them entirely.
  *
- * Framework internal — prefer {@link Ctx.url}, which caches the result per request.
+ * Framework internal — prefer {@link RequestContext.url}, which caches the result per request.
  *
  * @internal
  */
@@ -116,26 +116,26 @@ export function publicUrl(c) {
  * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside
  * server components and server actions.
  *
- * Obtain one with {@link getContext}, or — in a page component — take it straight
+ * Obtain one with {@link getRequestContext}, or — in a page component — take it straight
  * off the `ctx` prop, which is this same object. Never construct it yourself. One
  * instance is reused for the lifetime of a request, so its lazy getters
- * ({@link Ctx.url}, {@link Ctx.env}) are computed at most once.
+ * ({@link RequestContext.url}, {@link RequestContext.env}) are computed at most once.
  *
  * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and
- *   `Variables`, so {@link Ctx.var} and {@link Ctx.env} stay typed.
+ *   `Variables`, so {@link RequestContext.var} and {@link RequestContext.env} stay typed.
  *
  * @example
  * ```tsx
- * import { getContext } from '@rshono/core/server';
+ * import { getRequestContext } from '@rshono/core/server';
  *
  * export default async function Whoami() {
- *   const ctx = getContext();
+ *   const ctx = getRequestContext();
  *   const session = ctx.cookies.get('session');
  *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;
  * }
  * ```
  */
-export class Ctx {
+export class RequestContext {
     #raw;
     #url;
     #env;
@@ -143,23 +143,24 @@ export class Ctx {
         this.#raw = c;
     }
     /**
-     * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose.
+     * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose — and
+     * deliberately most things. `req`, `method`, `params` and a `header()` setter used to sit on this class
+     * as one-line pass-throughs to `c.req`, `c.req.method`, `c.req.param()` and `c.header()`; they are
+     * reachable through here (`ctx.raw.req`, `ctx.raw.header(…)`) and adding no name of their own is the
+     * point. What stays below is what this wrapper actually *does*: a proxy-aware cached URL, an env that
+     * merges runtime bindings over process env, and cookies without a second import.
      *
      * A getter over a private field rather than a plain property, so it is not an *own enumerable*
      * one — which matters more than it looks. React's diagnostic for a value that cannot be sent to a
      * client component (`describeObjectForErrorMessage`) walks `Object.keys` recursively with no depth
      * limit and no cycle guard, and the Hono context graph reaches the socket and the whole server
-     * through `req.raw` and `env`. While this was a plain property, passing a `Ctx` to a `'use client'`
+     * through `req.raw` and `env`. While this was a plain property, passing a `RequestContext` to a `'use client'`
      * component blew the stack *inside that message builder* — so React's actual, accurate "you cannot
      * pass this" error never got printed. Hidden from `Object.keys`, the walk stops here.
      */
     get raw() {
         return this.#raw;
     }
-    /** The parsed Hono request (`c.req`) — headers, body parsing, param access, etc. */
-    get req() {
-        return this.#raw.req;
-    }
     /**
      * The browser-facing request URL, proxy-header aware (see {@link publicUrl}) —
      * read `url.pathname`, `url.searchParams` and the rest off it. Parsed once and
@@ -169,17 +170,6 @@ export class Ctx {
     get url() {
         return (this.#url ??= publicUrl(this.#raw));
     }
-    /** The HTTP method of the request, e.g. `GET` or `POST`. */
-    get method() {
-        return this.#raw.req.method;
-    }
-    /**
-     * Matched route params, e.g. `{ id }` for a `/users/[id]` route. Returns an
-     * empty object when there is no active route match (rather than throwing).
-     */
-    get params() {
-        return readParams(this.#raw);
-    }
     /**
      * Typed variables set by middleware via `c.set('user', …)`, read here as
      * `ctx.var.user`. Type them by parameterising this class's {@link Env}.
@@ -191,7 +181,7 @@ export class Ctx {
      * Environment for the request: process env vars merged with runtime bindings
      * (bindings win on conflict). Computed once and cached.
      *
-     * @example `const key = getContext().env.STRIPE_SECRET_KEY;`
+     * @example `const key = getRequestContext().env.STRIPE_SECRET_KEY;`
      */
     get env() {
         if (this.#env)
@@ -200,16 +190,12 @@ export class Ctx {
         // The snapshot is shared, so hand it back as-is when there are no bindings to merge over it.
         return (this.#env = (bindings ? { ...processEnv(), ...bindings } : processEnv()));
     }
-    /** Sets a response header. Thin pass-through to `c.header(name, value)`. */
-    header(name, value) {
-        this.#raw.header(name, value);
-    }
     /**
      * Read and write request/response cookies.
      *
      * @example
      * ```ts
-     * const ctx = getContext();
+     * const ctx = getRequestContext();
      * ctx.cookies.get('session');                       // string | undefined
      * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });
      * ctx.cookies.delete('session', { path: '/' });
@@ -229,7 +215,7 @@ export class Ctx {
     };
 }
 /**
- * Returns the {@link Ctx} for the current request.
+ * Returns the {@link RequestContext} for the current request.
  *
  * This is the primary entry point for reading request data from a server
  * component or server action — the URL, cookies, params, env, and middleware
@@ -240,7 +226,7 @@ export class Ctx {
  * import is for everywhere else: a nested server component, or a `'use server'`
  * action module — neither of which receives props from the framework.
  *
- * @typeParam E - The app's Hono {@link Env}, to type {@link Ctx.var} and {@link Ctx.env}.
+ * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and {@link RequestContext.env}.
  * @throws If called at module load, where there is no ambient context to resolve.
  * @throws If called while prerendering a `render: 'static'` route, which has no
  *   per-request context at build time — mark the route `render: 'dynamic'` instead.
@@ -248,28 +234,28 @@ export class Ctx {
  * @example
  * ```ts
  * 'use server';
- * import { getContext, redirect } from '@rshono/core/server';
+ * import { getRequestContext, redirect } from '@rshono/core/server';
  *
  * export async function login(form: FormData) {
- *   getContext().cookies.set('session', String(form.get('email')), { httpOnly: true });
+ *   getRequestContext().cookies.set('session', String(form.get('email')), { httpOnly: true });
  *   redirect('/dashboard');
  * }
  * ```
  */
-export function getContext() {
+export function getRequestContext() {
     if (prerendering) {
-        throw new Error("[rshono] getContext() was called while prerendering a `render: 'static'` route. A static page " +
+        throw new Error("[rshono] getRequestContext() was called while prerendering a `render: 'static'` route. A static page " +
             'is rendered once at build time, so it has no per-request context to read (URL, cookies, ' +
             "headers, env). Change this route to `render: 'dynamic'` so it renders per request, or remove " +
-            'the getContext() call.');
+            'the getRequestContext() call.');
     }
     const c = contextStorage.getStore();
     if (!c) {
-        throw new Error('[rshono] getContext() was called outside a request. It only works inside a server component or a server action, not at module load.');
+        throw new Error('[rshono] getRequestContext() was called outside a request. It only works inside a server component or a server action, not at module load.');
     }
     let ctx = wrappers.get(c);
     if (!ctx) {
-        ctx = new Ctx(c);
+        ctx = new RequestContext(c);
         wrappers.set(c, ctx);
     }
     return ctx;
@@ -288,7 +274,7 @@ export function getContext() {
  *
  * @example
  * ```ts
- * const session = getContext().cookies.get('session');
+ * const session = getRequestContext().cookies.get('session');
  * if (!session) redirect('/login');
  * // session is defined below this line
  * ```
@@ -304,9 +290,11 @@ export function redirect(location, status = 303) {
  *
  * @example
  * ```tsx
- * const user = await db.user.find(getContext().params.id);
- * if (!user) notFound();
- * return <Profile user={user} />; // user is non-null here
+ * export default async function Page({ params }: PageProps<'/users/:id'>) {
+ *   const user = await db.user.find(params.id);
+ *   if (!user) notFound();
+ *   return <Profile user={user} />; // user is non-null here
+ * }
  * ```
  */
 export function notFound() {

package/dist/runtime/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"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","sourcesContent":["/// <reference path=\"../types/rshono-config.d.ts\" />\n/**\n * The request context: {@link getContext} and the {@link Ctx} wrapper it returns,\n * the {@link redirect} / {@link notFound} control-flow helpers, and the\n * {@link onServerError} reporting funnel — plus the `@internal` plumbing that binds\n * a request to the async context in the first place.\n *\n * The public half of this module is re-exported by `runtime/server.ts`, which is\n * what the `@rshono/core/server` subpath resolves to; import *that* from an app. Nothing\n * here is safe in a `'use client'` module — those run in the browser, with no bound\n * request context.\n */\n\nimport type { Context, Env, HonoRequest } from 'hono';\nimport { deleteCookie, getCookie, setCookie } from 'hono/cookie';\nimport type { CookieOptions } from 'hono/utils/cookie';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { NotFoundSignal, RedirectSignal } from './control.js';\n\n/**\n * HTTP status codes accepted by {@link redirect}.\n *\n * - `301` Moved Permanently, `308` Permanent Redirect — cacheable, permanent.\n * - `302` Found, `307` Temporary Redirect — temporary.\n * - `303` See Other — the default; forces a `GET` on the target, which is what\n *   you almost always want after a form action (post/redirect/get).\n */\nexport type RedirectStatus = 301 | 302 | 303 | 307 | 308;\n\nconst contextStorage = new AsyncLocalStorage<Context>();\n\n/** One {@link Ctx} per Hono {@link Context}, so repeated `getContext()` calls in a request share its lazy getters. */\nconst wrappers = new WeakMap<Context, Ctx>();\n\n/**\n * `process.env`, snapshotted on first read.\n *\n * It is not a plain object — every enumeration crosses into the host environment, which made\n * spreading it (~20µs) by far the most expensive thing {@link Ctx.env} did, once per request that\n * touched it. Snapshotted lazily rather than at module load because `loadEnvFiles()` runs *after*\n * this module is imported, so an eager copy would miss everything from `.env`. The trade-off: a\n * `process.env` mutation after the first `ctx.env` read is not picked up.\n */\nlet envSnapshot: Record<string, string | undefined> | undefined;\n\nfunction processEnv(): Record<string, string | undefined> {\n  return (envSnapshot ??= typeof process !== 'undefined' && process.env ? { ...process.env } : {});\n}\n\n/**\n * True when this process is the SSG build prerendering `render: 'static'` routes,\n * rather than a server handling real requests. `build.ts` sets `RSHONO_PRERENDER`\n * before importing the app bundle and starting the prerender pass; the app bundle\n * inlines its own copy of this module, so a shared `process.env` (not a module-level\n * flag) is what reliably crosses that boundary. Read by {@link getContext} to turn a\n * static route's request-context read into a clear build-time error instead of\n * silently baking synthetic build-time values (a `localhost` URL, no cookies, build\n * env) into the snapshot.\n */\nconst prerendering = typeof process !== 'undefined' && !!process.env?.RSHONO_PRERENDER;\n\n/**\n * Runs `fn` with the given Hono {@link Context} bound as the ambient request\n * context, so that {@link getContext} resolves to it anywhere in the call tree.\n *\n * Framework internal — the request handler wraps every render and action in\n * this. Application code should reach for {@link getContext} instead.\n *\n * @internal\n */\nexport function runWithContext<T>(c: Context, fn: () => T): T {\n  return contextStorage.run(c, fn);\n}\n\n/**\n * Reads the matched route params, returning an empty object when there is no\n * active route match (rather than throwing). Shared by {@link Ctx.params} and the\n * request renderer so the fallback behaviour stays in one place.\n *\n * Framework internal — read params from {@link Ctx.params} or a page's\n * `PageProps` instead.\n *\n * @internal\n */\nexport function readParams(c: Context): Record<string, string> {\n  try {\n    return c.req.param();\n  } catch {\n    return {};\n  }\n}\n\n/** A proxy chain appends to these headers, so the client-facing value is the first entry. */\nfunction firstForwardedValue(header: string | undefined): string | undefined {\n  const first = header?.split(',')[0]?.trim();\n  return first || undefined;\n}\n\n// DefinePlugin inlines the config into the server bundle, but this module is the public\n// `@rshono/core/server` entry and could be loaded by tooling that doesn't (a unit test, a one-off script).\n// Read through `typeof` so that degrades to the safe answer — don't trust — instead of a ReferenceError.\nconst trustProxy = typeof __RSHONO_CONFIG__ !== 'undefined' && __RSHONO_CONFIG__.trustProxy;\n\n/**\n * Resolves the browser-facing {@link URL} for a request.\n *\n * `c.req.url` reflects the internal address the server was reached on, which is wrong behind a\n * proxy or load balancer. `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when\n * `trustProxy` is enabled in `rshono.config.ts`** (always the case under `rshono dev`). Those\n * headers are client-supplied: honouring them unconditionally lets anyone who can reach the server\n * dictate the origin of every absolute URL the app builds — canonical tags, emails, redirects — and\n * poison a shared cache with them. So the default is to ignore them entirely.\n *\n * Framework internal — prefer {@link Ctx.url}, which caches the result per request.\n *\n * @internal\n */\nexport function publicUrl(c: Context): URL {\n  const url = new URL(c.req.url);\n  if (!trustProxy) return url;\n\n  const forwardedHost = firstForwardedValue(c.req.header('x-forwarded-host'));\n  // Parsed rather than assigned to `url.host`, because that setter *keeps the existing port* when\n  // the new value has none — leaving the internal port on the public URL (`example.com:3000`).\n  const forwarded = forwardedHost ? URL.parse(`http://${forwardedHost}`) : null;\n  if (forwarded) {\n    url.hostname = forwarded.hostname;\n    url.port = forwarded.port; // '' when the forwarded host carries no port, which clears it\n  }\n\n  // Restricted to the two schemes a browser can actually have requested; anything else (a proxy\n  // sending junk, or a client trying its luck) leaves the scheme alone.\n  const forwardedProto = firstForwardedValue(c.req.header('x-forwarded-proto'));\n  if (forwardedProto === 'http' || forwardedProto === 'https') url.protocol = forwardedProto;\n\n  return url;\n}\n\n/**\n * The environment available to a request: Cloudflare/Workers `Bindings` merged\n * with process env vars. Values not declared in `Bindings` are typed as\n * `string | undefined`. See {@link Ctx.env}.\n */\nexport type EnvVars<E extends Env> = E['Bindings'] & Record<string, string | undefined>;\n\n/**\n * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside\n * server components and server actions.\n *\n * Obtain one with {@link getContext}, or — in a page component — take it straight\n * off the `ctx` prop, which is this same object. Never construct it yourself. One\n * instance is reused for the lifetime of a request, so its lazy getters\n * ({@link Ctx.url}, {@link Ctx.env}) are computed at most once.\n *\n * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and\n *   `Variables`, so {@link Ctx.var} and {@link Ctx.env} stay typed.\n *\n * @example\n * ```tsx\n * import { getContext } from '@rshono/core/server';\n *\n * export default async function Whoami() {\n *   const ctx = getContext();\n *   const session = ctx.cookies.get('session');\n *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;\n * }\n * ```\n */\nexport class Ctx<E extends Env = Env> {\n  #raw: Context<E>;\n  #url?: URL;\n  #env?: EnvVars<E>;\n\n  constructor(c: Context<E>) {\n    this.#raw = c;\n  }\n\n  /**\n   * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose.\n   *\n   * A getter over a private field rather than a plain property, so it is not an *own enumerable*\n   * one — which matters more than it looks. React's diagnostic for a value that cannot be sent to a\n   * client component (`describeObjectForErrorMessage`) walks `Object.keys` recursively with no depth\n   * limit and no cycle guard, and the Hono context graph reaches the socket and the whole server\n   * through `req.raw` and `env`. While this was a plain property, passing a `Ctx` to a `'use client'`\n   * component blew the stack *inside that message builder* — so React's actual, accurate \"you cannot\n   * pass this\" error never got printed. Hidden from `Object.keys`, the walk stops here.\n   */\n  get raw(): Context<E> {\n    return this.#raw;\n  }\n\n  /** The parsed Hono request (`c.req`) — headers, body parsing, param access, etc. */\n  get req(): HonoRequest {\n    return this.#raw.req;\n  }\n\n  /**\n   * The browser-facing request URL, proxy-header aware (see {@link publicUrl}) —\n   * read `url.pathname`, `url.searchParams` and the rest off it. Parsed once and\n   * cached, so the same instance comes back on every read within a request; treat\n   * it as read-only for that reason.\n   */\n  get url(): URL {\n    return (this.#url ??= publicUrl(this.#raw as Context));\n  }\n\n  /** The HTTP method of the request, e.g. `GET` or `POST`. */\n  get method(): string {\n    return this.#raw.req.method;\n  }\n\n  /**\n   * Matched route params, e.g. `{ id }` for a `/users/[id]` route. Returns an\n   * empty object when there is no active route match (rather than throwing).\n   */\n  get params(): Record<string, string> {\n    return readParams(this.#raw as Context);\n  }\n\n  /**\n   * Typed variables set by middleware via `c.set('user', …)`, read here as\n   * `ctx.var.user`. Type them by parameterising this class's {@link Env}.\n   */\n  get var(): Readonly<E['Variables']> {\n    return this.#raw.var;\n  }\n\n  /**\n   * Environment for the request: process env vars merged with runtime bindings\n   * (bindings win on conflict). Computed once and cached.\n   *\n   * @example `const key = getContext().env.STRIPE_SECRET_KEY;`\n   */\n  get env(): EnvVars<E> {\n    if (this.#env) return this.#env;\n    const bindings = this.#raw.env as Record<string, unknown> | undefined;\n    // The snapshot is shared, so hand it back as-is when there are no bindings to merge over it.\n    return (this.#env = (bindings ? { ...processEnv(), ...bindings } : processEnv()) as EnvVars<E>);\n  }\n\n  /** Sets a response header. Thin pass-through to `c.header(name, value)`. */\n  header(name: string, value: string): void {\n    this.#raw.header(name, value);\n  }\n\n  /**\n   * Read and write request/response cookies.\n   *\n   * @example\n   * ```ts\n   * const ctx = getContext();\n   * ctx.cookies.get('session');                       // string | undefined\n   * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });\n   * ctx.cookies.delete('session', { path: '/' });\n   * ```\n   */\n  cookies = {\n    /** Reads a single cookie by name, or `undefined` if absent. */\n    get: (name: string): string | undefined => getCookie(this.#raw, name),\n    /** Reads every cookie as a `{ name: value }` record. */\n    all: (): Record<string, string> => getCookie(this.#raw),\n    /** Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`, `maxAge`, etc. */\n    set: (name: string, value: string, options?: CookieOptions): void => setCookie(this.#raw, name, value, options),\n    /** Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it. */\n    delete: (name: string, options?: CookieOptions): void => {\n      deleteCookie(this.#raw, name, options);\n    },\n  };\n}\n\n/**\n * Returns the {@link Ctx} for the current request.\n *\n * This is the primary entry point for reading request data from a server\n * component or server action — the URL, cookies, params, env, and middleware\n * variables. The returned wrapper is memoised per request, so repeated calls in\n * the same request are cheap and return the same instance.\n *\n * A **page** component is handed the very same object as its `ctx` prop, so this\n * import is for everywhere else: a nested server component, or a `'use server'`\n * action module — neither of which receives props from the framework.\n *\n * @typeParam E - The app's Hono {@link Env}, to type {@link Ctx.var} and {@link Ctx.env}.\n * @throws If called at module load, where there is no ambient context to resolve.\n * @throws If called while prerendering a `render: 'static'` route, which has no\n *   per-request context at build time — mark the route `render: 'dynamic'` instead.\n *\n * @example\n * ```ts\n * 'use server';\n * import { getContext, redirect } from '@rshono/core/server';\n *\n * export async function login(form: FormData) {\n *   getContext().cookies.set('session', String(form.get('email')), { httpOnly: true });\n *   redirect('/dashboard');\n * }\n * ```\n */\nexport function getContext<E extends Env = Env>(): Ctx<E> {\n  if (prerendering) {\n    throw new Error(\n      \"[rshono] getContext() was called while prerendering a `render: 'static'` route. A static page \" +\n        'is rendered once at build time, so it has no per-request context to read (URL, cookies, ' +\n        \"headers, env). Change this route to `render: 'dynamic'` so it renders per request, or remove \" +\n        'the getContext() call.',\n    );\n  }\n  const c = contextStorage.getStore();\n  if (!c) {\n    throw new Error(\n      '[rshono] getContext() was called outside a request. It only works inside a server component or a server action, not at module load.',\n    );\n  }\n  let ctx = wrappers.get(c);\n  if (!ctx) {\n    ctx = new Ctx(c);\n    wrappers.set(c, ctx);\n  }\n  return ctx as unknown as Ctx<E>;\n}\n\n/**\n * Redirects the request to `location` by throwing a control signal that the\n * framework catches and turns into an HTTP redirect response.\n *\n * Because it throws, it never returns — TypeScript narrows away any code after\n * the call, and you do not need to `return` it. Do not wrap it in a `try/catch`\n * that swallows the signal.\n *\n * @param location - Absolute path or URL to redirect to, e.g. `/dashboard`.\n * @param status - Redirect {@link RedirectStatus}; defaults to `303` (See Other),\n *   the correct choice after a form action so the browser follows up with a `GET`.\n *\n * @example\n * ```ts\n * const session = getContext().cookies.get('session');\n * if (!session) redirect('/login');\n * // session is defined below this line\n * ```\n */\nexport function redirect(location: string, status: RedirectStatus = 303): never {\n  throw new RedirectSignal(location, status);\n}\n\n/**\n * Aborts the current render with a 404, rendering the app's not-found page.\n *\n * Like {@link redirect}, this throws a control signal and never returns, so\n * TypeScript narrows away everything after the call. Do not catch-and-swallow it.\n *\n * @example\n * ```tsx\n * const user = await db.user.find(getContext().params.id);\n * if (!user) notFound();\n * return <Profile user={user} />; // user is non-null here\n * ```\n */\nexport function notFound(): never {\n  throw new NotFoundSignal();\n}\n\n/**\n * Which stage of a request produced an error handed to an {@link ServerErrorHandler}.\n *\n * - `action` — a `'use server'` function threw. React sends the client an opaque marker with no\n *   message in production, so this is the only place the real error is visible.\n * - `render` — a server component threw while the flight payload was being produced.\n * - `ssr` — SSR failed before the HTML shell could be sent, so the `error` page was unreachable too.\n * - `request` — anything else that reached the top-level handler, including a thrown endpoint route.\n */\nexport type ServerErrorSource = 'action' | 'render' | 'ssr' | 'request';\n\n/** What an {@link ServerErrorHandler} is told about an error, beyond the error itself. */\nexport interface ServerErrorContext {\n  /** The stage that produced it — see {@link ServerErrorSource}. */\n  source: ServerErrorSource;\n  /** The request being served, for the URL, method and headers. */\n  request: Request;\n}\n\n/** Handler registered with {@link onServerError}. Called for the side effect; its return value is ignored. */\nexport type ServerErrorHandler = (error: unknown, context: ServerErrorContext) => void;\n\nlet errorHandler: ServerErrorHandler | undefined;\n\n/**\n * Registers a handler for every error the framework catches, so they can reach an error tracker\n * (Sentry, Datadog, a log pipeline) instead of only `stderr`.\n *\n * Call it **once, at the top level of `src/server.ts`** — that module is imported as the server\n * starts, before any request is served. Registering again replaces the previous handler.\n *\n * Errors are still written to `stderr` either way, so a handler adds a destination rather than\n * replacing one. A handler that throws is caught and logged: reporting must never be able to fail\n * a request.\n *\n * @example\n * ```ts\n * // src/server.ts\n * import * as Sentry from '@sentry/node';\n * import { onServerError } from '@rshono/core/server';\n *\n * onServerError((error, { source, request }) => {\n *   Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });\n * });\n * ```\n */\nexport function onServerError(handler: ServerErrorHandler): void {\n  errorHandler = handler;\n}\n\n/**\n * Logs an error and forwards it to the registered {@link ServerErrorHandler}.\n *\n * Framework internal — the single funnel every caught server-side error goes through, so that\n * adding a reporting destination is one registration rather than a hook per call site.\n *\n * @internal\n */\nexport function reportServerError(error: unknown, info: ServerErrorContext & { message: string }): void {\n  console.error(info.message, error);\n  if (!errorHandler) return;\n  try {\n    errorHandler(error, { source: info.source, request: info.request });\n  } catch (handlerError) {\n    console.error('[rshono] the onServerError handler threw:', handlerError);\n  }\n}\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"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","sourcesContent":["/// <reference path=\"../types/rshono-config.d.ts\" />\n/**\n * The request context: {@link getRequestContext} and the {@link RequestContext} wrapper it returns,\n * the {@link redirect} / {@link notFound} control-flow helpers, and the\n * {@link onServerError} reporting funnel — plus the `@internal` plumbing that binds\n * a request to the async context in the first place.\n *\n * The public half of this module is re-exported by `runtime/server.ts`, which is\n * what the `@rshono/core/server` subpath resolves to; import *that* from an app. Nothing\n * here is safe in a `'use client'` module — those run in the browser, with no bound\n * request context.\n */\n\nimport type { Context, Env } from 'hono';\nimport { deleteCookie, getCookie, setCookie } from 'hono/cookie';\nimport type { CookieOptions } from 'hono/utils/cookie';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { NotFoundSignal, RedirectSignal } from './control.js';\n\n/**\n * HTTP status codes accepted by {@link redirect}.\n *\n * - `301` Moved Permanently, `308` Permanent Redirect — cacheable, permanent.\n * - `302` Found, `307` Temporary Redirect — temporary.\n * - `303` See Other — the default; forces a `GET` on the target, which is what\n *   you almost always want after a form action (post/redirect/get).\n */\nexport type RedirectStatus = 301 | 302 | 303 | 307 | 308;\n\nconst contextStorage = new AsyncLocalStorage<Context>();\n\n/** One {@link RequestContext} per Hono {@link Context}, so repeated `getRequestContext()` calls in a request share its lazy getters. */\nconst wrappers = new WeakMap<Context, RequestContext>();\n\n/**\n * `process.env`, snapshotted on first read.\n *\n * It is not a plain object — every enumeration crosses into the host environment, which made\n * spreading it (~20µs) by far the most expensive thing {@link RequestContext.env} did, once per request that\n * touched it. Snapshotted lazily rather than at module load because `loadEnvFiles()` runs *after*\n * this module is imported, so an eager copy would miss everything from `.env`. The trade-off: a\n * `process.env` mutation after the first `ctx.env` read is not picked up.\n */\nlet envSnapshot: Record<string, string | undefined> | undefined;\n\nfunction processEnv(): Record<string, string | undefined> {\n  return (envSnapshot ??= typeof process !== 'undefined' && process.env ? { ...process.env } : {});\n}\n\n/**\n * True when this process is the SSG build prerendering `render: 'static'` routes,\n * rather than a server handling real requests. `build.ts` sets `RSHONO_PRERENDER`\n * before importing the app bundle and starting the prerender pass; the app bundle\n * inlines its own copy of this module, so a shared `process.env` (not a module-level\n * flag) is what reliably crosses that boundary. Read by {@link getRequestContext} to turn a\n * static route's request-context read into a clear build-time error instead of\n * silently baking synthetic build-time values (a `localhost` URL, no cookies, build\n * env) into the snapshot.\n */\nconst prerendering = typeof process !== 'undefined' && !!process.env?.RSHONO_PRERENDER;\n\n/**\n * Runs `fn` with the given Hono {@link Context} bound as the ambient request\n * context, so that {@link getRequestContext} resolves to it anywhere in the call tree.\n *\n * Framework internal — the request handler wraps every render and action in\n * this. Application code should reach for {@link getRequestContext} instead.\n *\n * @internal\n */\nexport function runWithContext<T>(c: Context, fn: () => T): T {\n  return contextStorage.run(c, fn);\n}\n\n/**\n * Reads the matched route params, returning an empty object when there is no\n * active route match (rather than throwing), so the fallback behaviour stays in\n * one place.\n *\n * Framework internal — the request renderer calls this to build a page's `params`\n * prop. Read them from that prop (or `ctx.raw.req.param()` outside a page) instead.\n *\n * @internal\n */\nexport function readParams(c: Context): Record<string, string> {\n  try {\n    return c.req.param();\n  } catch {\n    return {};\n  }\n}\n\n/** A proxy chain appends to these headers, so the client-facing value is the first entry. */\nfunction firstForwardedValue(header: string | undefined): string | undefined {\n  const first = header?.split(',')[0]?.trim();\n  return first || undefined;\n}\n\n// DefinePlugin inlines the config into the server bundle, but this module is the public\n// `@rshono/core/server` entry and could be loaded by tooling that doesn't (a unit test, a one-off script).\n// Read through `typeof` so that degrades to the safe answer — don't trust — instead of a ReferenceError.\nconst trustProxy = typeof __RSHONO_CONFIG__ !== 'undefined' && __RSHONO_CONFIG__.trustProxy;\n\n/**\n * Resolves the browser-facing {@link URL} for a request.\n *\n * `c.req.url` reflects the internal address the server was reached on, which is wrong behind a\n * proxy or load balancer. `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when\n * `trustProxy` is enabled in `rshono.config.ts`** (always the case under `rshono dev`). Those\n * headers are client-supplied: honouring them unconditionally lets anyone who can reach the server\n * dictate the origin of every absolute URL the app builds — canonical tags, emails, redirects — and\n * poison a shared cache with them. So the default is to ignore them entirely.\n *\n * Framework internal — prefer {@link RequestContext.url}, which caches the result per request.\n *\n * @internal\n */\nexport function publicUrl(c: Context): URL {\n  const url = new URL(c.req.url);\n  if (!trustProxy) return url;\n\n  const forwardedHost = firstForwardedValue(c.req.header('x-forwarded-host'));\n  // Parsed rather than assigned to `url.host`, because that setter *keeps the existing port* when\n  // the new value has none — leaving the internal port on the public URL (`example.com:3000`).\n  const forwarded = forwardedHost ? URL.parse(`http://${forwardedHost}`) : null;\n  if (forwarded) {\n    url.hostname = forwarded.hostname;\n    url.port = forwarded.port; // '' when the forwarded host carries no port, which clears it\n  }\n\n  // Restricted to the two schemes a browser can actually have requested; anything else (a proxy\n  // sending junk, or a client trying its luck) leaves the scheme alone.\n  const forwardedProto = firstForwardedValue(c.req.header('x-forwarded-proto'));\n  if (forwardedProto === 'http' || forwardedProto === 'https') url.protocol = forwardedProto;\n\n  return url;\n}\n\n/**\n * The environment available to a request: Cloudflare/Workers `Bindings` merged\n * with process env vars. Values not declared in `Bindings` are typed as\n * `string | undefined`. See {@link RequestContext.env}.\n */\nexport type EnvVars<E extends Env> = E['Bindings'] & Record<string, string | undefined>;\n\n/**\n * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside\n * server components and server actions.\n *\n * Obtain one with {@link getRequestContext}, or — in a page component — take it straight\n * off the `ctx` prop, which is this same object. Never construct it yourself. One\n * instance is reused for the lifetime of a request, so its lazy getters\n * ({@link RequestContext.url}, {@link RequestContext.env}) are computed at most once.\n *\n * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and\n *   `Variables`, so {@link RequestContext.var} and {@link RequestContext.env} stay typed.\n *\n * @example\n * ```tsx\n * import { getRequestContext } from '@rshono/core/server';\n *\n * export default async function Whoami() {\n *   const ctx = getRequestContext();\n *   const session = ctx.cookies.get('session');\n *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;\n * }\n * ```\n */\nexport class RequestContext<E extends Env = Env> {\n  #raw: Context<E>;\n  #url?: URL;\n  #env?: EnvVars<E>;\n\n  constructor(c: Context<E>) {\n    this.#raw = c;\n  }\n\n  /**\n   * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose — and\n   * deliberately most things. `req`, `method`, `params` and a `header()` setter used to sit on this class\n   * as one-line pass-throughs to `c.req`, `c.req.method`, `c.req.param()` and `c.header()`; they are\n   * reachable through here (`ctx.raw.req`, `ctx.raw.header(…)`) and adding no name of their own is the\n   * point. What stays below is what this wrapper actually *does*: a proxy-aware cached URL, an env that\n   * merges runtime bindings over process env, and cookies without a second import.\n   *\n   * A getter over a private field rather than a plain property, so it is not an *own enumerable*\n   * one — which matters more than it looks. React's diagnostic for a value that cannot be sent to a\n   * client component (`describeObjectForErrorMessage`) walks `Object.keys` recursively with no depth\n   * limit and no cycle guard, and the Hono context graph reaches the socket and the whole server\n   * through `req.raw` and `env`. While this was a plain property, passing a `RequestContext` to a `'use client'`\n   * component blew the stack *inside that message builder* — so React's actual, accurate \"you cannot\n   * pass this\" error never got printed. Hidden from `Object.keys`, the walk stops here.\n   */\n  get raw(): Context<E> {\n    return this.#raw;\n  }\n\n  /**\n   * The browser-facing request URL, proxy-header aware (see {@link publicUrl}) —\n   * read `url.pathname`, `url.searchParams` and the rest off it. Parsed once and\n   * cached, so the same instance comes back on every read within a request; treat\n   * it as read-only for that reason.\n   */\n  get url(): URL {\n    return (this.#url ??= publicUrl(this.#raw as Context));\n  }\n\n  /**\n   * Typed variables set by middleware via `c.set('user', …)`, read here as\n   * `ctx.var.user`. Type them by parameterising this class's {@link Env}.\n   */\n  get var(): Readonly<E['Variables']> {\n    return this.#raw.var;\n  }\n\n  /**\n   * Environment for the request: process env vars merged with runtime bindings\n   * (bindings win on conflict). Computed once and cached.\n   *\n   * @example `const key = getRequestContext().env.STRIPE_SECRET_KEY;`\n   */\n  get env(): EnvVars<E> {\n    if (this.#env) return this.#env;\n    const bindings = this.#raw.env as Record<string, unknown> | undefined;\n    // The snapshot is shared, so hand it back as-is when there are no bindings to merge over it.\n    return (this.#env = (bindings ? { ...processEnv(), ...bindings } : processEnv()) as EnvVars<E>);\n  }\n\n  /**\n   * Read and write request/response cookies.\n   *\n   * @example\n   * ```ts\n   * const ctx = getRequestContext();\n   * ctx.cookies.get('session');                       // string | undefined\n   * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });\n   * ctx.cookies.delete('session', { path: '/' });\n   * ```\n   */\n  cookies = {\n    /** Reads a single cookie by name, or `undefined` if absent. */\n    get: (name: string): string | undefined => getCookie(this.#raw, name),\n    /** Reads every cookie as a `{ name: value }` record. */\n    all: (): Record<string, string> => getCookie(this.#raw),\n    /** Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`, `maxAge`, etc. */\n    set: (name: string, value: string, options?: CookieOptions): void => setCookie(this.#raw, name, value, options),\n    /** Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it. */\n    delete: (name: string, options?: CookieOptions): void => {\n      deleteCookie(this.#raw, name, options);\n    },\n  };\n}\n\n/**\n * Returns the {@link RequestContext} for the current request.\n *\n * This is the primary entry point for reading request data from a server\n * component or server action — the URL, cookies, params, env, and middleware\n * variables. The returned wrapper is memoised per request, so repeated calls in\n * the same request are cheap and return the same instance.\n *\n * A **page** component is handed the very same object as its `ctx` prop, so this\n * import is for everywhere else: a nested server component, or a `'use server'`\n * action module — neither of which receives props from the framework.\n *\n * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and {@link RequestContext.env}.\n * @throws If called at module load, where there is no ambient context to resolve.\n * @throws If called while prerendering a `render: 'static'` route, which has no\n *   per-request context at build time — mark the route `render: 'dynamic'` instead.\n *\n * @example\n * ```ts\n * 'use server';\n * import { getRequestContext, redirect } from '@rshono/core/server';\n *\n * export async function login(form: FormData) {\n *   getRequestContext().cookies.set('session', String(form.get('email')), { httpOnly: true });\n *   redirect('/dashboard');\n * }\n * ```\n */\nexport function getRequestContext<E extends Env = Env>(): RequestContext<E> {\n  if (prerendering) {\n    throw new Error(\n      \"[rshono] getRequestContext() was called while prerendering a `render: 'static'` route. A static page \" +\n        'is rendered once at build time, so it has no per-request context to read (URL, cookies, ' +\n        \"headers, env). Change this route to `render: 'dynamic'` so it renders per request, or remove \" +\n        'the getRequestContext() call.',\n    );\n  }\n  const c = contextStorage.getStore();\n  if (!c) {\n    throw new Error(\n      '[rshono] getRequestContext() was called outside a request. It only works inside a server component or a server action, not at module load.',\n    );\n  }\n  let ctx = wrappers.get(c);\n  if (!ctx) {\n    ctx = new RequestContext(c);\n    wrappers.set(c, ctx);\n  }\n  return ctx as unknown as RequestContext<E>;\n}\n\n/**\n * Redirects the request to `location` by throwing a control signal that the\n * framework catches and turns into an HTTP redirect response.\n *\n * Because it throws, it never returns — TypeScript narrows away any code after\n * the call, and you do not need to `return` it. Do not wrap it in a `try/catch`\n * that swallows the signal.\n *\n * @param location - Absolute path or URL to redirect to, e.g. `/dashboard`.\n * @param status - Redirect {@link RedirectStatus}; defaults to `303` (See Other),\n *   the correct choice after a form action so the browser follows up with a `GET`.\n *\n * @example\n * ```ts\n * const session = getRequestContext().cookies.get('session');\n * if (!session) redirect('/login');\n * // session is defined below this line\n * ```\n */\nexport function redirect(location: string, status: RedirectStatus = 303): never {\n  throw new RedirectSignal(location, status);\n}\n\n/**\n * Aborts the current render with a 404, rendering the app's not-found page.\n *\n * Like {@link redirect}, this throws a control signal and never returns, so\n * TypeScript narrows away everything after the call. Do not catch-and-swallow it.\n *\n * @example\n * ```tsx\n * export default async function Page({ params }: PageProps<'/users/:id'>) {\n *   const user = await db.user.find(params.id);\n *   if (!user) notFound();\n *   return <Profile user={user} />; // user is non-null here\n * }\n * ```\n */\nexport function notFound(): never {\n  throw new NotFoundSignal();\n}\n\n/**\n * Which stage of a request produced an error handed to an {@link ServerErrorHandler}.\n *\n * - `action` — a `'use server'` function threw. React sends the client an opaque marker with no\n *   message in production, so this is the only place the real error is visible.\n * - `render` — a server component threw while the flight payload was being produced.\n * - `ssr` — SSR failed before the HTML shell could be sent, so the `error` page was unreachable too.\n * - `request` — anything else that reached the top-level handler, including a thrown endpoint route.\n */\nexport type ServerErrorSource = 'action' | 'render' | 'ssr' | 'request';\n\n/** What an {@link ServerErrorHandler} is told about an error, beyond the error itself. */\nexport interface ServerErrorContext {\n  /** The stage that produced it — see {@link ServerErrorSource}. */\n  source: ServerErrorSource;\n  /** The request being served, for the URL, method and headers. */\n  request: Request;\n}\n\n/** Handler registered with {@link onServerError}. Called for the side effect; its return value is ignored. */\nexport type ServerErrorHandler = (error: unknown, context: ServerErrorContext) => void;\n\nlet errorHandler: ServerErrorHandler | undefined;\n\n/**\n * Registers a handler for every error the framework catches, so they can reach an error tracker\n * (Sentry, Datadog, a log pipeline) instead of only `stderr`.\n *\n * Call it **once, at the top level of `src/server.ts`** — that module is imported as the server\n * starts, before any request is served. Registering again replaces the previous handler.\n *\n * Errors are still written to `stderr` either way, so a handler adds a destination rather than\n * replacing one. A handler that throws is caught and logged: reporting must never be able to fail\n * a request.\n *\n * @example\n * ```ts\n * // src/server.ts\n * import * as Sentry from '@sentry/node';\n * import { onServerError } from '@rshono/core/server';\n *\n * onServerError((error, { source, request }) => {\n *   Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });\n * });\n * ```\n */\nexport function onServerError(handler: ServerErrorHandler): void {\n  errorHandler = handler;\n}\n\n/**\n * Logs an error and forwards it to the registered {@link ServerErrorHandler}.\n *\n * Framework internal — the single funnel every caught server-side error goes through, so that\n * adding a reporting destination is one registration rather than a hook per call site.\n *\n * @internal\n */\nexport function reportServerError(error: unknown, info: ServerErrorContext & { message: string }): void {\n  console.error(info.message, error);\n  if (!errorHandler) return;\n  try {\n    errorHandler(error, { source: info.source, request: info.request });\n  } catch (handlerError) {\n    console.error('[rshono] the onServerError handler threw:', handlerError);\n  }\n}\n"]}

package/dist/runtime/entry.client.d.ts

@@ -1,2 +1,6 @@
+declare global {
+    /** The array the payload `<script>` tags `flight-inject.ts` emits push their chunks into. */
+    var __FLIGHT_DATA: Array<string | Uint8Array> | undefined;
+}
 export {};
 //# sourceMappingURL=entry.client.d.ts.map

package/dist/runtime/entry.client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry.client.d.ts","sourceRoot":"","sources":["../../src/runtime/entry.client.tsx"],"names":[],"mappings":""}
+{"version":3,"file":"entry.client.d.ts","sourceRoot":"","sources":["../../src/runtime/entry.client.tsx"],"names":[],"mappings":"AAiBA,OAAO,CAAC,MAAM,CAAC;IACb,6FAA6F;IAC7F,IAAI,aAAa,EAAE,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,GAAG,SAAS,CAAC;CAC3D"}