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

package/serialization/dist/serialization.js

@@ -1,15 +1,110 @@
-import { Feature, Serializer, getCrossReferenceHeader, toCrossJSONStream, fromCrossJSON } from 'seroval';
+import { Feature, fromCrossJSON, toCrossJSONStream, Serializer, getCrossReferenceHeader } from 'seroval';
+export { OpaqueReference, createPlugin } from 'seroval';
 import { AbortSignalPlugin, CustomEventPlugin, DOMExceptionPlugin, EventPlugin, FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin } from 'seroval-plugins/web';
 
-const DEFAULT_DISABLED_FEATURES = Feature.AggregateError | Feature.BigIntTypedArray;
-const serializeOnlyDisabledFeatures = () => process.env.NODE_ENV === "development" ? 0 : Feature.ErrorPrototypeStack;
-const HYDRATION_GLOBAL = "_$HY.r";
+const STATE = Symbol.for("dom-expressions.container-trace-state");
+const state = globalThis[STATE] || (globalThis[STATE] = {
+  materialized: new WeakMap(),
+  materializedValues: new WeakSet()
+});
+const TRACE = Symbol.for("dom-expressions.container-trace");
+function materialize(marker) {
+  let value = state.materialized.get(marker.$tr);
+  if (value === undefined) {
+    value = state.materializeTrace(marker);
+    state.materialized.set(marker.$tr, value);
+    if (value !== null && typeof value === "object") state.materializedValues.add(value);
+  }
+  return value;
+}
+function parseTrace(value, ctx) {
+  const trace = value[TRACE];
+  return {
+    a: trace.array ? 1 : 0,
+    i: ctx.parse(trace.subscribe())
+  };
+}
+const ContainerTracePlugin = {
+  tag: "dom-expressions/container-trace",
+  test(value) {
+    return value != null && typeof value === "object" && TRACE in value;
+  },
+  parse: {
+    sync() {
+      throw new Error("A reactive container can only be serialized by a streaming serializer.");
+    },
+    async async(value, ctx) {
+      const trace = value[TRACE];
+      return {
+        a: trace.array ? 1 : 0,
+        i: await ctx.parse(trace.subscribe())
+      };
+    },
+    stream: parseTrace
+  },
+  serialize(node, ctx) {
+    return "{$tr:" + ctx.serialize(node.i) + ",$ta:" + node.a + "}";
+  },
+  deserialize(node, ctx) {
+    const iterable = ctx.deserialize(node.i);
+    const marker = {
+      $tr: iterable,
+      $ta: node.a
+    };
+    return state.materializeTrace ? materialize(marker) : marker;
+  }
+};
+
 const DEFAULT_WEB_PLUGINS = Object.freeze([AbortSignalPlugin,
 CustomEventPlugin, DOMExceptionPlugin, EventPlugin,
-FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin]);
+FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin,
+ContainerTracePlugin]);
 function resolveSerializerPlugins(customPlugins) {
   return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
 }
