@solidjs/web 2.0.0-beta.20 → 2.0.0-beta.21

package/types/server-functions/server.d.ts

@@ -2,7 +2,24 @@ import { ResponseEnvelope } from "../response.js";
 import { JSONCodecOptions } from "../serializer.js";
 import { RequestEvent } from "../server.js";
 
-export { FUNCTION_HEADER, INSTANCE_HEADER, decodeResponse } from "./shared.js";
+export {
+  FUNCTION_HEADER,
+  INSTANCE_HEADER,
+  SINGLE_FLIGHT_HEADER,
+  decodeResponse,
+  getServerFunctionMetadata,
+  isServerFunction,
+  subscribeFlightData,
+  withMeta
+} from "./shared.js";
+export type {
+  FlightDataConsumer,
+  FlightDataContext,
+  ServerFunction,
+  ServerFunctionMetadata,
+  SingleFlightPayload
+} from "./shared.js";
+import { ServerFunction } from "./shared.js";
 
 /**
  * The request event a server function call runs under: the base
@@ -13,6 +30,58 @@ export interface ServerFunctionEvent extends RequestEvent {
   serverOnly?: boolean;
 }
 
+/**
+ * What a server function call resolved to, as seen by the single-flight
+ * hook — enough context for any data-production strategy without core
+ * assuming one.
+ */
+export interface ServerFunctionOutcome {
+  /** The build-stable id of the function that ran. */
+  id: string;
+  /**
+   * The value the caller will receive: the raw return for plain results,
+   * the unwrapped `value` for `ResponseEnvelope`s, `null` for body-less
+   * control-flow `Response`s (redirect/reload).
+   */
+  value: unknown;
+  /**
+   * The `Response` carrying the result's HTTP metadata, when there is one
+   * (from a returned/thrown `Response` or a `ResponseEnvelope`). Read
+   * `Location` here for redirect-with-data — the data should describe the
+   * destination route — and `X-Revalidate` for the invalidated keys.
+   * Undefined for plain values.
+   */
+  response: Response | undefined;
+  /**
+   * The original HTTP request, untouched: headers the client integration
+   * sent (referrer, custom route context) ride here for the hook to read —
+   * core assigns them no meaning.
+   */
+  request: Request;
+  /** Whether the result was thrown rather than returned. */
+  thrown: boolean;
+}
+
+/**
+ * The single-flight server hook: given the request event and the function's
+ * outcome, optionally produce a data payload (possibly async) to fold into
+ * the response alongside the return value. Data production is a black box
+ * to the protocol — render data-only, run route preloads, query a cache,
+ * whatever the integration chooses; the payload just has to be
+ * codec-serializable. Return undefined to send the response unchanged
+ * (byte-identical to a call without the hook).
+ *
+ * Runs after `transformResult`, only for scripted calls that sent
+ * `SINGLE_FLIGHT_HEADER` on the request, on returned results and thrown
+ * `Response`/`ResponseEnvelope` control-flow signals alike (plain thrown
+ * errors never collect). The handler owns the enveloping: contributed data
+ * ships as `{ value, data }` under the single-flight response header.
+ */
+export type CollectFlightDataHook = (
+  event: ServerFunctionEvent,
+  outcome: ServerFunctionOutcome
+) => unknown | Promise<unknown>;
+
 /** Options for `configureServerFunctionsServer`. */
 export interface ServerFunctionsServerConfig {
   /**
@@ -23,6 +92,13 @@ export interface ServerFunctionsServerConfig {
    * an established request scope parks on the global.
    */
   provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
+  /**
+   * The single-flight hook: produces the data payload folded into
+   * responses of calls that opted in (see `CollectFlightDataHook`).
+   * Registered once by the integration that owns data production (a
+   * router); per-handler `collectFlightData` options override it.
+   */
+  collectFlightData?: CollectFlightDataHook;
   /**
    * Endpoint the HTTP handler is mounted on, used for the `url` of SSR'd
    * references (e.g. form actions) — must match the client configuration.
@@ -42,7 +118,8 @@ export interface ServerFunctionsServerConfig {
 /**
  * Configures the server runtime. Call once at server startup, before
  * handling requests. Only needed when deviating from the defaults (custom
- * endpoint, codec plugins, or an explicit event provider).
+ * endpoint, codec plugins, an explicit event provider, or a single-flight
+ * hook).
  */
 export function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
 
@@ -57,6 +134,12 @@ export function configureServerFunctionsServer(config?: ServerFunctionsServerCon
 export interface ServerFunctionReference<T extends any[] = any[], R = any> {
   id: string;
   fn: (...args: T) => R;
+  /**
+   * The function's source name, emitted by development builds only —
+   * `createServerReference` seeds the metadata channel with it.
+   * @internal
+   */
+  name?: string;
 }
 
 /**
@@ -82,12 +165,15 @@ export function getServerFunction<T extends any[], R>(id: string): (...args: T)
  * Compiler ABI — emitted by compiled `"use server"` server output for
  * every server function: registers `fn` for HTTP dispatch under its
  * build-stable id and returns the reference the server-side
- * `createServerReference` consumes. Not meant for hand-written code.
+ * `createServerReference` consumes. Development builds pass the function's
+ * source name as the trailing argument (dev-only metadata; never emitted in
+ * production). Not meant for hand-written code.
  * @internal
  */
 export function registerServerReference<T extends any[], R>(
   id: string,
-  fn: (...args: T) => R
+  fn: (...args: T) => R,
+  name?: string
 ): ServerFunctionReference<T, R>;
 
 /**
@@ -102,6 +188,29 @@ export function createServerReference<T extends any[], R>(
   reference: ServerFunctionReference<T, R>
 ): (...args: T) => R;
 
+/**
+ * Declares a server function callable over HTTP GET. The server half is
+ * identity-flavored — SSR calls stay in-process — but it brands the
+ * declaration on the reference's metadata channel
+ * (`getServerFunctionMetadata(fn)?.method === "GET"`) and records the
+ * declared method for the function's id so `handleServerFunctionRequest`
+ * enforces it: GET-declared functions accept GET requests (and only GET),
+ * everything else answers 405.
+ *
+ * Wrap the reference at its declaration; the compiler round-trips the call
+ * in both builds:
+ *
+ * ```ts
+ * export const getUser = GET(async (id: string) => {
+ *   "use server";
+ *   return db.users.find(id);
+ * });
+ * ```
+ */
+export function GET<A extends readonly any[], R>(
+  fn: (...args: A) => R
+): ServerFunction<A, Awaited<R>>;
+
 /** Identity of the currently executing server function. */
 export interface ServerFunctionMeta {
   id: string;
@@ -133,17 +242,26 @@ export interface HandleServerFunctionOptions {
   provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
   /**
    * Observes or replaces the function's result before encoding — the
-   * extension point for policies like single-flight payloads. Runs for
-   * returned and thrown results alike (`context.thrown` distinguishes);
-   * `context.instance` is null for no-JS calls. Return the result
-   * unchanged to pass through, or a `ResponseEnvelope` (exposed through
-   * the core entry) to send HTTP metadata plus a structured payload.
+   * extension point for response metadata policies (headers, statuses,
+   * substituted results). Runs for returned and thrown results alike
+   * (`context.thrown` distinguishes); `context.instance` is null for no-JS
+   * calls. Return the result unchanged to pass through, or a
+   * `ResponseEnvelope` (exposed through the core entry) to send HTTP
+   * metadata plus a structured payload. Runs before `collectFlightData`,
+   * so the flight hook sees the transformed outcome — use
+   * `collectFlightData`, not this, to fold data into the response.
    */
   transformResult?(
     event: ServerFunctionEvent,
     result: unknown,
     context: { instance: string | null; request: Request; thrown?: boolean }
   ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
+  /**
+   * Overrides the configured single-flight hook for this handler — same
+   * contract as the `collectFlightData` config option (see
+   * `CollectFlightDataHook`).
+   */
+  collectFlightData?: CollectFlightDataHook;
   /**
    * Builds the response for calls made without the client runtime (no
    * instance header — no-JS form posts, direct HTTP) — the extension
@@ -164,12 +282,13 @@ export interface HandleServerFunctionOptions {
 
 /**
  * Web-standard HTTP handler for server function calls: resolves the
- * function id from the request, decodes arguments, runs the function under
- * a request-event scope, and encodes the result (forwarding
- * redirect/revalidation metadata through headers). Mount it on the endpoint
- * the client transport targets (default `/_server`); platform adapters
- * (h3, express, ...) convert their request shape to a web `Request` around
- * it.
+ * function id from the request, enforces the declared method (405 when the
+ * request method contradicts a `GET` declaration — or uses GET without
+ * one), decodes arguments, runs the function under a request-event scope,
+ * and encodes the result (forwarding redirect/revalidation metadata
+ * through headers). Mount it on the endpoint the client transport targets
+ * (default `/_server`); platform adapters (h3, express, ...) convert their
+ * request shape to a web `Request` around it.
  *
  * @example
  * ```ts

package/types/server-functions/shared.d.ts

@@ -38,6 +38,177 @@ export const FUNCTION_HEADER: string;
  */
 export const INSTANCE_HEADER: string;
 
+/**
+ * Header driving the single-flight protocol on both legs
+ * (`"X-Single-Flight"`). On the request it opts the call into data
+ * collection — the transport sends it automatically on non-GET calls while
+ * a flight-data consumer is subscribed (subscribing IS the opt-in). On the
+ * response it marks a body carrying the standardized `SingleFlightPayload`.
+ * How the data is produced (a data-only render, running route preloads,
+ * anything else) and what it means is entirely the integration's business —
+ * the protocol only standardizes the wire shape and the delivery.
+ */
+export const SINGLE_FLIGHT_HEADER: string;
+
+/**
+ * The standardized body of a single-flight response (a response tagged with
+ * `SINGLE_FLIGHT_HEADER`): the function's return `value` plus the
+ * integration-produced `data` payload, folded into one round trip by the
+ * HTTP handler. Integrations decoding passthrough responses themselves (no
+ * registered consumer) see this shape from `decodeResponse`. The top level
+ * is reserved for the protocol — integration payload lives entirely under
+ * `data`, which can be any codec-serializable value.
+ */
+export interface SingleFlightPayload<T = unknown, D = unknown> {
+  /** The server function's return (or thrown) value. */
+  value: T;
+  /** The integration-produced data payload. */
+  data: D;
+}
+
+/**
+ * Envelope context delivered alongside single-flight data: the transport
+ * response, whose headers carry the integration metadata (`Location` for
+ * redirect-with-data, `X-Revalidate` keys) and status. The body is already
+ * consumed — read `data` and `value` from the delivery, not from here.
+ */
+export interface FlightDataContext {
+  /** The HTTP response the data arrived on (metadata only). */
+  response: Response;
+}
+
+/**
+ * Consumer receiving single-flight data on the client: `data` is the
+ * integration-produced payload (opaque to the protocol), `context` carries
+ * the envelope metadata. Async consumers are awaited before the function
+ * value is returned to the caller, so caches are seeded first.
+ */
+export type FlightDataConsumer<D = unknown> = (
+  data: D,
+  context: FlightDataContext
+) => void | Promise<void>;
+
+/**
+ * Registers the consumer the client transport delivers single-flight data
+ * to. Subscribing is the single-flight opt-in: while a consumer is
+ * registered the transport sends the request-leg `SINGLE_FLIGHT_HEADER` on
+ * non-GET calls (GET reads stay plain and cacheable), asking the server's
+ * collection hook to fold data into the response. When a single-flight
+ * response arrives, the transport decodes the standardized
+ * `{ value, data }` payload, delivers `data` (with the response as
+ * envelope context — redirect location, revalidation keys), and returns
+ * `value` to the caller as if the call were plain. What to do with the
+ * data (seed caches, navigate, ...) is entirely the consumer's business.
+ * One active consumer at a time — a later registration replaces the
+ * current one; returns an unsubscribe function. With no consumer
+ * registered, no header is sent and the server does no collection work;
+ * responses an integration opted in manually still pass through to the
+ * caller whole, exactly like other integration responses.
+ */
+export function subscribeFlightData<D = unknown>(consumer: FlightDataConsumer<D>): () => void;
+
+/**
+ * The currently registered single-flight consumer.
+ *
+ * Transport building block; not meant for hand-written code.
+ * @internal
+ */
+export function getFlightDataConsumer(): FlightDataConsumer | undefined;
+
+/**
+ * The public contract of a server function reference — what a `"use
+ * server"` import is at runtime on either side: an async callable plus its
+ * build-stable identity.
+ */
+export interface ServerFunction<A extends readonly any[] = any[], T = any> {
+  (...args: A): Promise<T>;
+  /** The build-stable function id (stable across the client and server builds). */
+  readonly id: string;
+  /** URL invoking this function directly over HTTP (form `action`s, raw fetches). */
+  readonly url: string;
+}
+
+/**
+ * Declaration-static metadata attached to a server function reference
+ * through declaration wrappers (`GET`, `withMeta`). Read it with
+ * `getServerFunctionMetadata`; routers and integrations detect capability
+ * from here instead of property sniffing, and `prepareRequest` receives it
+ * as `context.meta`. Write through `withMeta` — later writes shallow-merge
+ * over earlier ones.
+ */
+export interface ServerFunctionMetadata {
+  /** The declared HTTP method. Undeclared references call over POST. */
+  readonly method?: "GET" | "POST";
+  /**
+   * A human-readable label for the function, seeded by development builds
+   * from the compiled function's source name (dev tooling — inspectors,
+   * logs). Dev-only: production builds emit no name. Not unique and not an
+   * identity key — use `id` for identity. Seeded as a default: an explicit
+   * `withMeta` write wins.
+   */
+  readonly name?: string;
+  /** User-declared transport metadata attached with `withMeta`. */
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Reads a server function reference's declaration metadata — e.g.
+ * `getServerFunctionMetadata(fn)?.method === "GET"` detects a `GET(fn)`
+ * declaration. Returns undefined when `fn` is not a server function
+ * reference; plain references carry an empty metadata object. Works on
+ * client proxies and server-side references alike, across duplicated
+ * module instances (registered-symbol brand).
+ */
+export function getServerFunctionMetadata(fn: unknown): ServerFunctionMetadata | undefined;
+
+/**
+ * Whether `fn` is a server function reference (a client proxy or a
+ * server-side registered callable). Detection is structural — a
+ * registered-symbol metadata brand — so it holds across duplicated module
+ * instances and both sides of the directive boundary.
+ */
+export function isServerFunction(fn: unknown): fn is ServerFunction;
+
+/**
+ * Attaches user-declared transport metadata to a server function reference
+ * (client proxy or server-registered callable) and returns the reference.
+ * Writes ride the same channel `GET` uses: later writes shallow-merge over
+ * earlier ones, and `getServerFunctionMetadata(fn)` reads the merged bag —
+ * so `withMeta` composes with `GET` in either order
+ * (`GET(withMeta(fn, meta))` ≡ `withMeta(GET(fn), meta)`).
+ *
+ * The pattern is declare-on-function, react-in-hook: metadata declared
+ * here reaches `prepareRequest` as `context.meta`, letting session-dynamic
+ * transport policy key on declarations instead of comparing function ids:
+ *
+ * ```ts
+ * export const chargeCard = withMeta(async (amount: number) => {
+ *   "use server";
+ *   // ...
+ * }, { requiresAuth: true });
+ *
+ * configureServerFunctionsClient({
+ *   prepareRequest(init, { meta }) {
+ *     if (meta?.requiresAuth) {
+ *       return {
+ *         ...init,
+ *         headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
+ *       };
+ *     }
+ *     return init;
+ *   }
+ * });
+ * ```
+ */
+export function withMeta<F extends (...args: any[]) => any>(fn: F, meta: ServerFunctionMetadata): F;
+
+/**
+ * The registered symbol branding server function references with their
+ * declaration metadata. Use the typed accessors instead.
+ * @internal
+ */
+export const SERVER_FUNCTION_METADATA: unique symbol;
+
 /**
  * Header carrying the body format tag (a `BodyFormat` value) —
  * `"X-Server-Function-Format"`.

package/types-cjs/server-functions/client.d.cts

@@ -1,6 +1,48 @@
 import { JSONCodecOptions } from "../serializer.cjs";
+import { ServerFunction, ServerFunctionMetadata } from "./shared.cjs";
 
-export { FUNCTION_HEADER, INSTANCE_HEADER, decodeResponse } from "./shared.cjs";
+export {
+  FUNCTION_HEADER,
+  INSTANCE_HEADER,
+  SINGLE_FLIGHT_HEADER,
+  decodeResponse,
+  getServerFunctionMetadata,
+  isServerFunction,
+  subscribeFlightData,
+  withMeta
+} from "./shared.cjs";
+export type {
+  FlightDataConsumer,
+  FlightDataContext,
+  ServerFunction,
+  ServerFunctionMetadata,
+  SingleFlightPayload
+} from "./shared.cjs";
+
+/** The context `prepareRequest` receives alongside the outgoing RequestInit. */
+export interface PrepareRequestContext {
+  /** The build-stable id of the function being called. */
+  id: string;
+  /**
+   * The reference's declaration metadata (e.g. `method: "GET"` for
+   * `GET(fn)` references). Plain references carry an empty object.
+   */
+  meta: ServerFunctionMetadata | undefined;
+}
+
+/**
+ * Client-side session-dynamic transport hook: runs before every
+ * server-function fetch. Return (or mutate and return) the RequestInit the
+ * transport will use — the hook sees the final init, transport headers
+ * included. The motivating case is dynamic credentials that rotate during
+ * a session and apply uniformly to every call (OAuth bearer tokens); it is
+ * the client-side symmetric of the server handler hooks. Single hook, not
+ * a chain — compose by wrapping functions in userland.
+ */
+export type PrepareRequestHook = (
+  init: RequestInit,
+  context: PrepareRequestContext
+) => RequestInit | Promise<RequestInit>;
 
 /** Options for `configureServerFunctionsClient`. */
 export interface ServerFunctionsClientConfig {
@@ -18,40 +60,72 @@ export interface ServerFunctionsClientConfig {
    * `decodeResponse` sees them too.
    */
   codec?: JSONCodecOptions;
+  /**
+   * Runs before every server-function fetch. Return (or mutate and return)
+   * the RequestInit the transport will use; `context.meta` is the
+   * reference's declaration metadata (e.g. method). For session-dynamic
+   * cross-cutting concerns — bearer tokens, tracing headers:
+   *
+   * ```ts
+   * configureServerFunctionsClient({
+   *   prepareRequest(init) {
+   *     return {
+   *       ...init,
+   *       headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
+   *     };
+   *   }
+   * });
+   * ```
+   */
+  prepareRequest?: PrepareRequestHook;
 }
 
 /**
  * Configures the client transport. Call once, before any server function is
  * invoked — typically in the client entry, next to `hydrate()`. Only needed
- * when deviating from the defaults (custom endpoint or codec plugins).
+ * when deviating from the defaults (custom endpoint, codec plugins, or a
+ * `prepareRequest` hook).
  */
 export function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
 
 /**
- * What a server function import is at runtime on the client: an async
- * callable that fetches the server, plus escape hatches for forms and
- * custom requests.
+ * Declares a server function callable over HTTP GET: calls to the returned
+ * reference go out as GET requests with the arguments codec-encoded in the
+ * query string — cacheable by HTTP infrastructure. Cache headers flow
+ * through the handler's header forwarding
+ * (`respond(data, { headers: { "cache-control": "max-age=60" } })`).
+ *
+ * The declaration rides the metadata channel
+ * (`getServerFunctionMetadata(fn)?.method === "GET"`) for routers and
+ * integrations to detect, and the server enforces it: GET-declared
+ * functions accept GET requests (and only GET), everything else answers
+ * 405. Server-side the wrapper is identity-flavored — SSR calls stay
+ * in-process.
+ *
+ * Wrap the reference at its declaration; the compiler round-trips the call
+ * in both builds:
+ *
+ * ```ts
+ * export const getUser = GET(async (id: string) => {
+ *   "use server";
+ *   return db.users.find(id);
+ * });
+ * ```
  */
-export interface ServerFunctionCallable {
-  (...args: any[]): Promise<any>;
-  /** URL invoking this function directly over HTTP (e.g. form `action`s). */
-  url: string;
-  /**
-   * Variant issuing GET requests with the arguments encoded in the query
-   * string — cacheable by HTTP infrastructure.
-   */
-  GET: ServerFunctionCallable;
-  /** Variant applying a custom RequestInit to every call (headers etc.). */
-  withOptions(options: RequestInit): ServerFunctionCallable;
-}
+export function GET<A extends readonly any[], R>(
+  fn: (...args: A) => R
+): ServerFunction<A, Awaited<R>>;
 
 /**
  * Compiler ABI — emitted by compiled `"use server"` client output where a
  * server function was referenced; produces the fetch-backed callable for
- * the function's build-stable id. Not meant for hand-written code.
+ * the function's build-stable id. Development builds pass the function's
+ * source name as the trailing argument (dev-only metadata seeded on the
+ * metadata channel; never emitted in production). Not meant for
+ * hand-written code.
  * @internal
  */
-export function createServerReference(id: string): ServerFunctionCallable;
+export function createServerReference(id: string, name?: string): ServerFunction;
 
 /**
  * Compiler ABI — only ever referenced by server-mode compiler output;