@rsc-kit/core 0.23.0 → 0.24.0

package/dist/vite.js

@@ -201,6 +201,9 @@ let foundAssets = {
 let hostActions;
 /** What rpc() may be called with, from rsc-host-functions.json; null when the backend lists none. */
 let hostFunctions = null;
+/** The backend's typed signatures, by function name, and the named types they refer to. */
+let hostTypes = {};
+let hostDefs = {};
 /**
  * The manifest commands run in this process, by project and command.
  *
@@ -241,30 +244,8 @@ function envRouteConfig() {
 }
 /** The file a backend writes its action names into. */
 const HOST_FILE = "rsc-host.json";
-/**
- * What the backend offers the app, read from a file it wrote:
- *
- *     {
- *       "actions": { "ordersCreate": "Orders.create" },
- *       "functions": ["Orders.create", "Orders.recent"]
- *     }
- *
- * `actions` are the server actions the build writes "use server" stubs for,
- * by JavaScript name. `functions` are the names rpc() may be called with,
- * which the build turns into a type so a misspelt one fails the typecheck.
- *
- * A file rather than an environment variable, because the backend no longer
- * drives the build - `vite build` does. Discovery has to stay where the code
- * is (reflection through Composer's autoloader finds what a class inherits; a
- * regex would silently miss every inherited action), but the handoff is just
- * names, and a JSON file is something any language can write:
- *
- *     php artisan rsc:host-manifest
- *     go run ./backend -manifest rsc-host.json
- *
- * Absent is not an error: a backend-less app has no file. `hostManifest`
- * runs the command as dev or a build starts.
- */
+/** The "use server" module of the backend's action stubs, written beside the app. */
+const HOST_ACTIONS_MODULE = "server-actions.generated.ts";
 function fileHostManifest(root) {
     const path = join(root, HOST_FILE);
     if (!existsSync(path)) {
@@ -272,7 +253,7 @@ function fileHostManifest(root) {
             throw new Error("[rsc-kit] rsc-host-actions.json is the old manifest. The backend now writes " +
                 HOST_FILE + " - { actions, functions } - so update the adapter and run its manifest command.");
         }
-        return { actions: {}, functions: null };
+        return { actions: {}, functions: null, types: {}, defs: {} };
     }
     let parsed;
     try {
@@ -291,7 +272,10 @@ function fileHostManifest(root) {
     if (functions !== undefined && (!Array.isArray(functions) || functions.some((n) => typeof n !== "string"))) {
         throw new Error(`[rsc-kit] ${HOST_FILE}: "functions" must be an array of names.`);
     }
+    const isMap = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
     return {
+        types: isMap(parsed?.types) ? parsed.types : {},
+        defs: isMap(parsed?.defs) ? parsed.defs : {},
         actions: actions,
         // The reserved guard call is the engine's to make, not the app's.
         functions: functions ? functions.filter((n) => !n.startsWith("__rsc.")).sort() : null,
@@ -433,6 +417,8 @@ function loadHostManifest(options) {
     const manifest = fileHostManifest(projectRoot);
     hostActions = options.hostActions ?? manifest.actions;
     hostFunctions = manifest.functions;
+    hostTypes = manifest.types;
+    hostDefs = manifest.defs;
 }
 /** Run the backend's manifest command, once per process; see the option. */
 function runHostManifest(options, isBuild) {
@@ -790,7 +776,7 @@ function writeHostBindings(manifest) {
     // which typechecks a server and fails a prerender script.
     writeGenerated(join(typesDir, "rsc-engine.d.ts"), ENGINE_TYPES);
     warnIfTypesUnreachable();
-    const target = join(sourceDir, "server-actions.generated.ts");
+    const target = join(sourceDir, HOST_ACTIONS_MODULE);
     // A host with no functions of its own leaves no file behind: kept, its
     // stubs would go on naming targets the host has stopped answering for.
     if (Object.keys(hostActions).length === 0) {
@@ -1733,7 +1719,11 @@ async function prerenderAfterBundles(bundle, staticDir, assetsDir, knownActions
     // an action nothing else in the app states — whether anything checks who
     // calls it.
     const audited = await auditActions(engine, knownActions);
-    const bare = audited.filter((a) => !a.client);
+    // Not the host's stubs. Each forwards to a backend function, and the check
+    // on who calls it runs there - Laravel's guards, Go's middleware - where
+    // this build cannot see it. Counted, they made every backend action look
+    // unguarded: "11 actions run no middleware" for an API that checks them all.
+    const bare = audited.filter((a) => !a.client && basename(a.file) !== HOST_ACTIONS_MODULE);
     if (bare.length > 0) {
         const byFile = new Map();
         for (const a of bare)
@@ -2020,6 +2010,105 @@ function renderRouteTypes(manifest) {
         "",
     ].join("\n");
 }
+/** A property name as TypeScript accepts it. */
+const tsKey = (name) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+/**
+ * A backend's JSON Schema as a TypeScript type. Named types are written once,
+ * in the RscHost namespace, and referred to; anything the schema does not say
+ * is unknown rather than any, so a gap is visible where it is used.
+ */
+function tsOf(schema) {
+    if (!schema || Object.keys(schema).length === 0)
+        return "unknown";
+    const ref = schema.$ref;
+    if (typeof ref === "string" && ref.startsWith("#/defs/"))
+        return "RscHost." + ref.slice(7);
+    if (Array.isArray(schema.anyOf)) {
+        return [...new Set(schema.anyOf.map(tsOf))].join(" | ");
+    }
+    // A backed enum: its values, each a literal.
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.map((v) => JSON.stringify(v)).join(" | ") || "never";
+    }
+    switch (schema.type) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array":
+            return "Array<" + tsOf(schema.items) + ">";
+        case "object": {
+            const properties = schema.properties;
+            if (properties) {
+                const required = new Set(schema.required ?? []);
+                const fields = Object.entries(properties).map(([name, s]) => tsKey(name) + (required.has(name) ? "" : "?") + ": " + tsOf(s));
+                return "{ " + fields.join("; ") + (fields.length ? " }" : "}");
+            }
+            return "Record<string, " + tsOf(schema.additionalProperties) + ">";
+        }
+        default:
+            return "unknown";
+    }
+}
+/** A typed function's parameter list: positional, trailing pointers optional, a variadic rest. */
+function tsParams(sig) {
+    const optionalFrom = sig.params.length - (sig.optional ?? 0);
+    const params = sig.params.map((p, i) => "arg" + (i + 1) + (i >= optionalFrom ? "?" : "") + ": " + tsOf(p));
+    if (sig.rest)
+        params.push("...rest: Array<" + tsOf(sig.rest) + ">");
+    return params.join(", ");
+}
+/** The first parameter's schema with its reference followed, for decoding a form into it. */
+function firstParamSchema(sig) {
+    const first = sig?.params[0];
+    const ref = first?.$ref;
+    if (typeof ref === "string" && ref.startsWith("#/defs/"))
+        return hostDefs[ref.slice(7)] ?? null;
+    return first ?? null;
+}
+/**
+ * A form posted to a backend action. React hands the action a FormData; on
+ * the wire to the backend it is JSON, and JSON.stringify of a FormData is {} -
+ * so a form posting straight to a backend action used to send nothing. Its
+ * fields become one object, typed by the first parameter where the backend
+ * described it: numbers and booleans coerced, a repeated name a list.
+ */
+const FORM_ARGS = `function formArgs(args: unknown[], schema: Record<string, any> | null): unknown[] {
+  if (args.length !== 1 || !(args[0] instanceof FormData)) return args
+
+  const form = args[0] as FormData
+  const props: Record<string, any> = schema?.properties ?? {}
+  const coerce = (type: unknown, v: string): unknown =>
+    type === 'integer' || type === 'number' ? (v === '' ? null : Number(v))
+      : type === 'boolean' ? v === 'on' || v === 'true' || v === '1'
+      : v
+  const out: Record<string, unknown> = {}
+
+  for (const key of new Set(form.keys())) {
+    // React's own fields for a form action, not the form's.
+    if (key.startsWith('$ACTION_')) continue
+
+    const values = form.getAll(key).filter((v): v is string => typeof v === 'string')
+    const prop = props[key]
+
+    out[key] = prop?.type === 'array' || (!prop && values.length > 1)
+      ? values.map((v) => coerce(prop?.items?.type, v))
+      : coerce(prop?.type, values[0] ?? '')
+  }
+
+  // An unchecked checkbox sends nothing: false, not missing.
+  for (const [key, prop] of Object.entries(props)) {
+    if (!(key in out) && prop?.type === 'boolean') out[key] = false
+  }
+
+  return [out]
+}
+`;
 /** The "use server" module exposing each host function as a plain async call. */
 function renderHostActions() {
     const lines = [
@@ -2027,13 +2116,24 @@ function renderHostActions() {
         "// @generated — do not edit. Written by the RSC build from the host action map.",
         "",
     ];
+    lines.push(FORM_ARGS);
     for (const [name, target] of Object.entries(hostActions)) {
+        const sig = hostTypes[target];
+        // Typed where the backend described it: its own parameters, or the form
+        // that posts to it, and what it returns. Untyped otherwise, as before.
+        if (sig) {
+            const result = "Promise<" + (sig.result ? tsOf(sig.result) : "void") + ">";
+            lines.push("export async function " + name + "(" + tsParams(sig) + "): " + result + ";");
+            lines.push("export async function " + name + "(form: FormData): " + result + ";");
+        }
         lines.push("export async function " + name + "(...args: unknown[]) {");
         lines.push("  return await (globalThis as any)." +
             hostGlobal +
             "(" +
             JSON.stringify(target) +
-            ", ...args);");
+            ", ...formArgs(args, " +
+            JSON.stringify(firstParamSchema(sig)) +
+            "));");
         lines.push("}");
         lines.push("");
     }
@@ -2053,22 +2153,48 @@ function renderHostGlobalTypes() {
         "// Deliberately not a module — no import/export — so the declaration is",
         "// global to the project without every file having to reference it.",
         "",
-        // The names the backend listed, so a misspelt one fails the typecheck
-        // rather than the render. Without a list, any string.
-        ...(hostFunctions?.length
-            ? [
-                "// From " + HOST_FILE + ", which the backend writes.",
-                "type RscHostFunction =",
-                ...hostFunctions.map((name, i) => "  | " + JSON.stringify(name) + (i === hostFunctions.length - 1 ? ";" : "")),
-                "",
-            ]
-            : []),
-        "declare function " +
-            hostGlobal +
-            "<T = unknown>(name: " + (hostFunctions?.length ? "RscHostFunction" : "string") + ", ...args: unknown[]): Promise<T>;",
-        "",
+        ...renderHostSignatures(),
     ].join("\n");
 }
+/**
+ * The rpc() declaration, as precisely as the backend described itself.
+ *
+ * A function the backend typed gets its own overload: its parameters, and
+ * its result as the default type, so rpc('Orders.recent', 5) is Order[]
+ * without a type argument. One it named but did not type takes anything and
+ * returns what the caller says. With no list at all, any name.
+ */
+function renderHostSignatures() {
+    const out = [];
+    const typed = Object.keys(hostTypes).filter((name) => !name.startsWith("__rsc.")).sort();
+    if (Object.keys(hostDefs).length > 0) {
+        out.push("// The backend's own types, from " + HOST_FILE + ".", "declare namespace RscHost {");
+        for (const name of Object.keys(hostDefs).sort()) {
+            const schema = hostDefs[name];
+            out.push(schema.type === "object" && schema.properties
+                ? "  interface " + name + " " + tsOf(schema)
+                : "  type " + name + " = " + tsOf(schema) + ";");
+        }
+        out.push("}", "");
+    }
+    for (const name of typed) {
+        const sig = hostTypes[name];
+        const params = tsParams(sig);
+        out.push("declare function " + hostGlobal + "<T = " + (sig.result ? tsOf(sig.result) : "void") + ">(name: " +
+            JSON.stringify(name) + (params ? ", " + params : "") + "): Promise<T>;");
+    }
+    const untyped = hostFunctions?.filter((name) => !hostTypes[name]) ?? null;
+    if (untyped === null) {
+        out.push("declare function " + hostGlobal + "<T = unknown>(name: string, ...args: unknown[]): Promise<T>;");
+    }
+    else if (untyped.length > 0) {
+        // The names the backend listed, so a misspelt one fails the typecheck
+        // rather than the render.
+        out.push("// From " + HOST_FILE + ", which the backend writes.", "type RscHostFunction =", ...untyped.map((name, i) => "  | " + JSON.stringify(name) + (i === untyped.length - 1 ? ";" : "")), "declare function " + hostGlobal + "<T = unknown>(name: RscHostFunction, ...args: unknown[]): Promise<T>;");
+    }
+    out.push("");
+    return out;
+}
 // ── Discovery ────────────────────────────────────────────────────────────────
 const ROUTE_FILES = [
     "page",
@@ -2391,10 +2517,25 @@ const FALLBACK_CONSTS = `const FALLBACK_ORIGIN = __ORIGIN__
 const FALLBACK_MARKER = 'x-rsc-renderer-fallback'
 const PROXIED_MARKER = 'x-rsc-proxied-by-backend'
 `;
+/** With no backend configured: this app's not-found page, or a test's backend. */
+const NO_FALLBACK_BODY = `  const answer = await devHandler(request)
+
+  if (answer) return answer
+
+  if (backendForward && !pageSaidNotFound(request)) return await backendForward(request)
+
+  return await notFound(request)
+`;
 const FALLBACK_BODY = `  const answer = await devHandler(request)
 
   if (answer) return answer
 
+  // A page of this app said there is nothing here - notFound() in it or in
+  // its guard, or a backend's 404. That is this app's not-found.tsx, not a
+  // url for the backend: forwarded, the backend answered with its own 404
+  // and the app's never showed.
+  if (pageSaidNotFound(request)) return await notFound(request)
+
   // Nothing here owns this url. In development the backend usually does — a
   // Blade page, /login, a webhook, an uploaded file under /storage — so the
   // request is handed on rather than refused, and this origin is the whole
@@ -2452,6 +2593,18 @@ const FALLBACK_BODY = `  const answer = await devHandler(request)
 
   const hasBody = request.method !== 'GET' && request.method !== 'HEAD'
 
+  // A test's backend: the same request, answered in-process.
+  if (backendForward) {
+    return await backendForward(
+      new Request(target, {
+        method: request.method,
+        headers,
+        body: hasBody ? request.body : undefined,
+        ...(hasBody ? { duplex: 'half' } : {}),
+      } as RequestInit),
+    )
+  }
+
   try {
     return await fetch(target, {
       method: request.method,
@@ -2684,7 +2837,7 @@ import { notFoundDigest, isNotFoundSignal } from ${JSON.stringify(join(packageDi
 import { noteRequestRead, urlOf } from ${JSON.stringify(join(packageDir, "request"))}
 import { redirectDigest } from ${JSON.stringify(join(packageDir, "redirectDigest"))}
 import { cancelledByConsumer } from ${JSON.stringify(join(packageDir, "js/fallbackReport"))}
-import { createRscHandler, queryAndParams } from ${JSON.stringify(join(packageDir, "host"))}
+import { createRscHandler, pageSaidNotFound, queryAndParams } from ${JSON.stringify(join(packageDir, "host"))}
 import { httpHostCalls } from ${JSON.stringify(join(packageDir, "hostCalls"))}
 import { prerenderedBeside } from ${JSON.stringify(join(packageDir, "files"))}
 import { renderToReadableStream, decodeReply, decodeAction, decodeFormState, loadServerAction } from '@vitejs/plugin-rsc/rsc'
@@ -2693,7 +2846,7 @@ import { isActionValidationError, isClientBuilt } from ${JSON.stringify(join(pac
 import { forgetCached } from ${JSON.stringify(join(packageDir, "cache"))}
 import { noteFallback as noteCaughtRead } from ${JSON.stringify(join(packageDir, "request"))}
 import { isOutdatedOptimizedDep, outdatedDepResponse } from ${JSON.stringify(join(packageDir, "devReload"))}
-import { sharedDepth } from ${JSON.stringify(join(packageDir, "routing"))}
+import { paramsFor, segmentNames, sharedDepth } from ${JSON.stringify(join(packageDir, "routing"))}
 import { Suspense, createElement, Fragment } from 'react'
 import { AsyncLocalStorage } from 'node:async_hooks'
 ${imports.join("\n")}
@@ -3133,6 +3286,19 @@ if (__instrumentation.register && !isolateRuntime) {
 
 let currentHost: HostFn | null = null
 
+/**
+ * What answers a url this app does not own, in place of the backend.
+ *
+ * For createTestApp({ backend }): a url the app forwards to its backend
+ * reaches the test instead of a server that is not running, which answered
+ * every one with a 502.
+ */
+let backendForward: ((request: Request) => Response | Promise<Response>) | null = null
+
+export function installBackendForward(fn: ((request: Request) => Response | Promise<Response>) | null) {
+  backendForward = fn
+}
+
 export function installHostFn(fn: HostFn) {
   currentHost = fn
   return () => {
@@ -3306,6 +3472,48 @@ function errorChain(component: string): string[] {
   return errorChains[component] ?? []
 }
 
+/**
+ * The params of a render for a route's pattern rather than one url: they
+ * never settle, so whatever awaits them suspends and the rest is the shell.
+ * Marked, so a layout awaiting them can be named in the build's refusal.
+ */
+const unknownParams = new WeakSet<Promise<unknown>>()
+
+function patternParams(): Promise<Record<string, unknown>> {
+  const never = new Promise<Record<string, unknown>>(() => {})
+
+  unknownParams.add(never)
+
+  return never
+}
+
+/**
+ * What a layout is handed as params: its own segments' and those above it.
+ *
+ * During the pattern render, a layout with no dynamic segment of its own has
+ * nothing to wait for and gets its empty params at once. One with a segment
+ * waits forever, and says so - "params in app/[team]/layout" - so the build
+ * names the layout rather than whichever read happened to be last.
+ */
+function layoutParams(component: string, params: Promise<Record<string, unknown>>): Promise<Record<string, unknown>> {
+  if (!unknownParams.has(params)) return params.then((all) => paramsFor(component, all))
+
+  if (segmentNames(component).length === 0) return Promise.resolve({})
+
+  const by = 'params in ' + (component.startsWith('app/') ? component.slice(4) : component)
+
+  return {
+    then(resolve, reject) {
+      noteRequestRead(by)
+
+      return params.then(resolve, reject)
+    },
+    catch: (reject) => params.catch(reject),
+    finally: (done) => params.finally(done),
+    [Symbol.toStringTag]: 'Promise',
+  } as Promise<Record<string, unknown>>
+}
+
 // Composition: layout(outer..inner) > Suspense(loading, innermost-first) > page.
 function buildElement(
   component: string,
@@ -3465,8 +3673,13 @@ function buildElement(
       element = createElement(SegmentBoundary, { depth: i + 1, pageKey }, withPathname(element))
     }
 
+    // Its own segments' params and those above it, awaitable as a page's
+    // are: a layout above [team] is kept mounted across teams, so a deeper
+    // value handed to it would go stale. See paramsFor.
+    const own = layouts[i].component
     element = createElement(Layout, {
       ...(layouts[i].props ?? {}),
+      params: layoutParams(own, params),
       ...(slotsByLayout.get(i) ?? {}),
       children: element,
     })
@@ -4216,7 +4429,18 @@ interface PageContext {
  * A slot is the only unit smaller than a page the server can name, which is
  * why two tables have to be slots to be refreshed apart from each other.
  */
-async function renderRevalidated(target: string, page: PageContext): Promise<unknown> {
+/** What renderRevalidated answers for a region the calling page does not have. */
+const SKIPPED = Symbol('rsc-kit.revalidate-skipped')
+
+/** Whether any page in the app has a section or slot by this name. */
+function regionOfSomePage(target: string): boolean {
+  return manifest().routes.some((route: any) =>
+    (route.sections ?? []).some((name: string) => name.split('/').pop() === target + '.section') ||
+    Object.hasOwn(route.slots ?? {}, target),
+  )
+}
+
+async function renderRevalidated(target: string, page: PageContext, skipElsewhere = false): Promise<unknown> {
   // Every target below 'all' renders without the layout chain above it, which
   // is the same skip a navigation performs and needs the same guard run.
   await runMiddleware(page.component, page.props)
@@ -4279,6 +4503,12 @@ async function renderRevalidated(target: string, page: PageContext): Promise<unk
     ? page.parallelSlots[target]
     : undefined
 
+  // A region of another page. An action names what it changed, not where
+  // it was called from - a backend's above all, which cannot know - so a
+  // region the calling page does not show is nothing to refresh here. A name
+  // no page has is still a mistake, and refused below.
+  if (!slotComponent && skipElsewhere && regionOfSomePage(target)) return SKIPPED
+
   if (!slotComponent) {
     throw new Error(
       'Cannot revalidate ' + target + ': no section or slot of this page by that name. ' +
@@ -4457,7 +4687,9 @@ export async function handleAction(
     const revalidated: Record<string, unknown> = {}
 
     for (const target of targets) {
-      revalidated[target] = await renderRevalidated(target, page)
+      const tree = await renderRevalidated(target, page, true)
+
+      if (tree !== SKIPPED) revalidated[target] = tree
     }
 
     // Marked, so an action whose own result happens to be an object with a
@@ -4923,7 +5155,7 @@ export async function handleRscPprShell(
         0,
         pageKey,
         true,
-        pageKey ? Promise.resolve(props) : new Promise(() => {}),
+        pageKey ? Promise.resolve(props) : patternParams(),
       )
       // Quiet about a redirect: during the probe it is a classification, not
       // a failure, and React would otherwise print a stack for every one.
@@ -5047,7 +5279,7 @@ async function serve(request: Request): Promise<Response> {
 ${NITRO_HANDLER_OPTIONS}${NITRO_PRERENDERED}    maxActionBody: ${maxActionBody === undefined ? "undefined" : String(maxActionBody)},
   })
 
-${fallbackOrigin ? FALLBACK_BODY : "  return (await devHandler(request)) ?? (await notFound(request))\n"}}
+${fallbackOrigin ? FALLBACK_BODY : NO_FALLBACK_BODY}}
 
 /**
  * The page for a url nothing answers.