@real-router/rsc-server-plugin 0.2.1 → 0.2.3

package/src/getSsrRscMode.ts

@@ -1,41 +0,0 @@
-import { ALLOWED_RSC_MODES } from "./constants";
-
-import type { RscSsrMode } from "./types";
-import type { State } from "@real-router/types";
-
-/**
- * Returns the SSR mode resolved by `rsc-server-plugin` for the current state.
- * Falls back to `"full"` when the route has no plugin entry.
- *
- * Read this from `entry-server.tsx` to branch on full vs client-only:
- * - `"full"` — render the Server Component tree, pipe Flight stream.
- * - `"client-only"` — ship shell HTML and let the client fetch via its own mechanism.
- *
- * The mode is written to `state.context.ssrRscMode` by the plugin's `start`
- * interceptor for every route registered in the loaders map.
- *
- * Defensive read: if `state.context.ssrRscMode` was set to something outside
- * `ALLOWED_RSC_MODES` by a TS-cast bypass or a foreign writer, the function
- * collapses it to `"full"` rather than returning the bad value. Without this
- * guard, a downstream `mode === "full"` branch would silently misbehave for
- * `0`, `false`, `""`, `null`, or any unknown string.
- *
- * The read itself is wrapped in `try/catch` — a foreign writer that installs
- * a throwing getter (`Object.defineProperty(ctx, "ssrRscMode", { get() { throw … } })`)
- * cannot break the contract. The function NEVER throws, no matter how
- * adversarial the context shape. `"full"` is the safe default for any error.
- */
-export function getSsrRscMode(state: State): RscSsrMode {
-  let raw: unknown;
-
-  try {
-    raw = (state.context as { ssrRscMode?: unknown }).ssrRscMode;
-  } catch {
-    return "full";
-  }
-
-  return typeof raw === "string" &&
-    ALLOWED_RSC_MODES.includes(raw as RscSsrMode)
-    ? (raw as RscSsrMode)
-    : "full";
-}

package/src/index.ts

@@ -1,28 +0,0 @@
-export type {
-  RscActionResult,
-  RscLoaderFn,
-  RscLoaderFactoryMap,
-  RscLoaderFnFactory,
-  RscPayload,
-  RscRouteEntry,
-  RscSsrMode,
-  SsrLoaderContext,
-} from "./types";
-
-export { rscServerPluginFactory } from "./factory";
-
-export { rscActionPluginFactory } from "./actionFactory";
-
-export { buildRscPayload } from "./buildRscPayload";
-
-export { getSsrRscMode } from "./getSsrRscMode";
-
-export { invalidate } from "./invalidate";
-
-declare module "@real-router/types" {
-  interface StateContext {
-    rsc?: import("react").ReactNode;
-    rscAction?: import("./types").RscActionResult;
-    ssrRscMode?: import("./types").RscSsrMode;
-  }
-}

package/src/invalidate.ts

@@ -1,36 +0,0 @@
-import { markStale } from "./shared-ssr";
-
-import type { Router } from "@real-router/types";
-
-/**
- * Mark the `"rsc"` namespace as stale on the given router. The next
- * navigation (including a same-route reload) re-runs the RSC loader for the
- * destination route and overwrites `state.context.rsc` (and the mode marker)
- * via the plugin's `subscribeLeave` listener.
- *
- * Honest fire-and-forget semantics — returns `void`. The flag is consumed in
- * the awaited LEAVE_APPROVE phase of the next navigation, so subscribers see
- * a fresh `ReactNode` when the navigation completes. Behaviour during an
- * in-flight transition: the current transition completes unchanged; the flag
- * is read by the *following* navigation. This keeps the invariant
- * "one transition = one `state.context` snapshot" intact.
- *
- * Composability through the existing core API:
- *
- * ```ts
- * // 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 });
- * ```
- *
- * Surgical alternative to `router.navigate({ reload: true })` for multi-
- * namespace routes: only the `"rsc"` namespace re-runs; a side-by-side
- * `ssr-data-plugin` keeps its cached `state.context.data` on this transition
- * unless its own `invalidate()` was also called.
- */
-export function invalidate(router: Router, namespace: "rsc"): void {
-  markStale(router, namespace);
-}

package/src/types.ts

