@real-router/rsc-server-plugin 0.1.0

package/README.md

@@ -0,0 +1,338 @@
+# @real-router/rsc-server-plugin
+
+[![npm](https://img.shields.io/npm/v/@real-router/rsc-server-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/rsc-server-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/@real-router/rsc-server-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/rsc-server-plugin)
+[![bundle size](https://deno.bundlejs.com/?q=@real-router/rsc-server-plugin&treeshake=[*]&badge=detailed)](https://bundlejs.com/?q=@real-router/rsc-server-plugin&treeshake=[*])
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE)
+
+> Per-route `ReactNode` (RSC payload) loading for [Real-Router](https://github.com/greydragon888/real-router). Intercepts `start()` to load Server Components before Flight rendering. **Bundler-agnostic** — the plugin **never imports** a Flight renderer; the caller picks one of `@vitejs/plugin-rsc`, `react-server-dom-webpack`, `react-server-dom-turbopack`, or `react-server-dom-parcel`. Examples in this README and in the [wiki](https://github.com/greydragon888/real-router/wiki/RSC-Integration) use the Vite import path (`@vitejs/plugin-rsc/rsc`); other bundlers expose the same `renderToReadableStream` shape under their own paths (`react-server-dom-webpack/server.edge`, `react-server-dom-turbopack/server`, `react-server-dom-parcel/server`) — swap the import, keep the call site.
+
+```typescript
+// Without plugin: manual per-route Server Component dispatch
+const state = await router.start(url);
+const node = await getNodeForRoute(state.name, state.params); // manual
+
+// With plugin:
+router.usePlugin(rscServerPluginFactory(loaders));
+const state = await router.start(url);
+const node = state.context.rsc; // resolved automatically
+```
+
+## Installation
+
+```bash
+npm install @real-router/rsc-server-plugin
+```
+
+**Peer dependencies:** `@real-router/core`, `react` (>=19.0.0). No bundler dependency — the caller picks the Flight renderer.
+
+## Quick Start
+
+```typescript
+import { createRouter } from "@real-router/core";
+import { cloneRouter } from "@real-router/core/api";
+import { serializeRouterState } from "@real-router/core/utils";
+import { rscServerPluginFactory } from "@real-router/rsc-server-plugin";
+import type { RscLoaderFactoryMap } from "@real-router/rsc-server-plugin";
+import { renderToReadableStream } from "@vitejs/plugin-rsc/rsc";
+
+const loaders: RscLoaderFactoryMap = {
+  "users.profile": () => async (params) => {
+    const user = await fetchUser(params.id);
+    return <UserProfile user={user} />;
+  },
+  home: () => () => <HomePage />,
+};
+
+const baseRouter = createRouter(routes, { defaultRoute: "home", allowNotFound: true });
+
+// Per-request SSR
+const router = cloneRouter(baseRouter, { db: requestDb });
+router.usePlugin(rscServerPluginFactory(loaders));
+
+const state = await router.start(req.url);
+
+// 1) Pipe RSC Flight payload (the bundler-specific renderer is *yours*)
+if (state.context.rsc) {
+  const flightStream = renderToReadableStream(state.context.rsc);
+  // … pipe to HTTP response or inline-inject into HTML
+}
+
+// 2) Serialize state for client hydration — strip "rsc" (not JSON-serializable)
+const ssrState = serializeRouterState(state, { excludeContext: ["rsc"] });
+
+router.dispose();
+```
+
+## Configuration
+
+Loaders are keyed by **route name** (not path). Each value is a **factory function** `(router, getDependency) => loaderFn` returning the compiled loader. The factory runs once at plugin registration; the returned loader is cached.
+
+```typescript
+import type { RscLoaderFactoryMap } from "@real-router/rsc-server-plugin";
+
+const loaders: RscLoaderFactoryMap = {
+  home: () => () => <HomePage />,                         // sync ReactNode
+  "users.profile": () => async (params) => {              // async ReactNode
+    const user = await fetchUser(params.id);
+    return <UserProfile user={user} />;
+  },
+  "posts.list": (_router, getDep) => async () => {        // DI via getDependency
+    const db = getDep("db");
+    const posts = await db.posts.findAll();
+    return <PostsList posts={posts} />;
+  },
+};
+```
+
+Routes without a matching entry leave `state.context.rsc` as `undefined` and `getSsrRscMode(state)` falls back to `"full"`.
+
+## Per-route SSR mode
+
+`rsc-server-plugin` accepts the same `{ ssr?, loader? }` shape as `ssr-data-plugin`, but with a strict subset of `SsrMode`: only `"full"` and `"client-only"` are allowed. Passing `"data-only"` (RSC has no semantically meaningful "data without component") throws at factory time.
+
+```typescript
+const loaders: RscLoaderFactoryMap = {
+  home: () => () => <HomePage />,                                 // short form, defaults to "full"
+  "admin.dashboard": { ssr: false },                              // false → "client-only"
+  "docs.detail": {
+    ssr: (state) => state.params.format === "pdf" ? "client-only" : "full",
+    loader: () => () => <Doc />,
+  },
+};
+```
+
+| `ssr` value                  | mode marker       | loader behaviour          |
+| ---------------------------- | ----------------- | ------------------------- |
+| omitted / `true` / `"full"`  | `"full"`          | runs (composes with #596) |
+| `false` / `"client-only"`    | `"client-only"`   | **skipped** unconditionally |
+| `(state) => RscSsrMode`      | resolver result   | resolved per-navigation   |
+
+Read the resolved mode via `getSsrRscMode(state)` (returns `"full"` for routes without an entry):
+
+```typescript
+import { getSsrRscMode } from "@real-router/rsc-server-plugin";
+
+const mode = getSsrRscMode(state); // RscSsrMode = "full" | "client-only"
+
+if (mode === "full") {
+  const flight = renderToReadableStream(buildRscPayload(state));
+  // … pipe Flight + SSR HTML
+}
+// mode === "client-only" → no Server Component was rendered server-side
+```
+
+## Why `ReactNode`, not Flight bytes?
+
+The plugin publishes a `ReactNode`, not a pre-rendered Flight `Uint8Array`. This keeps the plugin:
+
+- **Bundler-agnostic** — `react-server-dom-{webpack,turbopack,parcel,esm}` have incompatible `renderToReadableStream` signatures; the caller picks the right one
+- **Streaming-friendly** — Flight rendering happens out-of-band, in parallel with HTML SSR
+- **Aligned with industry** — both React Router 7 (`unstable_RSCStaticRouter`) and TanStack Start (`renderServerComponent`) use the same model
+
+The Flight render itself is one line:
+
+```typescript
+const flight = renderToReadableStream(state.context.rsc);
+```
+
+## Serialization
+
+`state.context.rsc` is a `ReactNode` tree (functions, symbols) and cannot be JSON-serialized. Use `serializeRouterState`'s `excludeContext` option to strip it before client transport:
+
+```typescript
+import { serializeRouterState } from "@real-router/core/utils";
+
+const ssrJson = serializeRouterState(state, { excludeContext: ["rsc"] });
+// JSON contains state.context.data and other namespaces, but not state.context.rsc
+```
+
+## SSR-Only by Design (with explicit CSR revalidation channel)
+
+This plugin intercepts `start()` only — not `navigate()`. In SSR, the flow is:
+
+```
+cloneRouter → usePlugin → start(url) → ReactNode resolved → state.context.rsc
+                                                                    ↓
+                                                  renderToReadableStream(node)
+                                                                    ↓
+                                                          Flight stream → HTTP
+```
+
+Client-side navigation does **not** re-run the RSC loader by default — application-layer fetching (React Query, Suspense, RSC `/__rsc` endpoint) owns CSR data. The one explicit exception is the `invalidate()` revalidation channel below.
+
+## Client-side revalidation (`invalidate`)
+
+After a mutation, mark the `"rsc"` namespace stale on the router. The next navigation (including a same-route reload) re-runs the RSC loader for the destination route and overwrites `state.context.rsc` before `TRANSITION_SUCCESS` fires — so subscribers see the fresh `ReactNode`.
+
+```typescript
+import { invalidate } from "@real-router/rsc-server-plugin";
+
+// Fire-and-forget — stale until the user navigates somewhere.
+invalidate(router, "rsc");
+
+// Explicit await — pair with a same-route reload.
+invalidate(router, "rsc");
+await router.navigate(state.name, state.params, { reload: true });
+```
+
+The flag is **preserved** until a successful, non-cancelled loader write. So a navigation that lands on a route without an entry, a `client-only` route, a mode-only entry, or one that gets cancelled mid-loader (newer `navigate()` aborts the older controller) all leave the flag set for the next attempt. A loader rejection also leaves the flag set — retry re-runs the loader.
+
+Idempotent — multiple `invalidate()` calls between refreshes collapse to one re-run. Surgical for multi-namespace routes — only `"rsc"` re-runs; a side-by-side [`@real-router/ssr-data-plugin`](https://www.npmjs.com/package/@real-router/ssr-data-plugin) keeps its cached `state.context.data` unless its own `invalidate()` was also called.
+
+### Cancellation-aware loaders
+
+The leave handler passes the navigation's `AbortController.signal` as the second loader argument so loaders can abort their in-flight work (DB query, RSC stream, …) when a newer navigation supersedes:
+
+```typescript
+"users.profile": (_router, getDep) => async (params, ctx) => {
+  const db = getDep("db");
+  const user = await db.users.findById(params.id, { signal: ctx?.signal });
+
+  return <UserProfile user={user} />;
+},
+```
+
+The start interceptor calls the loader without a context. **Robust loaders check `signal.aborted` upfront** — a signal aborted before `addEventListener("abort", …)` does NOT auto-fire the listener.
+
+Non-breaking via TypeScript contravariance — existing `(params) => …` loaders continue to compile and work unchanged.
+
+## Post-hydration loader skip
+
+When the application uses `hydrateRouter()` from `@real-router/core/utils`, the parsed server-serialized state is briefly deposited on a one-shot internal scratchpad before `start()` runs. The plugin reads this scratchpad and **reuses the server-resolved value** if `state.context.rsc` is already present for the same route name — skipping the redundant client-side `ReactNode` resolution on first paint.
+
+In practice, RSC apps usually `excludeContext: ["rsc"]` from the JSON payload (a `ReactNode` tree contains functions/symbols and isn't JSON-serializable). In that case the scratchpad has no `rsc` namespace and the loader runs as today. The skip path matters when the bundler-specific Flight pipeline arranges to thread an already-resolved `ReactNode` through hydration.
+
+The skip is single-shot — only the first `start()` triggered by `hydrateRouter` consumes the scratchpad. Composes with per-route mode: `"client-only"` skips the loader regardless of scratchpad contents (mode wins).
+
+## Typed Loader Errors (`@real-router/rsc-server-plugin/errors`)
+
+Mirror of [`@real-router/ssr-data-plugin/errors`](../ssr-data-plugin/README.md#typed-loader-errors-real-routerssr-data-pluginerrors) — same shared source under `shared/ssr/errors.ts`. RSC apps can import error classes without adding `ssr-data-plugin` as a dependency:
+
+```typescript
+import {
+  LoaderNotFound,
+  LoaderRedirect,
+} from "@real-router/rsc-server-plugin/errors";
+
+const loaders: RscLoaderFactoryMap = {
+  "users.profile": (_router, getDep) => async (params) => {
+    const user = await getDep("db").users.findById(params.id);
+    if (!user) throw new LoaderNotFound(`user:${params.id}`);
+    return <UserProfile user={user} />;
+  },
+};
+
+// In the RSC fetch handler:
+try {
+  const state = await router.start(pathname);
+  return new Response(renderToReadableStream(buildRscPayload(state)));
+} catch (error) {
+  if (error?.code === "LOADER_NOT_FOUND") {
+    return new Response("Not Found", { status: 404 });
+  }
+  throw error;
+}
+```
+
+`LoaderNotFound`, `LoaderRedirect`, `LoaderTimeout`, `withTimeout` — same shape and structural `code` discriminator as the data-plugin counterparts.
+
+## Cleanup
+
+```typescript
+const unsubscribe = router.usePlugin(rscServerPluginFactory(loaders));
+
+// Later — releases "rsc" namespace claim and stops the start interceptor
+unsubscribe();
+```
+
+In SSR, `router.dispose()` handles cleanup automatically.
+
+## Server Actions (`rscActionPluginFactory`)
+
+For RSC apps that ship Server Actions, this package also exports a **second factory** — `rscActionPluginFactory(getResult)` — that publishes the action result (`returnValue` / `formState`) to `state.context.rscAction`. It claims a separate `"rscAction"` namespace, so it composes with `rscServerPluginFactory` and `ssr-data-plugin` on the same router. Action results are produced *outside* the loader pipeline (typically in the request fetch handler, before the router exists for that request), so they're surfaced via a closure-captured resolver rather than a per-route map.
+
+```typescript
+import {
+  buildRscPayload,
+  rscActionPluginFactory,
+  rscServerPluginFactory,
+  type RscActionResult,
+} from "@real-router/rsc-server-plugin";
+// Vite path — swap for `react-server-dom-{webpack,turbopack,parcel}/server.*`
+// when you use a different bundler. The plugin itself imports nothing here.
+import {
+  decodeAction,
+  decodeFormState,
+  decodeReply,
+  loadServerAction,
+  renderToReadableStream,
+} from "@vitejs/plugin-rsc/rsc";
+
+let actionResult: RscActionResult | undefined;
+
+if (request.method === "POST") {
+  const isFormPost = request.headers
+    .get("content-type")
+    ?.includes("multipart/form-data");
+
+  if (isFormPost) {
+    // Progressive enhancement path — POST without JS.
+    const formData = await request.formData();
+    const decoded = await decodeAction(formData);
+    const result = await decoded();
+    const formState = await decodeFormState(result, formData);
+
+    actionResult = formState ? { formState } : undefined;
+  } else {
+    // Hydrated client path — setServerCallback dispatched the call.
+    const actionId = request.headers.get("rsc-action") ?? "";
+    const fn = await loadServerAction(actionId);
+    const args = await decodeReply(await request.text());
+
+    actionResult = { returnValue: { ok: true, data: await fn(...args) } };
+  }
+}
+
+const router = cloneRouter(baseRouter, requestDeps);
+
+router.usePlugin(
+  rscServerPluginFactory(loaders),
+  rscActionPluginFactory(() => actionResult), // closure captures live mutation
+);
+
+const state = await router.start(new URL(request.url).pathname);
+const flight = renderToReadableStream(buildRscPayload(state));
+```
+
+Rules:
+
+- `getResult` is **validated at factory time** as a function — a TS-cast bypass that smuggles `null`/`async` through throws `TypeError` synchronously, **before** the `"rscAction"` namespace is claimed.
+- The return value is **validated per `start()`** — must be `undefined` (skip the write) or a plain object. Arrays, primitives, and `Promise`/thenables are rejected with a typed message pointing back at the call site. The most common consumer mistake is wiring an `async` getResult; the runtime guard surfaces that explicitly.
+- `state.context.rscAction` is **JSON-friendly** — `serializeRouterState(state)` works without `excludeContext`. Pass `excludeContext: ["rsc", "rscAction"]` only if the result carries server-only secrets you don't want to ship to the client.
+- The two plugins coexist regardless of registration order; both namespaces are exclusive (double-registration throws `RouterError(CONTEXT_NAMESPACE_ALREADY_CLAIMED)`).
+- `buildRscPayload(state, rootOverride?)` reads `state.context.rsc` + `state.context.rscAction` and returns the canonical `RscPayload<TReturn, TFormState>` Flight shape. `returnValue` / `formState` are **omitted** (not set to `undefined`) when their source is missing — type-safe under `exactOptionalPropertyTypes: true`.
+
+For the full integration recipe (HTML + `/__rsc` endpoints, dev/prod bundler config, Flight injection), see the [Wiki: RSC Integration](https://github.com/greydragon888/real-router/wiki/RSC-Integration) guide.
+
+## Example
+
+- [examples/web/react/ssr-examples/ssr-rsc](../../examples/web/react/ssr-examples/ssr-rsc) — End-to-end dogfooding example: Express + `@vitejs/plugin-rsc` + this plugin, with Flight injection, client navigation via `/__rsc?route=…`, revalidation, and **Server Actions** wired through `rscActionPluginFactory` (see `entry.rsc.tsx` + `NotificationBanner.tsx`). The Playwright suite covers **27 scenarios** including initial HTML load, client nav, revalidation **happy path + in-flight defer** (Scenarios 3 + 3b), 404 routing, per-request isolation under concurrent load, `/__rsc` content-type assertions, loader-driven HTTP status (404/500), search-param flow, browser back/forward, interleaved-click abort, per-route Cache-Control, ETag absence on streamed responses, and the full Server Action lifecycle (form rendering, mutation, `useActionState` validation errors, `NotificationBanner` cross-component reflection via `state.context.rscAction`). `RevalidateButton` calls `invalidate(router, "rsc")` for API symmetry — see [`src/client-components/RevalidateButton.tsx`](../../examples/web/react/ssr-examples/ssr-rsc/src/client-components/RevalidateButton.tsx).
+
+## Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — Design decisions and data flow
+- [INVARIANTS.md](INVARIANTS.md) — Property-based invariants
+- [Wiki: RSC Integration](https://github.com/greydragon888/real-router/wiki/RSC-Integration) — End-to-end integration guide
+
+## Related Packages
+
+| Package                                                                                     | Description                                              |
+| ------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| [@real-router/core](https://www.npmjs.com/package/@real-router/core)                        | Core router (required peer dependency)                   |
+| [@real-router/ssr-data-plugin](https://www.npmjs.com/package/@real-router/ssr-data-plugin)  | Sibling plugin for plain JSON data (`state.context.data`) |
+| [@real-router/react](https://www.npmjs.com/package/@real-router/react)                      | React bindings                                           |
+
+## License
+
+[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/errors.d.ts

@@ -0,0 +1,97 @@
+//#region ../../shared/ssr/errors.d.ts
+/**
+ * Typed loader errors that SSR pipelines translate into HTTP semantics.
+ *
+ * The `ssr-data-plugin` and `rsc-server-plugin` are intentionally
+ * HTTP-agnostic — they only await the loader and write the resolved value
+ * to `state.context.<namespace>`. Loaders bridge to HTTP status codes by
+ * throwing one of these named errors; application-layer middleware catches
+ * them and maps each `code` to the right status (302/308, 404, 504).
+ *
+ * Structural discrimination via `code` (not `instanceof`) so consumers
+ * can match across realms / bundle boundaries without coupling to the
+ * class identity.
+ *
+ * Re-exported from both plugins under the `./errors` subpath:
+ * `@real-router/ssr-data-plugin/errors` and
+ * `@real-router/rsc-server-plugin/errors`.
+ */
+declare class LoaderRedirect extends Error {
+  readonly target: string;
+  readonly status: 301 | 302 | 307 | 308;
+  readonly code = "LOADER_REDIRECT";
+  constructor(target: string, status?: 301 | 302 | 307 | 308);
+}
+declare class LoaderNotFound extends Error {
+  readonly resource: string;
+  readonly code = "LOADER_NOT_FOUND";
+  constructor(resource: string);
+}
+declare class LoaderTimeout extends Error {
+  readonly route: string;
+  readonly ms: number;
+  readonly code = "LOADER_TIMEOUT";
+  constructor(route: string, ms: number);
+}
+/**
+ * Race a loader against a deadline, with cooperative cancellation.
+ *
+ * The loader is invoked with `{ signal }` — a composed `AbortSignal` that
+ * aborts on the first of:
+ * - the deadline elapsing (`internalController.abort()` fires synchronously
+ *   *before* the race rejects with `LoaderTimeout`, so a loader that
+ *   threads `signal` into its I/O — e.g. `fetch(url, { signal })` — can
+ *   actually cancel the underlying work);
+ * - `options.upstreamSignal` aborting (typically the request-scoped abort
+ *   wired by `cloneRouter(base, { abortSignal })` for client-disconnect).
+ *
+ * Composition uses `AbortSignal.any([upstream, internal])` (Node 20.3+).
+ * If `upstreamSignal` is already aborted at call time, the loader is *not*
+ * invoked and the timer is *not* started — the rejection mirrors
+ * `upstreamSignal.reason ?? new DOMException("Aborted", "AbortError")`.
+ *
+ * On deadline, the same `LoaderTimeout` instance is used as both the
+ * `signal.reason` and the rejection reason — they refer to one object.
+ * On upstream abort during execution, the race rejects with the loader's
+ * own error (typically `AbortError`), *not* `LoaderTimeout`.
+ *
+ * Cancellation is cooperative: loaders that don't propagate `signal` into
+ * their I/O still run to completion in the background — the race result
+ * is unaffected, but resources are not freed early.
+ *
+ * The `setTimeout` handle is cleared via `.finally()` on the work promise
+ * so a fast-path success doesn't leak it. `Promise.race`'s internal
+ * `Promise.resolve(p).then(resolve, reject)` consumes any late losing
+ * rejection — no `unhandledRejection` for late loader settlements.
+ *
+ * Requires Node 20.3+ for `AbortSignal.any`.
+ *
+ * ### `ms` corner cases (Node `setTimeout` clamping)
+ *
+ * `ms` is forwarded verbatim to `setTimeout`, which means `Infinity`, `NaN`,
+ * and negative values are **NOT** safe sentinels for "no deadline":
+ *
+ * - `withTimeout("r", Infinity, …)` — Node clamps to `1` ms and emits a
+ *   `TimeoutOverflowWarning`. The race rejects with `LoaderTimeout` after
+ *   1 ms, not "never". Use a separate code path (e.g. invoke the loader
+ *   directly without wrapping) when you genuinely want no deadline.
+ * - `withTimeout("r", NaN, …)` — same: Node clamps to `1` ms with a
+ *   warning.
+ * - `withTimeout("r", -1, …)` — Node clamps to `1` ms with a warning.
+ * - `withTimeout("r", 0, …)` — fires on the next tick. A synchronous-
+ *   resolving loader (`() => Promise.resolve(v)`) typically wins the race,
+ *   but any async I/O loses. Treat `0` as "fire immediately" rather than
+ *   "no deadline".
+ *
+ * No runtime guard is added — the clamping is a Node-level concern and
+ * adding `if (!Number.isFinite(ms) || ms < 0) throw` would be a breaking
+ * change for callers relying on the current clamp semantics.
+ */
+declare function withTimeout<T>(routeName: string, ms: number, loader: (deps: {
+  signal: AbortSignal;
+}) => Promise<T>, options?: {
+  upstreamSignal?: AbortSignal | null;
+}): Promise<T>;
+//#endregion
+export { LoaderNotFound, LoaderRedirect, LoaderTimeout, withTimeout };
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../../../../shared/ssr/errors.ts"],"mappings":";;AAkBA;;;;;;;;;;;;;AAYA;;;cAZa,cAAA,SAAuB,KAAA;EAAA,SAIvB,MAAA;EAAA,SACA,MAAA;EAAA,SAJF,IAAA;cAGE,MAAA,UACA,MAAA;AAAA;AAAA,cAOA,cAAA,SAAuB,KAAA;EAAA,SAGb,QAAA;EAAA,SAFZ,IAAA;cAEY,QAAA;AAAA;AAAA,cAMV,aAAA,SAAsB,KAAA;EAAA,SAItB,KAAA;EAAA,SACA,EAAA;EAAA,SAJF,IAAA;cAGE,KAAA,UACA,EAAA;AAAA;;;;;AA6Db;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,WAAA,GAAA,CACd,SAAA,UACA,EAAA,UACA,MAAA,GAAS,IAAA;EAAQ,MAAA,EAAQ,WAAA;AAAA,MAAkB,OAAA,CAAQ,CAAA,GACnD,OAAA;EAAY,cAAA,GAAiB,WAAA;AAAA,IAC5B,OAAA,CAAQ,CAAA"}

package/dist/cjs/errors.js

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class extends Error{code=`LOADER_REDIRECT`;constructor(e,t=302){super(`Redirect to ${e}`),this.target=e,this.status=t,this.name=`LoaderRedirect`}},t=class extends Error{code=`LOADER_NOT_FOUND`;constructor(e){super(`Resource not found: ${e}`),this.resource=e,this.name=`LoaderNotFound`}},n=class extends Error{code=`LOADER_TIMEOUT`;constructor(e,t){super(`Loader for "${e}" exceeded ${t}ms`),this.route=e,this.ms=t,this.name=`LoaderTimeout`}};function r(e,t,r,i){let a=i?.upstreamSignal;if(a?.aborted)return Promise.reject(a.reason??new DOMException(`The operation was aborted.`,`AbortError`));let o=new AbortController,s=a?AbortSignal.any([a,o.signal]):o.signal,c,l=new Promise((r,i)=>{c=setTimeout(()=>{let r=new n(e,t);o.abort(r),i(r)},t)}),u=(async()=>r({signal:s}))().finally(()=>{c!==void 0&&clearTimeout(c)});return Promise.race([u,l])}exports.LoaderNotFound=t,exports.LoaderRedirect=e,exports.LoaderTimeout=n,exports.withTimeout=r;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../../../shared/ssr/errors.ts"],"sourcesContent":["/**\n * Typed loader errors that SSR pipelines translate into HTTP semantics.\n *\n * The `ssr-data-plugin` and `rsc-server-plugin` are intentionally\n * HTTP-agnostic — they only await the loader and write the resolved value\n * to `state.context.<namespace>`. Loaders bridge to HTTP status codes by\n * throwing one of these named errors; application-layer middleware catches\n * them and maps each `code` to the right status (302/308, 404, 504).\n *\n * Structural discrimination via `code` (not `instanceof`) so consumers\n * can match across realms / bundle boundaries without coupling to the\n * class identity.\n *\n * Re-exported from both plugins under the `./errors` subpath:\n * `@real-router/ssr-data-plugin/errors` and\n * `@real-router/rsc-server-plugin/errors`.\n */\n\nexport class LoaderRedirect extends Error {\n  readonly code = \"LOADER_REDIRECT\";\n\n  constructor(\n    readonly target: string,\n    readonly status: 301 | 302 | 307 | 308 = 302,\n  ) {\n    super(`Redirect to ${target}`);\n    this.name = \"LoaderRedirect\";\n  }\n}\n\nexport class LoaderNotFound extends Error {\n  readonly code = \"LOADER_NOT_FOUND\";\n\n  constructor(readonly resource: string) {\n    super(`Resource not found: ${resource}`);\n    this.name = \"LoaderNotFound\";\n  }\n}\n\nexport class LoaderTimeout extends Error {\n  readonly code = \"LOADER_TIMEOUT\";\n\n  constructor(\n    readonly route: string,\n    readonly ms: number,\n  ) {\n    super(`Loader for \"${route}\" exceeded ${ms}ms`);\n    this.name = \"LoaderTimeout\";\n  }\n}\n\n/**\n * Race a loader against a deadline, with cooperative cancellation.\n *\n * The loader is invoked with `{ signal }` — a composed `AbortSignal` that\n * aborts on the first of:\n * - the deadline elapsing (`internalController.abort()` fires synchronously\n *   *before* the race rejects with `LoaderTimeout`, so a loader that\n *   threads `signal` into its I/O — e.g. `fetch(url, { signal })` — can\n *   actually cancel the underlying work);\n * - `options.upstreamSignal` aborting (typically the request-scoped abort\n *   wired by `cloneRouter(base, { abortSignal })` for client-disconnect).\n *\n * Composition uses `AbortSignal.any([upstream, internal])` (Node 20.3+).\n * If `upstreamSignal` is already aborted at call time, the loader is *not*\n * invoked and the timer is *not* started — the rejection mirrors\n * `upstreamSignal.reason ?? new DOMException(\"Aborted\", \"AbortError\")`.\n *\n * On deadline, the same `LoaderTimeout` instance is used as both the\n * `signal.reason` and the rejection reason — they refer to one object.\n * On upstream abort during execution, the race rejects with the loader's\n * own error (typically `AbortError`), *not* `LoaderTimeout`.\n *\n * Cancellation is cooperative: loaders that don't propagate `signal` into\n * their I/O still run to completion in the background — the race result\n * is unaffected, but resources are not freed early.\n *\n * The `setTimeout` handle is cleared via `.finally()` on the work promise\n * so a fast-path success doesn't leak it. `Promise.race`'s internal\n * `Promise.resolve(p).then(resolve, reject)` consumes any late losing\n * rejection — no `unhandledRejection` for late loader settlements.\n *\n * Requires Node 20.3+ for `AbortSignal.any`.\n *\n * ### `ms` corner cases (Node `setTimeout` clamping)\n *\n * `ms` is forwarded verbatim to `setTimeout`, which means `Infinity`, `NaN`,\n * and negative values are **NOT** safe sentinels for \"no deadline\":\n *\n * - `withTimeout(\"r\", Infinity, …)` — Node clamps to `1` ms and emits a\n *   `TimeoutOverflowWarning`. The race rejects with `LoaderTimeout` after\n *   1 ms, not \"never\". Use a separate code path (e.g. invoke the loader\n *   directly without wrapping) when you genuinely want no deadline.\n * - `withTimeout(\"r\", NaN, …)` — same: Node clamps to `1` ms with a\n *   warning.\n * - `withTimeout(\"r\", -1, …)` — Node clamps to `1` ms with a warning.\n * - `withTimeout(\"r\", 0, …)` — fires on the next tick. A synchronous-\n *   resolving loader (`() => Promise.resolve(v)`) typically wins the race,\n *   but any async I/O loses. Treat `0` as \"fire immediately\" rather than\n *   \"no deadline\".\n *\n * No runtime guard is added — the clamping is a Node-level concern and\n * adding `if (!Number.isFinite(ms) || ms < 0) throw` would be a breaking\n * change for callers relying on the current clamp semantics.\n */\nexport function withTimeout<T>(\n  routeName: string,\n  ms: number,\n  loader: (deps: { signal: AbortSignal }) => Promise<T>,\n  options?: { upstreamSignal?: AbortSignal | null },\n): Promise<T> {\n  const upstream = options?.upstreamSignal;\n\n  if (upstream?.aborted) {\n    // `signal.reason` is normally set automatically by the spec\n    // (`controller.abort()` without an argument yields a `DOMException`),\n    // but the field is writable, so we fall back to a fresh `AbortError`\n    // if some caller produced an aborted signal with `reason === undefined`.\n    return Promise.reject(\n      upstream.reason ??\n        new DOMException(\"The operation was aborted.\", \"AbortError\"),\n    );\n  }\n\n  const internal = new AbortController();\n  const composed = upstream\n    ? AbortSignal.any([upstream, internal.signal])\n    : internal.signal;\n\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const timeoutPromise = new Promise<T>((_, reject) => {\n    timer = setTimeout(() => {\n      const error = new LoaderTimeout(routeName, ms);\n      internal.abort(error);\n      reject(error);\n    }, ms);\n  });\n\n  const work = (async () => loader({ signal: composed }))().finally(() => {\n    if (timer !== undefined) clearTimeout(timer);\n  });\n\n  return Promise.race<T>([work, timeoutPromise]);\n}\n"],"mappings":"mEAkBA,IAAa,EAAb,cAAoC,KAAM,CACxC,KAAgB,kBAEhB,YACE,EACA,EAAyC,IACzC,CACA,MAAM,eAAe,IAAS,CAHrB,KAAA,OAAA,EACA,KAAA,OAAA,EAGT,KAAK,KAAO,mBAIH,EAAb,cAAoC,KAAM,CACxC,KAAgB,mBAEhB,YAAY,EAA2B,CACrC,MAAM,uBAAuB,IAAW,CADrB,KAAA,SAAA,EAEnB,KAAK,KAAO,mBAIH,EAAb,cAAmC,KAAM,CACvC,KAAgB,iBAEhB,YACE,EACA,EACA,CACA,MAAM,eAAe,EAAM,aAAa,EAAG,IAAI,CAHtC,KAAA,MAAA,EACA,KAAA,GAAA,EAGT,KAAK,KAAO,kBA0DhB,SAAgB,EACd,EACA,EACA,EACA,EACY,CACZ,IAAM,EAAW,GAAS,eAE1B,GAAI,GAAU,QAKZ,OAAO,QAAQ,OACb,EAAS,QACP,IAAI,aAAa,6BAA8B,aAAa,CAC/D,CAGH,IAAM,EAAW,IAAI,gBACf,EAAW,EACb,YAAY,IAAI,CAAC,EAAU,EAAS,OAAO,CAAC,CAC5C,EAAS,OAET,EACE,EAAiB,IAAI,SAAY,EAAG,IAAW,CACnD,EAAQ,eAAiB,CACvB,IAAM,EAAQ,IAAI,EAAc,EAAW,EAAG,CAC9C,EAAS,MAAM,EAAM,CACrB,EAAO,EAAM,EACZ,EAAG,EACN,CAEI,GAAQ,SAAY,EAAO,CAAE,OAAQ,EAAU,CAAC,GAAG,CAAC,YAAc,CAClE,IAAU,IAAA,IAAW,aAAa,EAAM,EAC5C,CAEF,OAAO,QAAQ,KAAQ,CAAC,EAAM,EAAe,CAAC"}