@solidjs/web 2.0.0-beta.3 → 2.0.0-beta.30

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

@@ -0,0 +1,445 @@
+import { JSONCodecOptions } from "../serializer.js";
+
+export type { JSONCodecOptions };
+
+/**
+ * Configures the codec options for the server function wire format (extra
+ * Seroval plugins, feature policy, depth limit). Both peers must configure
+ * identical options or payloads will not round-trip. Usually called
+ * indirectly through `configureServerFunctionsClient` /
+ * `configureServerFunctionsServer` (their `codec` option writes through to
+ * here); call it directly only from universal code configuring both sides
+ * at once.
+ */
+export function configureServerFunctionsCodec(codec: JSONCodecOptions | undefined): void;
+
+/**
+ * The currently configured codec options (set through
+ * `configureServerFunctionsCodec` or the client/server `codec` option), or
+ * undefined when running on the defaults. Integrations pass this to
+ * lower-level codec helpers so custom plugins configured by the app apply.
+ */
+export function getServerFunctionsCodec(): JSONCodecOptions | undefined;
+
+/**
+ * Request header carrying the server function id (`"X-Server-Function-Id"`).
+ * Integrations can read it to identify which function a request targets;
+ * the id also arrives as the `id` query parameter for GET calls and no-JS
+ * form posts.
+ */
+export const FUNCTION_HEADER: string;
+
+/**
+ * Request header carrying a per-call instance id
+ * (`"X-Server-Function-Instance"`). Its presence tells the server the call
+ * came through the client runtime — its absence marks a no-JS form post or
+ * direct HTTP call, which receive plain responses instead of codec-encoded
+ * ones.
+ */
+export const INSTANCE_HEADER: string;
+
+/**
+ * Response header marking a thrown server-function error
+ * (`"X-Server-Function-Error"`). The client transport rejects with the
+ * decoded body when it is present (unless redirect/revalidation metadata
+ * marks the response as control flow). The value carries the error's
+ * message — `"true"` for thrown control-flow responses and non-Error
+ * values — encoded with `encodeErrorHeaderValue`, so integrations reading
+ * it must pass it through `decodeErrorHeaderValue`.
+ */
+export const ERROR_HEADER: string;
+
+/**
+ * Encodes an error message for the `ERROR_HEADER` value. HTTP header values
+ * are latin1 ByteStrings — `Headers.set` throws on code points above U+00FF
+ * — so plain printable-latin1 messages ride verbatim (ASCII stays
+ * byte-identical on the wire) and everything else (CJK, emoji, controls)
+ * travels percent-encoded behind a marker. `decodeErrorHeaderValue`
+ * round-trips the message exactly, astral-plane characters included (lone
+ * surrogates are replaced with U+FFFD — they cannot survive UTF-8 anyway).
+ */
+export function encodeErrorHeaderValue(value: string): string;
+
+/**
+ * Decodes an `ERROR_HEADER` value produced by `encodeErrorHeaderValue`:
+ * marked values are percent-decoded, everything else (including values from
+ * peers that never encode) passes through untouched.
+ */
+export function decodeErrorHeaderValue(value: string): 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;
+
+/**
+ * Name of the cookie carrying the outcome of a call made without the client
+ * runtime (`"flash"`). A no-JS form post has no way to receive a value —
+ * the browser follows the redirect and renders the next page — so the
+ * handler stashes the outcome here for the render after it to pick up,
+ * which is how a form submitted without JavaScript still shows its result.
+ *
+ * The name, detection and clearing are isomorphic (integrations read the
+ * cookie from code that also ships to the browser); the codec that fills it
+ * is server-only and lives behind the server entry.
+ */
+export const FLASH_COOKIE: string;
+
+/**
+ * Whether a Cookie header carries a flash cookie, readable or not. Cheap
+ * enough to call on every render so the clear can be queued before the
+ * response headers flush.
+ */
+export function hasFlashCookie(cookieHeader: string | null): boolean;
+
+/**
+ * The `Set-Cookie` value clearing the flash cookie. The outcome is
+ * one-shot: append this as soon as the cookie is detected, whether or not
+ * it decodes, so a stale outcome cannot resurface on a later request.
+ */
+export function clearFlashCookie(): string;
+
+/**
+ * The raw encoded flash payload out of a Cookie header, if present — the
+ * codec's own accessor.
+ *
+ * @internal
+ */
+export function matchFlashCookie(cookieHeader: string | null): string | undefined;
+
+/**
+ * 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"`.
+ *
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
+ */
+export const BODY_FORMAT_HEADER: string;
+
+/**
+ * FormData key used when a lone File is sent as the argument.
+ *
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
+ */
+export const FILE_FORM_KEY: string;
+
+/**
+ * Wire tags naming how a request/response body was encoded, carried in
+ * `BODY_FORMAT_HEADER`.
+ *
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
+ */
+export const BodyFormat: {
+  readonly Serialized: "0";
+  readonly String: "1";
+  readonly FormData: "2";
+  readonly URLSearchParams: "3";
+  readonly Blob: "4";
+  readonly File: "5";
+  readonly ArrayBuffer: "6";
+  readonly Uint8Array: "7";
+};
+
+/**
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
+ */
+export type BodyFormatValue = (typeof BodyFormat)[keyof typeof BodyFormat];
+
+/**
+ * Picks a direct HTTP encoding (headers + BodyInit) for values that have
+ * one — strings, FormData, URLSearchParams, File, Blob, ArrayBuffer,
+ * Uint8Array. Returns undefined when the value needs the serializer.
+ *
+ * Transport building block used by the fetch transport and the HTTP
+ * handler; not meant for hand-written code.
+ * @internal
+ */
+export function getHeadersAndBody(
+  body: unknown
+): { headers?: Record<string, string>; body: BodyInit } | undefined;
+
+/**
+ * Decodes a Request/Response body according to its `BODY_FORMAT_HEADER`
+ * tag (falling back to content-type sniffing for form posts that never saw
+ * the client runtime). The inverse of `getHeadersAndBody` + the serialized
+ * stream. Resolves undefined for bodies without a recognized encoding.
+ *
+ * Transport building block; use `decodeResponse` from integration code.
+ * @internal
+ */
+export function extractBody(
+  source: Request | Response,
+  codecOptions?: JSONCodecOptions
+): Promise<unknown>;
+
+/**
+ * Serializes a value as a stream of length-prefixed SerovalNode chunks.
+ * Async values (promises, streams) keep the stream open until they settle,
+ * so one connection carries incremental results. Codec options must match
+ * the deserializing peer.
+ *
+ * Transport building block; not meant for hand-written code.
+ * @internal
+ */
+export function serializeStream(
+  value: unknown,
+  codecOptions?: JSONCodecOptions
+): ReadableStream<Uint8Array>;
+
+/**
+ * `serializeStream` drained to a string (async values fully awaited).
+ *
+ * Transport building block; not meant for hand-written code.
+ * @internal
+ */
+export function serializeString(value: unknown, codecOptions?: JSONCodecOptions): Promise<string>;
+
+/**
+ * Decodes a framed chunk stream from a Request/Response body. Resolves with
+ * the first chunk's value (the source value); later chunks settle the async
+ * values referenced inside it as they arrive.
+ *
+ * Transport building block; use `decodeResponse` from integration code.
+ * @internal
+ */
+export function deserializeStream<T = unknown>(
+  source: Request | Response,
+  codecOptions?: JSONCodecOptions
+): Promise<T>;
+
+/**
+ * `deserializeStream` for an already-buffered string.
+ *
+ * Transport building block; not meant for hand-written code.
+ * @internal
+ */
+export function deserializeString<T = unknown>(
+  text: string,
+  codecOptions?: JSONCodecOptions
+): Promise<T>;
+
+/**
+ * Decodes a server function response body using the configured codec. This
+ * is the integration-facing decoder: routers call it on responses the
+ * transport hands over whole — redirects, revalidation, single-flight
+ * payloads — to recover the structured value inside. Resolves undefined for
+ * empty bodies and bodies without a recognized encoding (e.g. a raw user
+ * Response). Renderer- and platform-neutral: safe to use from universal
+ * code.
+ *
+ * @param response the transport response; its body is read from a clone,
+ * so the original stays readable
+ * @param codecOptions overrides the configured codec for this call
+ */
+export function decodeResponse<T = unknown>(
+  response: Response,
+  codecOptions?: JSONCodecOptions
+): Promise<T | undefined>;
+
+/**
+ * `decodeResponse` plus the single-flight envelope split: when the response
+ * carries the single-flight header the decoded `{ value, data }` payload is
+ * unwrapped into `{ value, flightData }`; otherwise the decoded body (or
+ * undefined for body-less responses) rides as `{ value }`. Integrations
+ * that apply response metadata themselves use this so the payload shape
+ * stays core's own.
+ */
+export function decodeResponsePayload<T = unknown, D = unknown>(
+  response: Response,
+  codecOptions?: JSONCodecOptions
+): Promise<{ value: T | undefined; flightData?: D }>;
+
+/**
+ * Frame one payload for the server-function wire: a `;0x<len32>;` length
+ * prefix followed by the utf-8 data. Both transports (server-function
+ * responses and frame streams) share this framing.
+ */
+export function createChunk(data: string): Uint8Array;
+
+/**
+ * Incremental decoder for `createChunk` framing over a byte stream: `next()`
+ * yields one complete payload string per call (async-iterator result shape),
+ * buffering partial frames internally until their length prefix is satisfied.
+ */
+export class ChunkReader {
+  constructor(stream: ReadableStream<Uint8Array>);
+  next(): Promise<{ done: boolean; value: string | undefined }>;
+}
+
+/**
+ * The intrinsic wire address of a server-component call: the function id,
+ * suffixed with a realm-stable hash of the arguments when there are any.
+ * Both peers derive it independently — the server names flight regions with
+ * it, the client routes them by it — so it must stay deterministic across
+ * realms and releases.
+ */
+export function frameAddress(id: string, args?: readonly unknown[]): string;