@@ -1,122 +0,0 @@
-import type {
-  SsrLoaderFn,
-  SsrLoaderFnFactory,
-  SsrMode,
-  SsrRouteEntry,
-} from "./shared-ssr";
-import type { DefaultDependencies } from "@real-router/types";
-import type { ReactNode } from "react";
-
-export { type SsrLoaderContext } from "./shared-ssr";
-
-/**
- * SSR mode subset supported by `rsc-server-plugin`.
- *
- * `"data-only"` is intentionally excluded — RSC has no concept of "data
- * without component" (the Flight payload IS the data + component). Using
- * `"data-only"` with `rscServerPluginFactory` is a configuration error and
- * is rejected at factory time.
- */
-export type RscSsrMode = Exclude<SsrMode, "data-only">;
-
-/**
- * Compiled RSC loader signature.
- *
- * Receives the resolved route's `params` and returns a `ReactNode` (a Server
- * Component element, sync or async). Synchronous return is permitted because
- * many Server Components are synchronous — wrapping them in `Promise.resolve`
- * would be ceremonial.
- */
-export type RscLoaderFn = SsrLoaderFn<ReactNode>;
-
-/**
- * Factory function for creating RSC loaders.
- *
- * Receives the router instance and a dependency getter (same pattern as
- * `DataLoaderFnFactory`/`GuardFnFactory`). Factory runs once at
- * `usePlugin()` time; the returned loader is cached.
- *
- * @template Dependencies - Router dependency map for typed `getDependency()`.
- *   Defaults to `DefaultDependencies`. Pass your app's dependency interface
- *   for type-safe DI: `RscLoaderFnFactory<AppDependencies>`.
- */
-export type RscLoaderFnFactory<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> = SsrLoaderFnFactory<ReactNode, Dependencies>;
-
-/**
- * Per-route entry: either a loader factory (short form) or
- * `{ ssr?, loader? }` object form. Mode defaults to `"full"`.
- *
- * Allowed `ssr` values for RSC: `"full"` | `"client-only"` (and the
- * `true` / `false` aliases). `"data-only"` is rejected at factory time.
- *
- * Function form `(state) => RscSsrMode` is resolved per-navigation,
- * **before** the mode is written to context.
- */
-export type RscRouteEntry<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> = SsrRouteEntry<ReactNode, RscSsrMode, Dependencies>;
-
-/**
- * Map of route name → entry (factory or `{ ssr?, loader? }`).
- *
- * Pass to `rscServerPluginFactory()`. Keys are route names (e.g. `"users.profile"`);
- * values are factory or object-form route entries.
- */
-export type RscLoaderFactoryMap<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> = Record<string, RscRouteEntry<Dependencies>>;
-
-/**
- * Server Action result published by `rscActionPluginFactory` to
- * `state.context.rscAction`. Consumers read either field at render
- * time. Both are optional — typical flows write one or the other:
- *
- * - `returnValue` — set when the action was invoked via the hydrated
- *   client path (`setServerCallback` → `loadServerAction` →
- *   `decodeReply` in the RSC entry). Threaded back into
- *   `useActionState` on the client.
- * - `formState` — set when the action was invoked via progressive
- *   enhancement (`<form action={fn}>` POST without JS) and decoded
- *   via `decodeAction(formData)` + `decodeFormState(result, formData)`.
- *
- * Both type parameters default to `unknown` to keep the plugin
- * runtime-only — consumers narrow them at the call site.
- */
-export interface RscActionResult<TReturn = unknown, TFormState = unknown> {
-  returnValue?: { ok: boolean; data: TReturn };
-  formState?: TFormState;
-}
-
-/**
- * Canonical Flight payload shape for RSC apps that ship Server Actions.
- *
- * The pipeline serializes this object via the bundler's RSC stream
- * renderer (e.g. `@vitejs/plugin-rsc/rsc.renderToReadableStream`); the
- * SSR + browser entries deserialize the same shape and thread
- * `returnValue`/`formState` into `useActionState`.
- *
- * Apps without Server Actions can use `RscPayload` with all generics
- * defaulted, or just type their payload as `{ root: ReactNode }`.
- *
- * Type parameters:
- * - `TReturn` — narrowed shape of `returnValue.data` (e.g. mutation
- *   confirmation). Defaults to `unknown`.
- * - `TFormState` — narrowed shape of `formState`. Defaults to
- *   `unknown` so the plugin stays free of `react-dom/client` import
- *   (which carries the canonical `ReactFormState` type). Consumers
- *   narrow at call site:
- *
- *   ```ts
- *   import type { ReactFormState } from "react-dom/client";
- *   type AppPayload = RscPayload<{ id: string }, ReactFormState>;
- *   ```
- */
-export interface RscPayload<
-  TReturn = unknown,
-  TFormState = unknown,
-> extends RscActionResult<TReturn, TFormState> {
-  /** Server Component tree to render. */
-  root: ReactNode;
-}