@solidjs/web 2.0.0-beta.27 → 2.0.0-beta.29

package/types-cjs/index.d.cts

@@ -176,3 +176,77 @@ export declare function dynamic<T extends ValidComponent>(source: () => T | Prom
  * @description https://docs.solidjs.com/reference/components/dynamic
  */
 export declare function Dynamic<T extends ValidComponent>(props: DynamicProps<T>): JSX.Element;
+/**
+ * Wraps a dynamically imported component so it renders only in the browser.
+ * The server renders `props.fallback` (and nothing else); the client shows
+ * the fallback until the import resolves and the tree has mounted, then
+ * swaps the real component in.
+ *
+ * Unlike `lazy()`, this avoids Suspense entirely and never server-renders
+ * the wrapped component — only the fallback — so the component participates
+ * in no hydration asset manifest and its code is guaranteed to never run on
+ * the server (safe for browser-only libraries touching `window`, DOM
+ * measurement, etc.). The mount gate keeps hydration safe: during hydration
+ * the fallback is rendered exactly as the server did, and the swap happens
+ * only after settle, so there is no mismatch.
+ *
+ * By default the import starts as soon as `clientOnly` is called (module
+ * load); pass `{ lazy: true }` to defer the import to the component's first
+ * render.
+ *
+ * @example
+ * ```tsx
+ * const Chart = clientOnly(() => import("./Chart.jsx"));
+ * // <Chart fallback={<div>Loading chart…</div>} data={data()} />
+ * ```
+ */
+export declare function clientOnly<T extends Component<any>>(fn: () => Promise<{
+    default: T;
+}>, options?: {
+    lazy?: boolean;
+}): Component<ComponentProps<T> & {
+    fallback?: JSX.Element;
+}>;
+/**
+ * Declares the HTTP response status (and optional status text) for the
+ * lifetime of the current reactive scope during SSR — call it bare in a
+ * component or reactive-scope body where the status is decided (a 404
+ * route, an error fallback). Client build: a no-op — the response head was
+ * sent long ago.
+ *
+ * Naming note — this is a scope-tied *declaration*, not a mutation: "while
+ * this reactive scope is live, the response has this status." Solid
+ * reserves `set*` verbs for event-time mutation; like
+ * `createSignal`/`onCleanup` this is called in scope bodies and un-declares
+ * on scope disposal.
+ *
+ * Retraction semantics (server): the write snapshots the previous
+ * `event.response` status at write time and restores it when the owning
+ * scope is disposed — so a boundary that errored, declared a status, and
+ * then recovered retracts its write instead of stomping a status a
+ * surviving part of the tree legitimately set. Once the integration marks
+ * the response head `committed` (head derived/sent), writes and
+ * retractions are no-ops.
+ */
+export declare function httpStatus(_code: number, _text?: string): void;
+/**
+ * Declares an HTTP response header (or with `append`, appends to one) for
+ * the lifetime of the current reactive scope during SSR — call it bare in a
+ * component or reactive-scope body. Client build: a no-op — the response
+ * head was sent long ago.
+ *
+ * Naming note — this is a scope-tied *declaration*, not a mutation: "while
+ * this reactive scope is live, the response has this header." Solid
+ * reserves `set*` verbs for event-time mutation; like
+ * `createSignal`/`onCleanup` this is called in scope bodies and un-declares
+ * on scope disposal.
+ *
+ * Retraction semantics (server): the header's prior value is snapshotted at
+ * write time and restored when the owning scope is disposed (deleted if
+ * there was none) — a boundary that errors or recovers retracts its writes.
+ * Once the integration marks the response head `committed` (head
+ * derived/sent), writes and retractions are no-ops.
+ */
+export declare function httpHeader(_name: string, _value: string, _options?: {
+    append?: boolean;
+}): void;

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

@@ -2,21 +2,29 @@ import { JSONCodecOptions } from "../serializer.cjs";
 import { ServerFunction, ServerFunctionMetadata } from "./shared.cjs";
 
 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,
   subscribeFlightData,
   withMeta
 } from "./shared.cjs";