+const JSON_CODEC_DISABLED_FEATURES = Feature.RegExp;
+const JSON_CODEC_DEPTH_LIMIT = 64;
+function resolveCodecOptions({
+  plugins,
+  disabledFeatures,
+  depthLimit
+} = {}) {
+  return {
+    plugins: resolveSerializerPlugins(plugins),
+    disabledFeatures: disabledFeatures === undefined ? JSON_CODEC_DISABLED_FEATURES : disabledFeatures,
+    depthLimit: depthLimit === undefined ? JSON_CODEC_DEPTH_LIMIT : depthLimit
+  };
+}
+function createJSONDeserializer(options) {
+  const refs = new Map();
+  const resolved = resolveCodecOptions(options);
+  return function deserializeJSONChunk(node) {
+    return fromCrossJSON(node, {
+      refs,
+      ...resolved
+    });
+  };
+}
+function createJSONDataTable(options) {
+  const deserialize = createJSONDeserializer(options);
+  const table = new Map();
+  return {
+    apply(record) {
+      const value = deserialize(record.node);
+      if (record.initial) table.set(record.key, value);
+    },
+    get(key) {
+      return table.get(key);
+    },
+    resolve(ref) {
+      return table.get(ref.$ref);
+    }
+  };
+}
+
+const DEFAULT_DISABLED_FEATURES = Feature.AggregateError | Feature.BigIntTypedArray;
+const serializeOnlyDisabledFeatures = () => process.env.NODE_ENV === "development" ? 0 : Feature.ErrorPrototypeStack;
+const HYDRATION_GLOBAL = "_$HY.r";
 function createSerializer(options) {
   return new Serializer({
     ...options,
@@ -36,19 +131,6 @@ function createHydrationSerializer({
 function getLocalHeaderScript(id) {
   return getCrossReferenceHeader(id) + ";";
 }
-const JSON_CODEC_DISABLED_FEATURES = Feature.RegExp;
-const JSON_CODEC_DEPTH_LIMIT = 64;
-function resolveCodecOptions({
-  plugins,
-  disabledFeatures,
-  depthLimit
-} = {}) {
-  return {
-    plugins: resolveSerializerPlugins(plugins),
-    disabledFeatures: disabledFeatures === undefined ? JSON_CODEC_DISABLED_FEATURES : disabledFeatures,
-    depthLimit: depthLimit === undefined ? JSON_CODEC_DEPTH_LIMIT : depthLimit
-  };
-}
 function serializeJSON(value, {
   onParse,
   onDone,
@@ -64,16 +146,6 @@ function serializeJSON(value, {
     disabledFeatures: resolved.disabledFeatures | serializeOnlyDisabledFeatures()
   });
 }
-function createJSONDeserializer(options) {
-  const refs = new Map();
-  const resolved = resolveCodecOptions(options);
-  return function deserializeJSONChunk(node) {
-    return fromCrossJSON(node, {
-      refs,
-      ...resolved
-    });
-  };
-}
 function createJSONSerializer({
   onData,
   onDone,
@@ -139,21 +211,5 @@ function createJSONSerializer({
     }
   };
 }
-function createJSONDataTable(options) {
-  const deserialize = createJSONDeserializer(options);
-  const table = new Map();
-  return {
-    apply(record) {
-      const value = deserialize(record.node);
-      if (record.initial) table.set(record.key, value);
-    },
-    get(key) {
-      return table.get(key);
-    },
-    resolve(ref) {
-      return table.get(ref.$ref);
-    }
-  };
-}
 
 export { DEFAULT_WEB_PLUGINS, createHydrationSerializer, createJSONDataTable, createJSONDeserializer, createJSONSerializer, createSerializer, getLocalHeaderScript, resolveSerializerPlugins, serializeJSON };

package/serialization/types/index.d.ts

@@ -1,35 +1,67 @@
-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 type { Serializer } from "seroval";
+import {
+  JSONCodecOptions,
+  PluginInfo,
+  SerializerPlugin,
+  SerovalNode
+} from "./serializer-decode.js";
 
-/**
- * Seroval's node shape — the intermediate representation `serializeJSON`
- * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
- */
-export type { SerovalNode };
+// The decode half — `SerovalNode`, the plugin TYPES, `DEFAULT_WEB_PLUGINS`,
+// `resolveSerializerPlugins`, `JSONCodecOptions`, `createJSONDeserializer`,
+// `createJSONDataTable` — is declared in serializer-decode.d.ts (published
+// as `@solidjs/web/serialization/decode`, the module lazy client consumers
+// load) and re-exported here so this remains the full surface.
+export * from "./serializer-decode.js";
+
+// ---- 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 plugin TYPES live in serializer-decode.d.ts (hand-declared there —
+// see its banner for why).
 
 /**
- * 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.
+ * 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 type SerializerPlugin = Plugin<any, any>;
+export function createPlugin<Value, Info extends PluginInfo>(
+  plugin: SerializerPlugin<Value, Info>
+): SerializerPlugin<Value, Info>;
 
 /**
- * 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`.
+ * 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 const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+export class OpaqueReference<V, R = undefined> {
+  readonly value: V;
+  readonly replacement?: R;
+  constructor(value: V, replacement?: R);
+}
 
 /**
- * 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.
+ * Options for `createSerializer`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
-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;
@@ -58,6 +90,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;
 
@@ -90,30 +124,14 @@ export function createHydrationSerializer(options: HydrationSerializerOptions):
 export function getLocalHeaderScript(id?: string): string;
 
 // ---- JSON codec (server function transports) ----
+// (`JSONCodecOptions` and the decode half are declared in
+// serializer-decode.d.ts and re-exported above.)
 
 /**
- * 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.
+ * Options for `serializeJSON`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
-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.
-   * Outside development, the encoding side additionally strips
-   * `Error.prototype.stack` on top of any override — serialized stacks leak
-   * server paths to the client. Decoding stays permissive, so payloads from
-   * a development peer still round-trip.
-   */
-  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
@@ -132,26 +150,33 @@ 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;
 
-/**
- * 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;
+/** 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;
+}
 
 /**
- * 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)`).
+ * 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 interface JSONDataTable {
-  apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
-  resolve<T = unknown>(ref: { $ref: string }): T;
-}
-export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;
+export function createJSONSerializer(options: JSONSerializerOptions): {
+  write(key: string, value: unknown): void;
+  flush(): void;
+  close(): void;
+};

package/serialization/types/serializer-decode.d.ts

@@ -0,0 +1,182 @@
+// The DECODE half of the serialization surface (published as
+// `@solidjs/web/serialization/decode`): what reading a serialized payload
+// needs — `fromCrossJSON`-backed deserializers and the shared plugin set —
+// with none of the encode machinery. Lazy client consumers (the frames
+// data tables, `deserializeStream`) load this module so the encode half
+// never ships to a browser that only reads. The full serializer.d.ts
+// re-exports everything here; see its banner for the stability contract
+// (integration-facing, exempt from the 2.0 stability guarantee).
+// ---- Plugin types ----
+//
+// Declared here by hand (seroval's published d.ts use extensionless
+// ESM-relative imports that `moduleResolution: "nodenext"` cannot follow —
+// a bare type re-export would silently degrade the surface to `any` under
+// skipLibCheck, and an import would make every entry whose types reach
+// this module — the MAIN client entry included, via the server-function
+// seam's `JSONCodecOptions` — unimportable from a strict Node16 CJS
+// consumer). The declarations mirror seroval ~1.5 exactly; the `~` pin is
+// what makes mirroring safe. Plugin AUTHORING (`createPlugin`,
+// `OpaqueReference`) lives on the full serialization entry.
+
+/**
+ * Seroval's node shape — the intermediate representation `serializeJSON`
+ * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ * Declared by hand like the plugin types below (same rationale): the
+ * observable envelope — a numeric type tag, an optional reference id —
+ * with the rest owned by the codec. Real seroval nodes satisfy it; treat
+ * it as an opaque token.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export interface SerovalNode {
+  /** Node type tag (seroval-internal enum). */
+  t: number;
+  /** Reference id, when the node participates in cross-referencing. */
+  i?: number | undefined;
+  [key: string]: unknown;
+}
+
+/** 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 (`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 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;
+}
+
+/**
+ * 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[];
+
+/**
+ * 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.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+/**
+ * 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.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+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.
+   * Outside development, the encoding side additionally strips
+   * `Error.prototype.stack` on top of any override — serialized stacks leak
+   * server paths to the client. Decoding stays permissive, so payloads from
+   * a development peer still round-trip.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+/**
+ * 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.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+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)`).
+ *
+ * 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;
+  resolve<T = unknown>(ref: { $ref: string }): T;
+}
+export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;