@solidjs/web 2.0.0-beta.31 → 2.0.0-beta.33

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

@@ -1,4 +1,4 @@
-import { JSONCodecOptions } from "../serializer.js";
+import { JSONCodecOptions } from "../serializer-decode.js";
 
 export type { JSONCodecOptions };
 
@@ -18,6 +18,9 @@ export function configureServerFunctionsCodec(codec: JSONCodecOptions | undefine
  * `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.
+ *
+ * Integration plumbing; not meant for hand-written application code.
+ * @internal
  */
 export function getServerFunctionsCodec(): JSONCodecOptions | undefined;
 
@@ -57,6 +60,9 @@ export const ERROR_HEADER: string;
  * 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).
+ *
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
  */
 export function encodeErrorHeaderValue(value: string): string;
 
@@ -64,6 +70,10 @@ 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.
+ *
+ * Integration plumbing for readers of `ERROR_HEADER`; not meant for
+ * hand-written application code.
+ * @internal
  */
 export function decodeErrorHeaderValue(value: string): string;
 
@@ -273,6 +283,46 @@ export function withMeta<F extends (...args: any[]) => any>(fn: F, meta: ServerF
  */
 export const SERVER_FUNCTION_METADATA: unique symbol;
 
+/**
+ * The transport surface integrations consume through the late-bound RPC
+ * seam (server-functions/registry.js) — filled by the transport halves when
+ * the first server function reference is created (code that only exists in
+ * a bundle when a `"use server"` function was actually compiled in), read
+ * by routers so they never import the transport/codec statically.
+ */
+export interface ServerFunctionRPC {
+  /**
+   * The build's `GET` declaration wrapper (client fetch transport or
+   * server in-process dispatch — see the respective entries).
+   */
+  GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
+  /**
+   * `decodeResponse` bound to the configured codec: decodes a server
+   * function response body the transport handed over whole (redirects,
+   * revalidation). Resolves undefined for empty bodies and bodies without
+   * a recognized encoding (e.g. a raw user Response).
+   */
+  decodeResponse<T = unknown>(response: Response): Promise<T | undefined>;
+}
+
+/**
+ * Fills the RPC seam. Called by the transport halves when the first server
+ * function reference is created; first write wins.
+ * @internal
+ */
+export function provideServerFunctionRPC(rpc: ServerFunctionRPC): void;
+
+/**
+ * The registered RPC surface, or undefined when no server function exists
+ * in this build's graph. Integration plumbing (routers): gate every use of
+ * the transport/codec behind this read instead of importing it — an app
+ * with no server functions then ships none of it, while a reference in the
+ * bundle guarantees the seam is filled before integration code can hold
+ * that reference (compiled output creates references at module scope).
+ * @internal
+ */
+export function getServerFunctionRPC(): ServerFunctionRPC | undefined;
+
 /**
  * Header carrying the body format tag (a `BodyFormat` value) —
  * `"X-Server-Function-Format"`.
@@ -306,6 +356,11 @@ export const BodyFormat: {
   readonly File: "5";
   readonly ArrayBuffer: "6";
   readonly Uint8Array: "7";
+  /**
+   * Plain `JSON.stringify` — the fast path for JSON-safe payloads on both
+   * legs: argument lists on the request, results on the response.
+   */
+  readonly Json: "8";
 };
 
 /**
@@ -314,6 +369,17 @@ export const BodyFormat: {
  */
 export type BodyFormatValue = (typeof BodyFormat)[keyof typeof BodyFormat];
 
+/**
+ * Whether a value survives a `JSON.stringify` round trip faithfully: JSON
+ * primitives (finite numbers only), arrays, and plain objects. Anything
+ * else — Dates, Maps, typed arrays, undefined (bare or as a property),
+ * NaN, class instances, cyclic structures — needs the codec. Never throws:
+ * cycles and pathological depth answer `false`. Both peers negotiate the
+ * wire format with this guard: the client for argument lists, the server
+ * for results.
+ */
+export function isJSONSafe(value: unknown): boolean;
+
 /**
  * Picks a direct HTTP encoding (headers + BodyInit) for values that have
  * one — strings, FormData, URLSearchParams, File, Blob, ArrayBuffer,
@@ -412,6 +478,9 @@ export function decodeResponse<T = unknown>(
  * undefined for body-less responses) rides as `{ value }`. Integrations
  * that apply response metadata themselves use this so the payload shape
  * stays core's own.
+ *
+ * Integration plumbing; not meant for hand-written application code.
+ * @internal
  */
 export function decodeResponsePayload<T = unknown, D = unknown>(
   response: Response,
@@ -422,6 +491,9 @@ export function decodeResponsePayload<T = unknown, D = unknown>(
  * 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.
+ *
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
  */
 export function createChunk(data: string): Uint8Array;
 
@@ -429,6 +501,9 @@ 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.
+ *
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
  */
 export class ChunkReader {
   constructor(stream: ReadableStream<Uint8Array>);
@@ -441,5 +516,8 @@ export class ChunkReader {
  * 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.
+ *
+ * Transport wire detail; not meant for hand-written code.
+ * @internal
  */
 export function frameAddress(id: string, args?: readonly unknown[]): string;

package/types/server-mock.d.ts

@@ -1,7 +1,48 @@
+import type { RequestEvent, RequestEventLocals, ResponseStub } from "./client.js";
+/** Static asset manifest produced by a build (e.g. parsed Vite manifest.json). */
+export type AssetManifest = Record<string, {
+    file: string;
+    css?: string[];
+    isEntry?: boolean;
+    imports?: string[];
+}> & {
+    _base?: string;
+};
+/** Inline style content, e.g. dev CSS collected from a bundler's module graph. */
+export type InlineStyleAsset = {
+    id: string;
+    content: string;
+    attrs?: Record<string, string>;
+};
+export type ResolvedAssets = {
+    js: string[];
+    css: (string | InlineStyleAsset)[];
+};
+/**
+ * Resolver form of the manifest option — the primitive a dev server
+ * implements against its live module graph (a static manifest object is
+ * normalized into a sync resolver internally). `resolve` may return a
+ * promise (async resolvers require streaming rendering); CSS entries may be
+ * URL strings (emitted as load-gated `<link>` tags) or inline-style
+ * descriptors (emitted as `<style>` tags). A bare `resolve`-shaped function
+ * is accepted as shorthand for `{ resolve }`.
+ */
+export type AssetResolver = {
+    resolve(key: string): ResolvedAssets | null | undefined | Promise<ResolvedAssets | null | undefined>;
+    /**
+     * Synchronous fast path answering with whatever is knowable without async
+     * work (typically js URLs, omitting css). Sync consumers — e.g. a lazy
+     * component's `moduleUrl` getter used by islands — use this when `resolve`
+     * would return a promise, so adapters should provide it whenever possible.
+     */
+    resolveSync?(key: string): ResolvedAssets | null | undefined;
+};
+/** Bare-function shorthand for `AssetResolver` (no sync fast path). */
+export type AssetResolverFn = (key: string) => ResolvedAssets | null | undefined | Promise<ResolvedAssets | null | undefined>;
 /**
  * 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.
+ * resolution await `renderToStream` instead.
  *
  * Pair the returned HTML with `hydrate()` on the client.
  *
@@ -18,45 +59,20 @@ export declare function renderToString<T>(fn: () => T, options?: {
     renderId?: string;
     noScripts?: boolean;
     plugins?: any[];
-    manifest?: Record<string, {
-        file: string;
-        css?: string[];
-        isEntry?: boolean;
-        isDynamicEntry?: boolean;
-        imports?: string[];
-    }>;
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onError?: (err: any) => void;
+    /**
+     * Embedded-render contract for hosts that own the document. When the
+     * render output contains no `</head>`, everything head-bound (resolved
+     * `useHead` winners, eager resources, tracked asset links, inline
+     * styles) is delivered here as one HTML string — prelude (charset/base)
+     * first — for the host to splice into its own `<head>` template, instead
+     * of being dropped. Called synchronously before `renderToString`
+     * returns; not called when the output has a `</head>` (splicing is
+     * automatic then).
+     */
+    onHead?: (head: string) => 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;
-    renderId?: string;
-    noScripts?: boolean;
-    plugins?: any[];
-    manifest?: Record<string, {
-        file: string;
-        css?: string[];
-        isEntry?: boolean;
-        isDynamicEntry?: boolean;
-        imports?: string[];
-    }>;
-    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>`
@@ -64,9 +80,10 @@ export declare function renderToStringAsync<T>(fn: () => T, options?: {
  *
  * 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.
+ * `new Response(stream.readable)`, plus a thenable for awaiting full
+ * completion — `await renderToStream(...)` resolves with the settled HTML
+ * (the fully-resolved-string form of the render). `pipe`, `pipeTo`, and
+ * `readable` each consume the render — use exactly one of the three.
  *
  * @example
  * ```tsx
@@ -77,6 +94,9 @@ export declare function renderToStringAsync<T>(fn: () => T, options?: {
  *
  * // Web (Workers / Deno):
  * return new Response(renderToStream(() => <App />).readable);
+ *
+ * // Fully settled string:
+ * const html = await renderToStream(() => <App />);
  * ```
  */
 export declare function renderToStream<T>(fn: () => T, options?: {
@@ -84,13 +104,7 @@ export declare function renderToStream<T>(fn: () => T, options?: {
     renderId?: string;
     noScripts?: boolean;
     plugins?: any[];
-    manifest?: Record<string, {
-        file: string;
-        css?: string[];
-        isEntry?: boolean;
-        isDynamicEntry?: boolean;
-        imports?: string[];
-    }>;
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onCompleteShell?: (info: {
         write: (v: string) => void;
     }) => void;
@@ -98,8 +112,25 @@ export declare function renderToStream<T>(fn: () => T, options?: {
         write: (v: string) => void;
     }) => void;
     onError?: (err: any) => void;
+    /**
+     * Embedded-render contract for hosts that own the document. When the
+     * shell contains no `</head>`, everything head-bound at first flush
+     * (resolved `useHead` winners, eager resources, tracked asset links,
+     * inline styles) is delivered here as one HTML string — prelude first —
+     * before the shell chunk is emitted, so the host can write its own
+     * `<head>` ahead of piping the stream. Post-shell head updates flow
+     * through the stream itself and apply in the browser. Not called when
+     * the shell has a `</head>` (splicing is automatic then).
+     */
+    onHead?: (head: string) => void;
 }): {
-    then: (fn: (html: string) => void) => void;
+    /**
+     * Awaiting the stream resolves with the complete HTML once every boundary
+     * settles — the fully-settled-string form of the render. Render errors
+     * route through `onError` and the promise resolves with whatever HTML the
+     * render produced; it never rejects.
+     */
+    then<TResult1 = string, TResult2 = never>(onfulfilled?: ((html: string) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     pipe: (writable: {
         write: (v: string) => void;
         end: () => void;
@@ -107,6 +138,75 @@ export declare function renderToStream<T>(fn: () => T, options?: {
     pipeTo: (writable: WritableStream) => Promise<void>;
     readonly readable: ReadableStream<Uint8Array>;
 };
+/**
+ * Fetch-style middleware: receives the `Request` and a `next` continuation
+ * (pass a `Request` to substitute it downstream) and returns the `Response`.
+ * Composed with `composeMiddleware`; runs inside the request-event scope, so
+ * `getRequestEvent()` works exactly as in application code.
+ */
+export type FetchMiddleware = (request: Request, next: (request?: Request) => Promise<Response>) => Response | Promise<Response>;
+/**
+ * Creates a fresh, uncommitted {@link ResponseStub}. Server-only.
+ */
+export declare function createResponseStub(): ResponseStub;
+/**
+ * Builds the canonical request event — a web-standard `Request`, a `locals`
+ * bag, and a stub-backed `response` head — for `provideRequestEvent`.
+ * Server-only: on the client the request event belongs to the server that
+ * rendered the page.
+ */
+export declare function createRequestEvent<T extends object = {}>(request: Request, init?: T): {
+    request: Request;
+    locals: RequestEventLocals;
+    response: ResponseStub;
+} & T;
+/**
+ * The HTTP status a redirect should use: the stub's own status when it is a
+ * redirect status (301/302/303/307/308), 302 otherwise. Server-only.
+ */
+export declare function getExpectedRedirectStatus(response: ResponseStub): number;
+/**
+ * Derives the outgoing `Response` for an SSR render result, running the
+ * response-head lifecycle against `event.response`: the stub commits at
+ * shell flush, a pre-flush `Location` becomes a real redirect
+ * (`getExpectedRedirectStatus`), and a post-flush one appends the
+ * nonce-aware `<script>window.location=...</script>` fallback. String
+ * results return a `Response` synchronously; stream results resolve at
+ * shell flush. Server-only.
+ */
+export declare function createSSRResponse(result: string, event: RequestEvent | undefined, options?: {
+    responseInit?: ResponseInit;
+    nonce?: string;
+    transformChunk?: (chunk: string) => string;
+}): Response;
+export declare function createSSRResponse(result: {
+    pipe(writable: {
+        write: (v: string) => void;
+        end: () => void;
+    }): void;
+}, event: RequestEvent | undefined, options?: {
+    responseInit?: ResponseInit;
+    nonce?: string;
+    transformChunk?: (chunk: string) => string;
+}): Promise<Response>;
+/**
+ * Handler-lifecycle plumbing — the exit for a `Response` that did not go
+ * through `createSSRResponse` (a middleware early return, an API result):
+ * folds the request event's response stub onto it (cookies append
+ * entry-by-entry, other headers gap-fill, status never) and commits the
+ * stub. Already-committed stubs pass the response through untouched, so
+ * handlers apply it unconditionally after their middleware chain unwinds.
+ * `event` defaults to the ambient `getRequestEvent()`. Application
+ * middleware never calls this. Server-only.
+ */
+export declare function commitEventResponse(response: Response, event?: RequestEvent): Response;
+/**
+ * Composes fetch-style middleware — `(request, next) => Response` — into a
+ * single function of the same shape. Nothing reaches the wire until the
+ * outermost middleware returns, so headers on the returned `Response` stay
+ * mutable through the whole unwind, streamed bodies included. Server-only.
+ */
+export declare function composeMiddleware(middlewares: FetchMiddleware[]): (request: Request, next: (request?: Request) => Response | Promise<Response>) => Promise<Response>;
 /**
  * Compiler primitive — emitted by JSX-DOM-Expressions for tagged-template
  * SSR output. Not meant for hand-written code.
@@ -124,27 +224,39 @@ export declare function ssrElement(name: string, props: any, children: any, need
     t: string;
 };
 /**
- * Compiler primitive — serializes a classList object for SSR output. Not
- * meant for hand-written code.
+ * Compiler primitive — serializes a class value (string, object map, or
+ * array) for SSR output. Not meant for hand-written code.
  * @internal
  */
-export declare function ssrClassList(value: {
+export declare function ssrClassName(value: string | {
     [k: string]: boolean;
-}): string;
+} | Array<any>): string;
 /**
- * Compiler primitive — serializes a style object for SSR output. Not meant
+ * Compiler primitive — serializes a style value for SSR output. Not meant
  * for hand-written code.
  * @internal
  */
-export declare function ssrStyle(value: {
+export declare function ssrStyle(value: string | {
     [k: string]: string;
 }): string;
 /**
- * Compiler primitive — serializes a boolean attribute for SSR output. Not
+ * Compiler primitive — serializes one style property for SSR output. Not
+ * meant for hand-written code.
+ * @internal
+ */
+export declare function ssrStyleProperty(name: string, value: any): string;
+/**
+ * Compiler primitive — serializes an attribute for SSR output. Not meant
+ * for hand-written code.
+ * @internal
+ */
+export declare function ssrAttribute(key: string, value: any): string;
+/**
+ * Compiler primitive — wraps a template-group closure for SSR output. Not
  * meant for hand-written code.
  * @internal
  */
-export declare function ssrAttribute(key: string, value: boolean): string;
+export declare function ssrGroup<T extends () => any[]>(fn: T, n: number): T;
 /**
  * Compiler primitive — generates the hydration-key attribute for SSR
  * output. Not meant for hand-written code.
@@ -156,10 +268,10 @@ export declare function ssrHydrationKey(): string;
  * Not meant for hand-written code.
  * @internal
  */
-export declare function resolveSSRNode(node: any): string;
+export declare function resolveSSRNode(node: any, result?: any, top?: boolean): any;
 /**
  * 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;
+export declare function escape(s: any, attr?: boolean): any;