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

package/types/response.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Envelope pairing HTTP metadata (a `Response`) with an in-memory value.
+ * Produced by `respond()` and by server-function `transformResult`
+ * implementations (e.g. single-flight payloads). The HTTP handler forwards
+ * `response`'s headers and (non-redirect) status and encodes `value` as the
+ * body through the codec, while client-only integrations read `value`
+ * directly — no reparse. Mostly consumed by integrations (routers);
+ * application code usually just returns what `respond()` gives it.
+ */
+export class ResponseEnvelope<T = unknown> {
+  constructor(response: Response | undefined, value: T);
+  /** The HTTP metadata: status and headers to forward (body ignored by integrations). */
+  response: Response | undefined;
+  /** The structured value the caller receives. */
+  value: T;
+}
+
+/**
+ * Whether `value` is a `ResponseEnvelope`. Uses a registered-symbol brand
+ * rather than `instanceof`, so it stays correct when separately bundled
+ * entries each carry a copy of the class. Integrations should always use
+ * this over `instanceof`.
+ */
+export function isResponseEnvelope(value: unknown): value is ResponseEnvelope;
+
+/** `ResponseInit` accepted by the response helpers, plus `revalidate`. */
+export interface ResponseHelperInit extends ResponseInit {
+  /**
+   * Cache keys the mutation invalidated, carried in the `X-Revalidate`
+   * header. Opaque to the protocol — the integration's keyed cache (e.g.
+   * the router's `query` cache) assigns them meaning.
+   */
+  revalidate?: string | string[];
+}
+
+/**
+ * Response redirecting to `url` (default status 302). Return (or throw) it
+ * from a server function — the HTTP handler forwards the redirect for the
+ * client integration to follow — or return it from a client-side action,
+ * where the integration interprets it in memory. Same object, same
+ * meaning, both sides.
+ *
+ * @example
+ * ```ts
+ * import { redirect } from "@solidjs/web";
+ *
+ * async function login(form: FormData) {
+ *   "use server";
+ *   // ...
+ *   return redirect("/dashboard", { revalidate: "session" });
+ * }
+ * ```
+ */
+export function redirect(url: string, init?: number | ResponseHelperInit): Response;
+
+/**
+ * Empty response requesting revalidation of the named cache keys — all of
+ * them when omitted. For mutations whose only effect the caller needs is
+ * "refetch your data".
+ *
+ * @example
+ * ```ts
+ * import { reload } from "@solidjs/web";
+ *
+ * async function addTodo(title: string) {
+ *   "use server";
+ *   await db.insert(title);
+ *   return reload({ revalidate: "todos" });
+ * }
+ * ```
+ */
+export function reload(init?: ResponseHelperInit): Response;
+
+/**
+ * A value paired with response metadata (status, headers, `revalidate`) —
+ * for the things a naked return can't express. Scripted callers receive
+ * `value` transparently (the transport unwraps the envelope), and
+ * progressive enhancement stays invisible: the carried response holds a
+ * plain JSON body so consumers without the client runtime (no-JS form
+ * posts, direct HTTP) get real JSON.
+ *
+ * @example
+ * ```ts
+ * import { respond } from "@solidjs/web";
+ *
+ * async function createItem(input: Item) {
+ *   "use server";
+ *   const item = await db.create(input);
+ *   return respond(item, { status: 201, revalidate: "items" });
+ * }
+ * ```
+ */
+export function respond<T>(value: T, init?: ResponseHelperInit): ResponseEnvelope<T>;

package/types/serializer.d.ts

