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

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

@@ -119,6 +119,33 @@ export type CollectFlightDataHook = (
   outcome: ServerFunctionOutcome
 ) => unknown | Promise<unknown>;
 
+/**
+ * Wraps a server function execution — the per-invocation seam for
+ * framework policies (per-function middleware, auth, logging, error
+ * mapping). Called inside the call's event scope with the invocation
+ * identity already established: `getServerFunctionInvocation()` answers
+ * before, during and after `run()`. Must return (or resolve to) `run()`'s
+ * result — replacing it replaces the function's result; throwing routes
+ * through the handler's normal error encoding.
+ *
+ * The context carries the call's identity (`id`, parsed `args`), its
+ * `event`, and how it arrived: `direct` is `true` for in-process SSR calls
+ * (where `request` is absent) and `false` for HTTP dispatch. On the direct
+ * path the wrapper must stay transparent for synchronous functions —
+ * return `run()`'s value, not an unconditional promise, unless it needs to
+ * be async.
+ */
+export type WrapInvocationHook = (
+  run: () => unknown,
+  context: {
+    id: string;
+    args: unknown[];
+    event: ServerFunctionEvent;
+    request?: Request;
+    direct: boolean;
+  }
+) => unknown;
+
 /**
  * Request headers with `setCookies` folded into the `Cookie` header, as the
  * browser would have applied them before its next request. Later entries
@@ -180,6 +207,14 @@ export interface ServerFunctionsServerConfig {
    * an established request scope parks on the global.
    */
   provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
+  /**
+   * Wraps every server function execution — HTTP dispatch and direct SSR
+   * calls alike — with the invocation identity already established (see
+   * `WrapInvocationHook`). The per-invocation seam for framework policies:
+   * per-function middleware, auth, logging, error mapping. A per-request
+   * option overrides it for HTTP dispatch.
+   */
+  wrapInvocation?: WrapInvocationHook;
   /**
    * The single-flight hook: produces the data payload folded into
    * responses of calls that opted in (see `CollectFlightDataHook`).
@@ -402,6 +437,13 @@ export interface HandleServerFunctionOptions {
    * contract as the `provideEvent` config option.
    */
   provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
+  /**
+   * Overrides the configured per-invocation wrap for this handler — same
+   * contract as the `wrapInvocation` config option (see
+   * `WrapInvocationHook`), except it only applies to HTTP dispatch (a
+   * per-request option can't see direct SSR calls).
+   */
+  wrapInvocation?: WrapInvocationHook;
   /**
    * Observes or replaces the function's result before encoding — the
    * extension point for response metadata policies (headers, statuses,
@@ -473,6 +515,41 @@ export interface HandleServerFunctionOptions {
  * (default `/_server`); platform adapters (h3, express, ...) convert their
  * request shape to a web `Request` around it.
  *
+ * When the event carries a `response` head stub (`event.response`, see the
+ * server entry's `ResponseStub`), the handler folds it onto every outgoing
+ * response as the head freezes — its `Set-Cookie` values (cookies appended
+ * during the call) append cookie-by-cookie alongside the result's own,
+ * other stub headers fill gaps (the call's response metadata wins; the
+ * protocol-owned family — the error/format/single-flight tags, `Location`,
+ * `X-Revalidate` — never fills, and neither does `Content-Type`/`Content-
+ * Length` onto a bodiless response) — and marks the stub `committed`, so
+ * later cookie/header writes report instead of silently missing the wire.
+ *
+ * ## Thrown-error sanitization (security default)
+ *
+ * A thrown `Response`/envelope (`redirect`/`reload`/`respond`) is intentional
+ * control flow and is forwarded untouched. A *plain* thrown value (a bare
+ * `Error`, string, or object) is different: serialized verbatim it would ship
+ * its `message` and every own-property to the client — a driver/ORM error's
+ * failing query, connection string, or bound parameters included. So outside
+ * the dev build a plain thrown value is replaced with a generic `Error`
+ * before serialization; the client still receives *an* `Error` (the shape
+ * `submission.error` etc. expect), just with no leaked content. The dev
+ * build keeps full fidelity (message, stack, own-props) for DX and the dev
+ * toolbar inspector. Dev/prod is the BUILD VARIANT, not `NODE_ENV`:
+ * `@solidjs/web` publishes a dev copy of this entry behind the
+ * `development` export condition (what Vite dev resolves) and the default
+ * resolution sanitizes — as does importing the runtime source directly with
+ * no bundler signal (fail-safe).
+ *
+ * Escape hatch: brand the value with `markSafeError` (`Symbol.for(
+ * "solid.SafeError")`) to send its content intact in every environment.
+ * A `wrapInvocation`/`transformResult` override that maps errors expresses
+ * intent the same way — throw a `Response`/envelope, or brand the mapped
+ * error safe; an unbranded plain error it lets propagate is sanitized like
+ * any other, so a framework onError policy must brand its result to keep a
+ * custom client-facing message in production.
+ *
  * @example
  * ```ts
  * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
@@ -488,3 +565,24 @@ export function handleServerFunctionRequest(
   request: Request,
   options?: HandleServerFunctionOptions
 ): Promise<Response>;
+
+/** Message a sanitized (production) server error carries on the wire. */
+export const GENERIC_SERVER_ERROR_MESSAGE: string;
+
+/**
+ * The production error-sanitization policy `handleServerFunctionRequest`
+ * applies to a plain thrown value before serialization. Returns `value`
+ * unchanged in the dev build or when it is branded safe (`markSafeError`);
+ * otherwise returns a generic `Error` carrying `GENERIC_SERVER_ERROR_MESSAGE`.
+ * Exposed for frameworks composing their own dispatch around the same policy.
+ */
+export function sanitizeServerError(value: unknown): unknown;
+
+/**
+ * Overrides the build-variant dev flag for this module instance — the seam
+ * for test harnesses and hand-rolled bundles whose packaging cannot replace
+ * `_DX_DEV_`. Applications never call this; select the dev build through
+ * the `development` export condition instead.
+ * @internal
+ */
+export function setServerFunctionsDev(dev: boolean): void;

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

@@ -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;
 
@@ -412,6 +422,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 +435,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 +445,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 +460,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;