@solidjs/web 2.0.0-experimental.8 → 2.0.0-rc.0

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

@@ -0,0 +1,201 @@
+import { JSONCodecOptions } from "../serializer-decode.js";
+import { ServerFunction, ServerFunctionMetadata } from "./shared.js";
+
+export {
+  ChunkReader,
+  ERROR_HEADER,
+  FLASH_COOKIE,
+  FUNCTION_HEADER,
+  INSTANCE_HEADER,
+  SINGLE_FLIGHT_HEADER,
+  clearFlashCookie,
+  createChunk,
+  decodeErrorHeaderValue,
+  decodeResponse,
+  decodeResponsePayload,
+  deserializeStream,
+  encodeErrorHeaderValue,
+  frameAddress,
+  getFlightDataConsumer,
+  getServerFunctionMetadata,
+  getServerFunctionsCodec,
+  hasFlashCookie,
+  isServerFunction,
+  serializeString,
+  subscribeFlightData,
+  withMeta
+} from "./shared.js";
+export { REVALIDATE_HEADER } from "../response.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;
+  /**
+   * Response-side integration seam — the client mirror of the handler's
+   * `transformResult`. `handle(response, ctx)` sees every response before
+   * the transport decodes it; returning anything but undefined resolves the
+   * call with that value. `capture(info)` runs synchronously at the call
+   * site (before any await) and its return arrives as `ctx.context`, so
+   * ambient per-call state (e.g. a reactive owner) survives to response
+   * time. See `createServerComponentHandler` in frame-transport for the
+   * canonical implementation.
+   */
+  responseHandler?: {
+    capture?(info: { id: string; meta: unknown }): unknown;
+    handle(
+      response: Response,
+      ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
+    ): unknown;
+  };
+  /**
+   * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
+   * always go as plain JSON (no codec in the bundle); anything else throws
+   * unless this is set. Installed by `enableRichArguments()` from the
+   * rich-args entry — set directly only for custom wire encodings.
+   */
+  serializeArgs?(args: unknown[]): string | Promise<string>;
+}
+
+/**
+ * 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 honors it: GET-declared functions
+ * accept GET requests in addition to the default POST transport (declaring
+ * GET grants, it does not revoke); functions that never declared GET answer
+ * GET requests with 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.
+ *
+ * The optional `base` targets calls at that url verbatim instead of the
+ * configured endpoint — for integrations reconstructing a callable from a
+ * server-rendered action url (e.g. a router intercepting a form submit whose
+ * `action="/_server?id=...&args=..."` came off the wire): bound arguments
+ * stay in the query string, where the server reads them for natural-encoding
+ * bodies (FormData, urlencoded).
+ * @internal
+ */
+export function createServerReference(id: string, name?: string, base?: 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;
+
+/**
+ * Identity of the currently executing server function call — see the
+ * server entry. Named here so isomorphic code can import the type from
+ * either entry.
+ */
+export interface ServerFunctionInvocation {
+  id: string;
+}
+
+/**
+ * Client no-op mirror of the server entry's accessor: there is never a
+ * server function call in flight on the client, so this always returns
+ * undefined. Present so `"use server"` modules that import it stay
+ * import-stable in client builds before dead-code elimination.
+ */
+export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;

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

@@ -0,0 +1,38 @@
+/**
+ * The outcome of a call made without the client runtime, as it rides the
+ * flash cookie: what was submitted, where, and what came back. `result` and
+ * `error` are mutually exclusive — a thrown outcome fills `error`, a
+ * returned one fills `result` — mirroring the split a scripted call sees.
+ */
+export interface FlashSubmission {
+  /** The arguments the call was made with (files are dropped). */
+  input: any[];
+  /** The call's url: pathname + search of the server function request. */
+  url: string;
+  /** The returned value, when the call returned. */
+  result?: any;
+  /** The thrown value, when the call threw. */
+  error?: any;
+}
+
+/**
+ * Encodes the outcome of a no-JS call as a `Set-Cookie` value, for the
+ * handler to send with its redirect. `url` identifies which submission the
+ * outcome belongs to; pass `thrown` when the call threw rather than
+ * returned.
+ *
+ * The payload is JSON inside the cookie: `FormData` and `URLSearchParams`
+ * arguments are captured as entry pairs and revived on decode, and `File`
+ * entries are dropped (they cannot ride a cookie). Keep in mind the 4 KB
+ * cookie budget — outcomes larger than that will not survive the round
+ * trip.
+ */
+export function encodeFlashCookie(url: string, result: any, input: any[], thrown?: boolean): string;
+
+/**
+ * Decodes the flash cookie out of a request's `Cookie` header, for the
+ * render that follows the redirect. Returns undefined when the cookie is
+ * absent or unreadable — a malformed cookie never takes down the render,
+ * and `clearFlashCookie` should be appended regardless.
+ */
+export function decodeFlashCookie(cookieHeader: string | null): FlashSubmission | undefined;

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

@@ -0,0 +1,10 @@
+/**
+ * Opt-in codec encoding for server-function ARGUMENTS. By default the client
+ * sends argument lists as plain JSON (no serializer in the bundle) and
+ * throws on values JSON can't carry faithfully. Call once at startup to
+ * send Dates, Maps, Sets, typed arrays, cyclic structures, etc. through the
+ * codec — at the cost of the serializer's write half (~5 KB gz on top of
+ * the decode half responses already need). The handler accepts both
+ * encodings unconditionally.
+ */
+export function enableRichArguments(): void;