@@ -0,0 +1,139 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+/**
+ * Seroval's node shape — the intermediate representation `serializeJSON`
+ * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ */
+export type { SerovalNode };
+
+/**
+ * A Seroval plugin usable with the web serializers — teaches the codec how
+ * to encode/decode a custom value type. Supply matching plugins on both
+ * peers of a transport.
+ */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * Baseline plugin set for serializing web-platform values (AbortSignal,
+ * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
+ * Applied by every serializer in this module; custom plugins compose ahead
+ * of it via `resolveSerializerPlugins`.
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * first so they can shadow a default for values both would match. Returns a
+ * fresh array; the defaults are never mutated. Useful when handing a full
+ * plugin list to another serialization layer.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+/** Options for `createSerializer`. */
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  /** Cross-reference scope id, for isolating multiple streams on one page. */
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays).
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  /** Receives each emitted script chunk. */
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy. Emits JavaScript chunks (through
+ * `onData`) that reconstruct the values under `globalIdentifier` when
+ * evaluated — the script-injection form of serialization renderers build
+ * on. For a JSON-based wire codec (no eval on the receiving side), use
+ * `serializeJSON` / `createJSONDeserializer` instead.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+/**
+ * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
+ * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
+ * @internal
+ */
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Renderer primitive — the serializer SSR uses for hydration output. Pins
+ * the hydration global (`_$HY.r`) and feature policy; only the wiring
+ * options (callbacks, scope, extra plugins) are configurable. Not meant
+ * for hand-written code — custom serialization should use
+ * `createSerializer` or the JSON codec.
+ * @internal
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/**
+ * Renderer primitive — returns the cross-reference bootstrap script SSR
+ * emits ahead of hydration data for a render scope. Not meant for
+ * hand-written code.
+ * @internal
+ */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+/**
+ * Options shared by both halves of the JSON codec. All of them must match
+ * on the serializing and deserializing peer or payloads will not
+ * round-trip — for server functions, set them once through the
+ * client/server `codec` config option.
+ */
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+/** Options for `serializeJSON`. */
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse` —
+ * the encoding half of the eval-free JSON codec (RPC-style transports;
+ * the deserializing peer needs no script evaluation, so CSP-safe). Wire
+ * framing of the nodes is the transport's concern. Returns a cancel
+ * function that aborts pending async serialization.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * from one stream must go through the same deserializer instance. The first
+ * chunk's return value is the decoded source value; feeding later chunks
+ * settles the async values referenced inside it.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;

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

@@ -0,0 +1,137 @@
+import { JSONCodecOptions } from "../serializer.js";
+import { ServerFunction, ServerFunctionMetadata } 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";
+
+/** 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 {
+  /**
+   * Endpoint the server's HTTP handler is mounted on. Must match the
+   * server configuration — SSR'd reference `url`s (e.g. form actions) and
+   * client fetches both derive from it. Prefix it when the app serves from
+   * a base path (e.g. `` `${BASE_URL}_server` ``).
+   * @default "/_server"
+   */
+  endpoint?: string;
+  /**
+   * Codec options (extra plugins etc.) for encoding arguments and decoding
+   * results — must match the server's. Stored in the shared layer, so
+   * `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, codec plugins, or a
+ * `prepareRequest` hook).
+ */
+export function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
+
+/**
+ * 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 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. 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, name?: string): ServerFunction;
+
+/**
+ * Compiler ABI — only ever referenced by server-mode compiler output;
+ * throws so a misconfigured build (server transform feeding a client
+ * bundle) fails loudly instead of with a missing-export error. Not meant
+ * for hand-written code.
+ * @internal
+ */
+export function registerServerReference(): never;

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

