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

package/types-cjs/response.d.cts

@@ -49,6 +49,51 @@ export interface Href {
  */
 export function isHref(value: unknown): value is Href;
 
+/**
+ * Registered-symbol brand (`Symbol.for("solid.SafeError")`) marking a thrown
+ * value as safe to serialize to the client verbatim. Declared `unique
+ * symbol` type-side; the runtime value is the registered symbol, so
+ * separately bundled copies agree on identity.
+ */
+export declare const SAFE_ERROR: unique symbol;
+
+/**
+ * Marks `error` as safe to serialize to the client verbatim, opting it out
+ * of the server-function handler's production error sanitization.
+ *
+ * By default a plain `Error` thrown from a server function is sanitized to a
+ * generic `Error` outside the dev build (the `development` export condition
+ * selects the full-fidelity copy; every other resolution sanitizes):
+ * its `message`, `stack`, and own-properties are dropped so a driver/ORM
+ * error can't leak a failing query or connection string over the wire.
+ * Dev builds keep full fidelity. This is the escape hatch for errors whose
+ * content is *intentional* client-facing information — brand them and their
+ * message/properties travel intact in every environment.
+ *
+ * The brand is a non-enumerable, symbol-keyed property, so it never itself
+ * serializes as an own-property. Sets the brand and returns the same value.
+ *
+ * @example
+ * ```ts
+ * import { markSafeError } from "@solidjs/web";
+ *
+ * async function transfer(amount: number) {
+ *   "use server";
+ *   if (amount > balance) {
+ *     // The user must see this message; opt out of sanitization.
+ *     throw markSafeError(new Error("Insufficient funds"));
+ *   }
+ * }
+ * ```
+ */
+export function markSafeError<E>(error: E): E;
+
+/**
+ * Whether `value` is branded safe to serialize (via `markSafeError`).
+ * Registered-symbol check, correct across duplicated module instances.
+ */
+export function isSafeError(value: unknown): value is Error;
+
 /**
  * Response header naming the cache keys a mutation invalidated
  * (`"X-Revalidate"`), comma separated. The response helpers below set it

package/types-cjs/serializer.d.cts

@@ -1,23 +1,142 @@
-import { Plugin, Serializer, SerovalNode } from "seroval";
+// Serialization surface (published as `@solidjs/web/serialization`): the
+// runtime's Seroval machinery, exposed for the runtime's own entries and
+// for integrations building transports on the same codec. This is
+// INTEGRATION-FACING plumbing, not application API — it is exempt from the
+// 2.0 stability guarantee and may change between releases. Application and
+// router code should configure `codec` on the server-function entries
+// instead of importing from here.
+import { Serializer, SerovalNode } from "seroval";
 
 /**
  * Seroval's node shape — the intermediate representation `serializeJSON`
  * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export type { SerovalNode };
 
+// ---- Plugin authoring ----
+//
+// Unlike the rest of this entry, plugin authoring is APPLICATION-FACING —
+// it is the supported way to feed the serializers' `plugins` options and
+// the server-function entries' `codec.plugins`. The values re-export
+// seroval's own (`createPlugin`, `OpaqueReference` — see serializer.js);
+// the TYPES are declared here by hand, like everything else in this file,
+// because seroval's published d.ts use extensionless ESM-relative imports
+// that `moduleResolution: "nodenext"` cannot follow — a bare type
+// re-export would silently degrade the whole authoring surface to `any`
+// under skipLibCheck. The declarations mirror seroval ~1.5 exactly; the
+// `~` pin is what makes mirroring safe.
+
+/** Per-plugin bookkeeping seroval hands each plugin callback. */
+export interface PluginData {
+  id: number;
+}
+
+/**
+ * The shape of a plugin's parsed payload: a map of `SerovalNode`s produced
+ * by the parse contexts, consumed by `serialize`/`deserialize`.
+ */
+export type PluginInfo = { [key: string]: SerovalNode };
+
+/** Parse context for `parse.sync`: turns child values into nodes. */
+export interface SyncParsePluginContext {
+  parse<T>(current: T): SerovalNode;
+}
+
+/** Parse context for `parse.async`: like sync, but child parses await. */
+export interface AsyncParsePluginContext {
+  parse<T>(current: T): Promise<SerovalNode>;
+}
+
+/**
+ * Parse context for `parse.stream`: sync parsing plus the streaming
+ * lifecycle (pending-state tracking, late node emission, cleanup).
+ */
+export interface StreamParsePluginContext {
+  parse<T>(current: T): SerovalNode;
+  parseWithError<T>(current: T): SerovalNode | undefined;
+  isAlive(): boolean;
+  pushPendingState(): void;
+  popPendingState(): void;
+  onParse(node: SerovalNode): void;
+  onError(error: unknown): void;
+  addCleanup(callback: () => void): void;
+}
+
+/** Serialize context: renders child nodes to JS source. */
+export interface SerializePluginContext {
+  serialize(node: SerovalNode): string;
+}
+
+/** Deserialize context: revives child nodes to runtime values. */
+export interface DeserializePluginContext {
+  deserialize<T>(node: SerovalNode): T;
+}
+
 /**
  * A Seroval plugin usable with the web serializers — teaches the codec how
- * to encode/decode a custom value type. Supply matching plugins on both
- * peers of a transport.
+ * to encode/decode a custom value type (`Value` is the value it matches,
+ * `Info` its parsed payload). Supply matching plugins on both peers of a
+ * transport. Bare `SerializerPlugin` (both parameters defaulted to `any`)
+ * is the list-element type every `plugins` option accepts.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
-export type SerializerPlugin = Plugin<any, any>;
+export interface SerializerPlugin<Value = any, Info extends PluginInfo = any> {
+  /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
+  tag: string;
+  /** Dependency plugins, resolved ahead of this one. */
+  extends?: SerializerPlugin[];
+  /** Whether `value` is this plugin's to encode. */
+  test(value: unknown): boolean;
+  /** Parsing modes — provide the ones the transports you target use. */
+  parse: {
+    sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
+    async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
+    stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
+  };
+  /** Renders the parsed payload as JS source (script-injection form). */
+  serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
+  /** Revives the parsed payload back into the runtime value. */
+  deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
+}
+
+/**
+ * Builds a `SerializerPlugin` — seroval's `createPlugin`, re-exported so
+ * plugin authors stay on the exact seroval instance/version the runtime
+ * serializes with. Import it from HERE, not from your own `seroval`
+ * dependency: a plugin built against a different copy/version would not
+ * fail the build — it would emit nodes the other peer can't interpret.
+ *
+ * Application-facing (see the plugin-authoring banner above).
+ */
+export function createPlugin<Value, Info extends PluginInfo>(
+  plugin: SerializerPlugin<Value, Info>
+): SerializerPlugin<Value, Info>;
+
+/**
+ * Seroval's `OpaqueReference`, re-exported from the runtime's own instance
+ * (an `OpaqueReference` from another seroval copy fails the serializer's
+ * instanceof check and serializes as a plain value): wraps a value so it
+ * crosses the wire as its `replacement` (default `undefined`) while
+ * staying readable in-process through `.value`.
+ *
+ * Application-facing (see the plugin-authoring banner above).
+ */
+export class OpaqueReference<V, R = undefined> {
+  readonly value: V;
+  readonly replacement?: R;
+  constructor(value: V, replacement?: R);
+}
 
 /**
  * Baseline plugin set for serializing web-platform values (AbortSignal,
  * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
  * Applied by every serializer in this module; custom plugins compose ahead
  * of it via `resolveSerializerPlugins`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
 
@@ -26,10 +145,16 @@ export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
  * first so they can shadow a default for values both would match. Returns a
  * fresh array; the defaults are never mutated. Useful when handing a full
  * plugin list to another serialization layer.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
 
-/** Options for `createSerializer`. */
+/**
+ * Options for `createSerializer`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
 export interface WebSerializerOptions {
   /** Name of the global object the emitted scripts write resolved values into. */
   globalIdentifier: string;
