@solidjs/web 2.0.0-rc.5 → 2.0.0-rc.6

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

@@ -241,7 +241,9 @@ export interface ServerFunctionsServerConfig {
     /**
      * Codec options (extra plugins etc.) for decoding arguments and encoding
      * results — must match the client's. Stored in the shared layer, so
-     * `decodeResponse` sees them too.
+     * `decodeResponse` sees them too. When `serializeErrorStacks` is omitted,
+     * the server-function boundary defaults it from this module's compiled
+     * development variant.
      */
     codec?: JSONCodecOptions;
     /**
@@ -440,7 +442,7 @@ export declare function guardFailures(value: any, state: any): any;
  * teardown registry are threaded through its state (`{ items: rows() }` —
  * a cursor beside a total — gets the same two guarantees as `return rows()`).
  */
-export declare function serializeResponseStream(value: any, codecOptions: any, signal: any): ReadableStream<any>;
+export declare function serializeResponseStream(value: any, codecOptions: any, signal: any, scope: any): ReadableStream<any>;
 /** Message a sanitized (production) server error carries on the wire. */
 export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
 export declare function setServerFunctionsDev(dev: boolean): void;
@@ -448,4 +450,73 @@ export declare function sanitizeServerError(value: unknown): unknown;
 export declare function observeServerFunctionCalls(observer: (call: ServerFunctionCall) => void): () => void;
 export declare function serverFunctionUrl(id: string, boundArgs?: readonly unknown[]): string;
 export declare function parseServerFunctionUrl(url: string): string | null;
+/**
+ * Web-standard HTTP handler for server function calls: resolves the
+ * function id from the request, enforces the method allowlist (POST always
+ * dispatches; GET and HEAD dispatch only to functions that declared `GET`,
+ * with HEAD returning the equivalent GET's status and headers minus the
+ * body; every other method answers 405), decodes arguments, runs the
+ * function under a request-event scope, and encodes the result (forwarding
+ * redirect/revalidation metadata through headers). Mount it on the endpoint
+ * the client transport targets (default `/_server`); platform adapters (h3,
+ * express, ...) convert their request shape to a web `Request` around it.
+ *
+ * Requests are same-origin by default. The handler accepts browser requests
+ * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
+ * without usable metadata unless explicitly configured otherwise. GET/HEAD
+ * requests to `GET`-declared functions skip this gate: they are reads by
+ * contract, cross-site response READING is already blocked by same-origin
+ * policy, and skipping it keeps the `Vary: Sec-Fetch-Site, Origin, Referer`
+ * it would impose off the responses shared caches are meant to store.
+ *
+ * Every response leaves with `Cache-Control: no-store` unless the function
+ * set its own cache policy (via `respond()` headers or a returned
+ * `Response`) — caching is opt-in on the wire, not just in prose.
+ *
+ * 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";
+ * import "virtual:solid-server-function-manifest";
+ *
+ * // in the server's request handling:
+ * if (url.pathname.startsWith("/_server")) {
+ *   return handleServerFunctionRequest(request);
+ * }
+ * ```
+ */
 export declare function handleServerFunctionRequest(request: Request, options?: HandleServerFunctionOptions): Promise<Response>;

package/types-cjs/client.d.cts

@@ -136,7 +136,7 @@ export declare function claimElement<T extends Element>(node: T): T;
 export declare function setAttribute(node: Element, name: string, value: string): void;
 export declare function setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
 export declare function className(node: Element, value: JSX.ClassValue, prev?: JSX.ClassValue): void;
-export declare function addEvent(node: Element, name: string, handler: EventListener | EventListenerObject | (EventListenerObject & AddEventListenerOptions), delegate: boolean): void;
+export declare function addEvent(node: Element, name: string, handler: EventListener | EventListenerObject | (EventListenerObject & AddEventListenerOptions), delegate: boolean): EventListener | EventListenerObject | void;
 export declare function style(node: Element, value: {
     [k: string]: string;
 }, prev?: {
@@ -149,6 +149,7 @@ export declare function applyRef<T extends Element = Element>(r: ((element: NoIn
 export declare function ref(fn: () => ((element: Element) => void) | ((element: Element) => void)[], element: Element): void;
 /** Compiler-emitted primitive; not for hand-written code. @internal */
 export declare function scope<T extends () => any>(fn: T): T;
+export declare function getInsertionParent(): Node | undefined;
 export declare function installHydrationRuntime(): void;
 /**
  * Compiler-emitted primitive; not for hand-written code.

package/types-cjs/constants.d.cts

@@ -15,4 +15,6 @@ declare const Namespaces: Record<string, string>;
 declare const VoidElements: Set<string>;
 declare const RawTextElements: Set<string>;
 declare const DOMElements: Set<string>;
-export { DOMWithState, ChildProperties, DelegatedEvents, SVGElements, MathMLElements, VoidElements, RawTextElements, Namespaces, DOMElements, $$SLOT, $$HOST };
+declare const COMPOSED_BODY_FRAMING: ReadonlySet<string>;
+declare function isHttpNavigationTarget(target: string): boolean;
+export { DOMWithState, ChildProperties, DelegatedEvents, SVGElements, MathMLElements, VoidElements, RawTextElements, Namespaces, DOMElements, $$SLOT, $$HOST, COMPOSED_BODY_FRAMING, isHttpNavigationTarget };

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

@@ -241,7 +241,9 @@ export interface ServerFunctionsServerConfig {
     /**
      * Codec options (extra plugins etc.) for decoding arguments and encoding
      * results — must match the client's. Stored in the shared layer, so
-     * `decodeResponse` sees them too.
+     * `decodeResponse` sees them too. When `serializeErrorStacks` is omitted,
+     * the server-function boundary defaults it from this module's compiled
+     * development variant.
      */
     codec?: JSONCodecOptions;
     /**
@@ -440,7 +442,7 @@ export declare function guardFailures(value: any, state: any): any;
  * teardown registry are threaded through its state (`{ items: rows() }` —
  * a cursor beside a total — gets the same two guarantees as `return rows()`).
  */
-export declare function serializeResponseStream(value: any, codecOptions: any, signal: any): ReadableStream<any>;
+export declare function serializeResponseStream(value: any, codecOptions: any, signal: any, scope: any): ReadableStream<any>;
 /** Message a sanitized (production) server error carries on the wire. */
 export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
 export declare function setServerFunctionsDev(dev: boolean): void;
@@ -448,4 +450,73 @@ export declare function sanitizeServerError(value: unknown): unknown;
 export declare function observeServerFunctionCalls(observer: (call: ServerFunctionCall) => void): () => void;
 export declare function serverFunctionUrl(id: string, boundArgs?: readonly unknown[]): string;
 export declare function parseServerFunctionUrl(url: string): string | null;
+/**
+ * Web-standard HTTP handler for server function calls: resolves the
+ * function id from the request, enforces the method allowlist (POST always
+ * dispatches; GET and HEAD dispatch only to functions that declared `GET`,
+ * with HEAD returning the equivalent GET's status and headers minus the
+ * body; every other method answers 405), decodes arguments, runs the
+ * function under a request-event scope, and encodes the result (forwarding
+ * redirect/revalidation metadata through headers). Mount it on the endpoint
+ * the client transport targets (default `/_server`); platform adapters (h3,
+ * express, ...) convert their request shape to a web `Request` around it.
+ *
+ * Requests are same-origin by default. The handler accepts browser requests
+ * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
+ * without usable metadata unless explicitly configured otherwise. GET/HEAD
+ * requests to `GET`-declared functions skip this gate: they are reads by
+ * contract, cross-site response READING is already blocked by same-origin
+ * policy, and skipping it keeps the `Vary: Sec-Fetch-Site, Origin, Referer`
+ * it would impose off the responses shared caches are meant to store.
+ *
+ * Every response leaves with `Cache-Control: no-store` unless the function
+ * set its own cache policy (via `respond()` headers or a returned
+ * `Response`) — caching is opt-in on the wire, not just in prose.
+ *
+ * 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";
+ * import "virtual:solid-server-function-manifest";
+ *
+ * // in the server's request handling:
+ * if (url.pathname.startsWith("/_server")) {
+ *   return handleServerFunctionRequest(request);
+ * }
+ * ```
+ */
 export declare function handleServerFunctionRequest(request: Request, options?: HandleServerFunctionOptions): Promise<Response>;