@@ -0,0 +1,307 @@
+import { ResponseEnvelope } from "../response.js";
+import { JSONCodecOptions } from "../serializer.js";
+import { RequestEvent } from "../server.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
+ * `RequestEvent` (request + locals) plus `serverOnly`, set when the call is
+ * an in-process SSR invocation whose result never serializes to a client.
+ */
+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 {
+  /**
+   * Establishes the request-event scope for a call — the function passed
+   * runs with `event` visible to `getRequestEvent()`. Wire it to
+   * `provideRequestEvent` from `@solidjs/web/storage` (or the framework's
+   * equivalent). When omitted, falls back to the AsyncLocalStorage instance
+   * 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.
+   * Prefix it when the app serves from a base path (e.g.
+   * `` `${BASE_URL}_server` ``).
+   * @default "/_server"
+   */
+  endpoint?: string;
+  /**
+   * Codec options (extra plugins etc.) for decoding arguments and encoding
+   * results — must match the client's. Stored in the shared layer, so
+   * `decodeResponse` sees them too.
+   */
+  codec?: JSONCodecOptions;
+}
+
+/**
+ * Configures the server runtime. Call once at server startup, before
+ * handling requests. Only needed when deviating from the defaults (custom
+ * endpoint, codec plugins, an explicit event provider, or a single-flight
+ * hook).
+ */
+export function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
+
+/**
+ * A registered server function: its build-stable id paired with the
+ * original implementation. Returned by `registerServerReference` and
+ * consumed by the server-side `createServerReference`.
+ *
+ * Compiler ABI shape; hand-written code rarely constructs these.
+ * @internal
+ */
+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;
+}
+
+/**
+ * Adds a function to the dispatch registry under an id and returns it
+ * unchanged. The low-level registry write for integrations registering
+ * functions outside the compiler (e.g. a router registering its own
+ * endpoints); compiled output goes through `registerServerReference`
+ * instead. Ids must be stable across the client and server builds.
+ */
+export function registerServerFunction<T extends any[], R>(
+  id: string,
+  callback: (...args: T) => R
+): (...args: T) => R;
+
+/**
+ * Looks up a registered server function by id; throws for unknown ids.
+ * The HTTP handler uses this for dispatch — integrations building custom
+ * dispatch (or introspection) can too.
+ */
+export function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
+
+/**
+ * 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. 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,
+  name?: string
+): ServerFunctionReference<T, R>;
+
+/**
+ * Compiler ABI — emitted by compiled `"use server"` server output where
+ * the function was referenced; produces the server-side callable. Calling
+ * it during SSR runs the original function in-process (no HTTP), under a
+ * request event derived from the current one — marked `serverOnly` and
+ * carrying the function's meta. Not meant for hand-written code.
+ * @internal
+ */
+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;
+}
+
+/**
+ * Reads the calling server function's meta (its id) off the current request
+ * event — usable inside a server function body, e.g. to key caches or logs
+ * by function. Returns undefined outside a server function call.
+ */
+export function getServerFunctionMeta(): ServerFunctionMeta | undefined;
+
+/**
+ * Hooks layering framework policy onto `handleServerFunctionRequest`.
+ * All are optional — the bare handler dispatches, scopes events, and
+ * encodes results on its own.
+ */
+export interface HandleServerFunctionOptions {
+  /**
+   * Builds the request event a call runs under (default: bare
+   * `{ request, locals: {} }`). Integrations supply their richer event
+   * (cookies, response helpers, platform handles).
+   */
+  createEvent?(request: Request): ServerFunctionEvent;
+  /**
+   * Overrides the configured event provider for this handler — same
+   * contract as the `provideEvent` config option.
+   */
+  provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
+  /**
+   * Observes or replaces the function's result before encoding — the
+   * 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
+   * point for conventions like redirect-with-flash-cookie. Receives the
+   * (transformed) result, the request, and the decoded arguments; `thrown`
+   * is set when the result was thrown rather than returned. Defaults to
+   * the normal serialized response.
+   */
+  handleNoJS?(
+    result: unknown,
+    request: Request,
+    args: unknown[],
+    thrown?: boolean
+  ): Response | Promise<Response>;
+  /** Overrides the configured codec options for this handler. */
+  codec?: JSONCodecOptions;
+}
+
+/**
+ * Web-standard HTTP handler for server function calls: resolves the
+ * 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
+ * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
+ * import "virtual:solid-server-function-manifest";
+ *
+ * // in the server's request handling:
+ * if (url.pathname.startsWith("/_server")) {
+ *   return handleServerFunctionRequest(request);
+ * }
+ * ```
+ */
+export function handleServerFunctionRequest(
+  request: Request,
+  options?: HandleServerFunctionOptions
+): Promise<Response>;