+export { REVALIDATE_HEADER } from "../response.cjs";
 export type {
   FlightDataConsumer,
   FlightDataContext,
@@ -173,3 +181,20 @@ export function createServerReference(id: string, name?: string, base?: string):
  * @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-cjs/server-functions/server.d.cts

@@ -11,6 +11,7 @@ export {
   clearFlashCookie,
   decodeErrorHeaderValue,
   decodeResponse,
+  decodeResponsePayload,
   encodeErrorHeaderValue,
   getServerFunctionMetadata,
   hasFlashCookie,
@@ -31,8 +32,9 @@ import { ServerFunction } from "./shared.cjs";
 
 /**
  * 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.
+ * `RequestEvent` (request + locals) with `serverOnly` added, set when the
+ * call is an in-process SSR invocation whose result never serializes to a
+ * client.
  */
 export interface ServerFunctionEvent extends RequestEvent {
   serverOnly?: boolean;
@@ -68,6 +70,29 @@ export interface ServerFunctionOutcome {
   request: Request;
   /** Whether the result was thrown rather than returned. */
   thrown: boolean;
+  /**
+   * The URL the client will show after the mutation — the redirect
+   * `Location` when the outcome carries one (resolved against the request
+   * URL, as a browser would), the referring page otherwise. Undefined
+   * without a usable referer (a non-browser caller has no page to produce
+   * data for) and for redirects leaving the app's origin: produce no data
+   * when this is undefined.
+   */
+  targetUrl: string | undefined;
+  /**
+   * The outcome's `X-Revalidate` keys, split — the invalidation scope the
+   * mutation declared. Undefined when the outcome carries none (integrations
+   * typically collect everything for the target in that case).
+   */
+  revalidateKeys: string[] | undefined;
+  /**
+   * The request headers with the mutation's cookie effects applied: the
+   * event response's `Set-Cookie`s (set during the call), then the
+   * outcome's own (e.g. `redirect(to, { headers })`), later winning on
+   * conflict, deletions honored. Build the data-collection request from
+   * these so re-run reads observe post-mutation cookie state.
+   */
+  foldedHeaders: Headers;
 }
 
 /**
@@ -82,8 +107,12 @@ export interface ServerFunctionOutcome {
  * 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.
+ * errors never collect, and neither do raw body-carrying `Response` values
+ * — those are the caller's verbatim payload). The handler owns the
+ * enveloping: contributed data ships as `{ value, data }` under the
+ * single-flight response header. The generic halves of collection arrive
+ * pre-digested on the outcome (`targetUrl`, `revalidateKeys`,
+ * `foldedHeaders`); the hook supplies only the data strategy.
  */
 export type CollectFlightDataHook = (
   event: ServerFunctionEvent,
@@ -168,13 +197,36 @@ export interface ServerFunctionsServerConfig {
   transformResult?(
     event: ServerFunctionEvent,
     result: unknown,
-    context: { instance: string | null; request: Request; thrown?: boolean }
+    context: {
+      id: string;
+      args: unknown[];
+      instance: string | null;
+      request: Request;
+      thrown?: boolean;
+    }
   ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
+  /**
+   * `transformResult`'s counterpart for the single-flight fold: when a
+   * call's flight payload needs a body only a policy knows how to build
+   * (frames' `frameTransformFlightResult` — an invalidated entry is
+   * markup), this gets first refusal on the `{ value, data }` outcome.
+   * Return a `Response` to carry the outcome (call headers and cookies are
+   * copied onto it), or `undefined` to decline and keep the plain
+   * serialized envelope. A per-request option overrides it.
+   */
+  transformFlightResult?(
+    event: ServerFunctionEvent,
+    outcome: { value: unknown; data: unknown },
+    context: { id: string; args: unknown[]; instance: string | null; request: Request }
+  ): Response | undefined | Promise<Response | undefined>;
   /**
    * The in-process mirror of `transformResult` for direct (same-server)
    * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
    */
-  transformDirectResult?(value: unknown, options: { id: string }): unknown;
+  transformDirectResult?(
+    value: unknown,
+    options: { id: string; args: unknown[]; event: ServerFunctionEvent }
+  ): unknown;
   /**
    * Server-wide response builder for calls made without the client runtime
    * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
@@ -305,17 +357,33 @@ 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 {
+/** Identity of the currently executing server function call. */
+export interface ServerFunctionInvocation {
   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.
+ * Reads the in-flight server function invocation (its id) for 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.
+ * The state lives in a module-private WeakMap keyed by the per-call request
+ * event (never in `event.locals`, which derived events share with their
+ * outer event). Distinct from `getServerFunctionMetadata(fn)`, which reads
+ * a reference's static declaration metadata; this describes the call
+ * currently executing.
+ */
+export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
+
+/**
+ * The event-keyed half of `getServerFunctionInvocation`, for callers handed
+ * an event outside its provideEvent scope (the handler's result transforms
+ * run after the scope has exited). Integration plumbing — application code
+ * reads the ambient accessor instead.
+ * @internal
  */
-export function getServerFunctionMeta(): ServerFunctionMeta | undefined;
+export function getEventServerFunctionInvocation(
+  event: RequestEvent | undefined
+): ServerFunctionInvocation | undefined;
 
 /**
  * Hooks layering framework policy onto `handleServerFunctionRequest`.
@@ -339,16 +407,26 @@ export interface HandleServerFunctionOptions {
    * 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.
+   * calls. The context carries the call's identity — the function `id` and
+   * the parsed `args` the implementation was invoked with — matching the
+   * direct-call mirror (`transformDirectResult`), so a policy keying state
+   * by the call works over either dispatch path. 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 }
+    context: {
+      id: string;
+      args: unknown[];
+      instance: string | null;
+      request: Request;
+      thrown?: boolean;
+    }
   ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
   /**
    * Overrides the configured single-flight hook for this handler — same
@@ -356,6 +434,15 @@ export interface HandleServerFunctionOptions {
    * `CollectFlightDataHook`).
    */
   collectFlightData?: CollectFlightDataHook;
+  /**
+   * Overrides the configured single-flight fold policy for this handler —
+   * same contract as the `transformFlightResult` config option.
+   */
+  transformFlightResult?(
+    event: ServerFunctionEvent,
+    outcome: { value: unknown; data: unknown },
+    context: { id: string; args: unknown[]; instance: string | null; request: Request }
+  ): Response | undefined | Promise<Response | undefined>;
   /**
    * Builds the response for calls made without the client runtime (no
    * instance header — no-JS form posts, direct HTTP). Receives the

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

@@ -405,6 +405,19 @@ export function decodeResponse<T = unknown>(
   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
@@ -421,3 +434,12 @@ 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-cjs/server-mock.d.cts

@@ -63,7 +63,10 @@ export declare function renderToStringAsync<T>(fn: () => T, options?: {
  * 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`, plus a `then` for awaiting full completion.
+ * 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
@@ -73,7 +76,7 @@ export declare function renderToStringAsync<T>(fn: () => T, options?: {
  * renderToStream(() => <App />).pipe(res);
  *
  * // Web (Workers / Deno):
- * await renderToStream(() => <App />).pipeTo(stream.writable);
+ * return new Response(renderToStream(() => <App />).readable);
  * ```
  */
 export declare function renderToStream<T>(fn: () => T, options?: {
@@ -102,6 +105,7 @@ 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

package/types-cjs/server.d.cts

@@ -97,6 +97,17 @@ export function renderToStream<T>(
   then: (fn: (html: string) => void) => void;
   pipe: (writable: { write: (v: string) => void; end: () => void }) => void;
   pipeTo: (writable: WritableStream) => Promise<void>;
+  /**
+   * Lazy `ReadableStream<Uint8Array>` view of the render — hand it straight
+   * to `new Response(stream.readable)`. First access starts the render
+   * piping through an internal `TransformStream` (chunks are UTF-8 encoded
+   * bytes, the same as `pipeTo` writes) and the stream is cached, so
+   * repeated access returns the same instance. Like `pipe`/`pipeTo`, this
+   * consumes the render: use exactly one of the three — mixing distinct
+   * consumers (`readable` after `pipe`/`pipeTo`, or vice versa) throws an
+   * error naming the conflict.
+   */
+  readonly readable: ReadableStream<Uint8Array>;
 };
 
 export function HydrationScript(props: { nonce?: string; eventNames?: string[] }): JSX.Element;
@@ -140,10 +151,37 @@ export function generateHydrationScript(options?: {
  * @internal
  */
 export declare const RequestContext: unique symbol;
+/**
+ * The mutable response head an integration's handler exposes on the request
+ * event as `event.response`: status/statusText/headers it will apply when
+ * sending the response. A scaffold, not a `Response` — application code
+ * (e.g. JSX response components) writes to it during render, and the
+ * handler reads it when the head goes out. Core does not declare the
+ * `response` property on `RequestEvent` itself: integrations that provide
+ * one declare it through module augmentation (as `@solidjs/router` does),
+ * and this type names the shape they agree on. Core's server-function
+ * handler reads its `Set-Cookie` headers when folding single-flight
+ * cookies but never requires it.
+ */
+export interface ResponseStub {
+  status?: number;
+  statusText?: string;
+  headers: Headers;
+  /**
+   * Set by the integration once the response head has been derived/sent
+   * from this stub — status and headers can no longer change. Consumers
+   * that write response metadata during render (e.g. JSX response
+   * components) must treat later status/header writes and cleanup-time
+   * retractions as no-ops.
+   */
+  committed?: boolean;
+}
+
 /**
  * The per-request context available on the server: the incoming `Request`
  * and a `locals` bag integrations and middleware can hang state on.
- * Frameworks typically extend this shape with richer fields.
+ * Frameworks typically extend this shape with richer fields (e.g. a
+ * `response` head — see `ResponseStub`).
  */
 export interface RequestEvent {
   request: Request;