@@ -58,6 +183,8 @@ export interface WebSerializerOptions {
  * evaluated — the script-injection form of serialization renderers build
  * on. For a JSON-based wire codec (no eval on the receiving side), use
  * `serializeJSON` / `createJSONDeserializer` instead.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function createSerializer(options: WebSerializerOptions): Serializer;
 
@@ -96,6 +223,8 @@ export function getLocalHeaderScript(id?: string): string;
  * on the serializing and deserializing peer or payloads will not
  * round-trip — for server functions, set them once through the
  * client/server `codec` config option.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export interface JSONCodecOptions {
   /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
@@ -113,7 +242,11 @@ export interface JSONCodecOptions {
   depthLimit?: number;
 }
 
-/** Options for `serializeJSON`. */
+/**
+ * Options for `serializeJSON`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
 export interface JSONSerializeOptions extends JSONCodecOptions {
   /**
    * Receives each serialized node; `initial` is true for the first chunk
@@ -132,6 +265,8 @@ export interface JSONSerializeOptions extends JSONCodecOptions {
  * the deserializing peer needs no script evaluation, so CSP-safe). Wire
  * framing of the nodes is the transport's concern. Returns a cancel
  * function that aborts pending async serialization.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
 
@@ -141,14 +276,46 @@ export function serializeJSON(value: unknown, options: JSONSerializeOptions): ()
  * from one stream must go through the same deserializer instance. The first
  * chunk's return value is the decoded source value; feeding later chunks
  * settles the async values referenced inside it.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
 
+/** Options for `createJSONSerializer`. */
+export interface JSONSerializerOptions extends JSONCodecOptions {
+  /**
+   * Receives each keyed record — `initial` is true for a key's first node
+   * (the written value itself); async values patch through later records
+   * under the same key. The decoding peer is `createJSONDataTable`.
+   */
+  onData: (record: { key: string; node: SerovalNode; initial: boolean }) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once `flush()` has been called and every pending value settled. */
+  onDone?: () => void;
+}
+
+/**
+ * The keyed, streaming encoder of the eval-free JSON codec — the render
+ * stream's data serializer (frames default to it). Each `write(key, value)`
+ * shares one reference space, so cross-record identity holds; `flush()`
+ * marks the write set complete (writes after it are dropped, mirroring the
+ * hydration serializer); `close()` aborts pending async serialization.
+ */
+export function createJSONSerializer(options: JSONSerializerOptions): {
+  write(key: string, value: unknown): void;
+  flush(): void;
+  close(): void;
+};
+
 /**
  * A resident, response-scoped decode table over the keyed JSON codec: apply
  * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
  * `resolve`. The frames client host wires one per response
  * (`applyData: c => table.apply(c)`).
+ *
+ * Integration-facing; may change (see the entry banner). This serialization
+ * entry is the single home of the data table — the frames client consumes
+ * it internally rather than re-exporting it.
  */
 export interface JSONDataTable {
   apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;

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

@@ -21,6 +21,7 @@ export {
   getServerFunctionsCodec,
   hasFlashCookie,
   isServerFunction,
+  serializeString,
   subscribeFlightData,
   withMeta
 } from "./shared.cjs";

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

@@ -0,0 +1,10 @@
+/**
+ * Opt-in codec encoding for server-function ARGUMENTS. By default the client
+ * sends argument lists as plain JSON (no serializer in the bundle) and
+ * throws on values JSON can't carry faithfully. Call once at startup to
+ * send Dates, Maps, Sets, typed arrays, cyclic structures, etc. through the
+ * codec — at the cost of the serializer's write half (~5 KB gz on top of
+ * the decode half responses already need). The handler accepts both
+ * encodings unconditionally.
+ */
+export function enableRichArguments(): void;

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

@@ -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-cjs/server-functions/shared.d.cts

@@ -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;