package/types/server-mock.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Renders a component tree synchronously to an HTML string. Async reads inside
+ * `<Loading>` boundaries emit their `fallback` content; for full-graph
+ * resolution use `renderToStringAsync` instead.
+ *
+ * Pair the returned HTML with `hydrate()` on the client.
+ *
+ * @example
+ * ```tsx
+ * import { renderToString } from "@solidjs/web";
+ *
+ * const html = renderToString(() => <App />);
+ * res.send(`<!doctype html><html><body><div id="root">${html}</div></body></html>`);
+ * ```
+ */
 export declare function renderToString<T>(fn: () => T, options?: {
     nonce?: string;
     renderId?: string;
@@ -12,6 +27,21 @@ export declare function renderToString<T>(fn: () => T, options?: {
     }>;
     onError?: (err: any) => void;
 }): string;
+/**
+ * Renders a component tree to an HTML string and awaits all async reads in the
+ * subtree before resolving. The returned HTML reflects the fully-settled state
+ * — no `<Loading>` fallbacks appear in the output.
+ *
+ * Use this when you want a complete page in one round-trip. For incremental
+ * streaming with progressive boundary resolution, use `renderToStream`.
+ *
+ * @example
+ * ```tsx
+ * import { renderToStringAsync } from "@solidjs/web";
+ *
+ * const html = await renderToStringAsync(() => <App />);
+ * ```
+ */
 export declare function renderToStringAsync<T>(fn: () => T, options?: {
     timeoutMs?: number;
     nonce?: string;
@@ -27,6 +57,28 @@ export declare function renderToStringAsync<T>(fn: () => T, options?: {
     }>;
     onError?: (err: any) => void;
 }): Promise<string>;
+/**
+ * Streams an HTML response, flushing the synchronous shell first and then
+ * progressively emitting async-resolved fragments as their `<Loading>`
+ * boundaries settle. Good for time-to-first-byte sensitive pages.
+ *
+ * Returns an object with `pipe`/`pipeTo` for piping to a Node `Writable` or
+ * a Web `WritableStream`, a lazy `readable` byte-stream view for
+ * `new Response(stream.readable)`, plus a `then` for awaiting full
+ * completion. `pipe`, `pipeTo`, and `readable` each consume the render —
+ * use exactly one of the three.
+ *
+ * @example
+ * ```tsx
+ * import { renderToStream } from "@solidjs/web";
+ *
+ * // Node:
+ * renderToStream(() => <App />).pipe(res);
+ *
+ * // Web (Workers / Deno):
+ * return new Response(renderToStream(() => <App />).readable);
+ * ```
+ */
 export declare function renderToStream<T>(fn: () => T, options?: {
     nonce?: string;
     renderId?: string;
@@ -53,20 +105,61 @@ export declare function renderToStream<T>(fn: () => T, options?: {
         end: () => void;
     }) => void;
     pipeTo: (writable: WritableStream) => Promise<void>;
+    readonly readable: ReadableStream<Uint8Array>;
 };
+/**
+ * Compiler primitive — emitted by JSX-DOM-Expressions for tagged-template
+ * SSR output. Not meant for hand-written code.
+ * @internal
+ */
 export declare function ssr(template: string[] | string, ...nodes: any[]): {
     t: string;
 };
+/**
+ * Compiler primitive — emitted by JSX-DOM-Expressions for SSR element
+ * output. Not meant for hand-written code.
+ * @internal
+ */
 export declare function ssrElement(name: string, props: any, children: any, needsId: boolean): {
     t: string;
 };
+/**
+ * Compiler primitive — serializes a classList object for SSR output. Not
+ * meant for hand-written code.
+ * @internal
+ */
 export declare function ssrClassList(value: {
     [k: string]: boolean;
 }): string;
+/**
+ * Compiler primitive — serializes a style object for SSR output. Not meant
+ * for hand-written code.
+ * @internal
+ */
 export declare function ssrStyle(value: {
     [k: string]: string;
 }): string;
+/**
+ * Compiler primitive — serializes a boolean attribute for SSR output. Not
+ * meant for hand-written code.
+ * @internal
+ */
 export declare function ssrAttribute(key: string, value: boolean): string;
+/**
+ * Compiler primitive — generates the hydration-key attribute for SSR
+ * output. Not meant for hand-written code.
+ * @internal
+ */
 export declare function ssrHydrationKey(): string;
+/**
+ * Compiler primitive — collapses an SSR-shaped node into its HTML string.
+ * Not meant for hand-written code.
+ * @internal
+ */
 export declare function resolveSSRNode(node: any): string;
+/**
+ * Escapes a string for safe inclusion in HTML output. Used by the SSR
+ * runtime; not generally part of user code.
+ * @internal
+ */
 export declare function escape(html: string): string;