@solidjs/web 2.0.0-beta.22 → 2.0.0-beta.24

package/types-cjs/frames/serializer.d.cts

@@ -0,0 +1,151 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+/**
+ * Seroval's node shape — the intermediate representation `serializeJSON`
+ * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ */
+export type { SerovalNode };
+
+/**
+ * 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.
+ */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * 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`.
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * 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.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+/** Options for `createSerializer`. */
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  /** Cross-reference scope id, for isolating multiple streams on one page. */
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays).
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  /** Receives each emitted script chunk. */
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy. Emits JavaScript chunks (through
+ * `onData`) that reconstruct the values under `globalIdentifier` when
+ * 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.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+/**
+ * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
+ * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
+ * @internal
+ */
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Renderer primitive — the serializer SSR uses for hydration output. Pins
+ * the hydration global (`_$HY.r`) and feature policy; only the wiring
+ * options (callbacks, scope, extra plugins) are configurable. Not meant
+ * for hand-written code — custom serialization should use
+ * `createSerializer` or the JSON codec.
+ * @internal
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/**
+ * Renderer primitive — returns the cross-reference bootstrap script SSR
+ * emits ahead of hydration data for a render scope. Not meant for
+ * hand-written code.
+ * @internal
+ */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+/**
+ * Options shared by both halves of the JSON codec. All of them must match
+ * 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.
+ */
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+/** Options for `serializeJSON`. */
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse` —
+ * the encoding half of the eval-free JSON codec (RPC-style transports;
+ * 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.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * 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.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+
+/**
+ * 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)`).
+ */
+export interface JSONDataTable {
+  apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
+  resolve<T = unknown>(ref: { $ref: string }): T;
+}
+export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;

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

@@ -0,0 +1,21 @@
+/**
+ * @solidjs/web/frames — server half. Render server components (functions
+ * returned from server functions) to frame-chunk streams, serve them as
+ * framed HTTP responses through the server-function handler's
+ * transformResult hook, and render them inline during document SSR.
+ *
+ * Copied next to the runtime's frame d.ts files at publish (see
+ * types:copy-frames), so the relative imports below resolve in-place.
+ */
+export {
+  renderToFrameStream,
+  renderServerComponent,
+  serverComponentResponse,
+  frameTransformResult,
+  createFrameSink,
+  frameTransformDirectResult,
+  ServerComponentPlugin,
+  SERVER_COMPONENT_BOOTSTRAP
+} from "./frame-sink.cjs";
+export type { FrameAddress, FrameStream, FrameStreamOptions } from "./frame-sink.cjs";
+export { FRAME_STREAM_HEADER, isFrameStreamResponse } from "./frame-transport.cjs";

package/types-cjs/serializer.d.cts

@@ -137,3 +137,15 @@ export function serializeJSON(value: unknown, options: JSONSerializeOptions): ()
  * settles the async values referenced inside it.
  */
 export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+
+/**
+ * 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)`).
+ */
+export interface JSONDataTable {
+  apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
+  resolve<T = unknown>(ref: { $ref: string }): T;
+}
+export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;

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

@@ -81,6 +81,30 @@ export interface ServerFunctionsClientConfig {
    * ```
    */
   prepareRequest?: PrepareRequestHook;
+  /**
+   * Response-side integration seam — the client mirror of the handler's
+   * `transformResult`. `handle(response, ctx)` sees every response before
+   * the transport decodes it; returning anything but undefined resolves the
+   * call with that value. `capture(info)` runs synchronously at the call
+   * site (before any await) and its return arrives as `ctx.context`, so
+   * ambient per-call state (e.g. a reactive owner) survives to response
+   * time. See `createServerComponentHandler` in frame-transport for the
+   * canonical implementation.
+   */
+  responseHandler?: {
+    capture?(info: { id: string; meta: unknown }): unknown;
+    handle(
+      response: Response,
+      ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
+    ): unknown;
+  };
+  /**
+   * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
+   * always go as plain JSON (no codec in the bundle); anything else throws
+   * unless this is set. Installed by `enableRichArguments()` from the
+   * rich-args entry — set directly only for custom wire encodings.
+   */
+  serializeArgs?(args: unknown[]): string | Promise<string>;
 }
 
 /**

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

@@ -102,6 +102,23 @@ export interface ServerFunctionsServerConfig {
    * router); per-handler `collectFlightData` options override it.
    */
   collectFlightData?: CollectFlightDataHook;
+  /**
+   * Server-wide default for the handler's `transformResult` (same contract
+   * — see `HandleServerFunctionRequestOptions`); a per-request option
+   * overrides it. Registering it here makes result policies (e.g. frames'
+   * `frameTransformResult`) work through generic dispatchers that call
+   * `handleServerFunctionRequest(request)` with no options.
+   */
+  transformResult?(
+    event: ServerFunctionEvent,
+    result: unknown,
+    context: { instance: string | null; request: Request; thrown?: boolean }
+  ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
+  /**
+   * 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;
   /**
    * Endpoint the HTTP handler is mounted on, used for the `url` of SSR'd
    * references (e.g. form actions) — must match the client configuration.

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

@@ -369,3 +369,20 @@ export function decodeResponse<T = unknown>(
   response: Response,
   codecOptions?: JSONCodecOptions
 ): Promise<T | undefined>;
+
+/**
+ * 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.
+ */
+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.
+ */
+export class ChunkReader {
+  constructor(stream: ReadableStream<Uint8Array>);
+  next(): Promise<{ done: boolean; value: string | undefined }>;
+}

package/types-cjs/server.d.cts

@@ -212,6 +212,8 @@ export function setAttributeNS(node: Element, namespace: string, name: string, v
 export function registerElementClaim(handler: (element: Element) => void): () => void;
 /** Server no-op: returns `node` unchanged. Claims never fire during SSR. */
 export function claimElement<T extends Element>(node: T): T;
+/** Server no-op: returns `root` unchanged. Claims never fire during SSR. */
+export function claimElementTree<T extends Node>(root: T): T;
 
 /** @deprecated not supported on the server side */
 export function addEvent(node: Element, name: string, handler: () => void, delegate: boolean): void;