@solidjs/web 2.0.0-beta.3 → 2.0.0-beta.30

package/serialization/dist/serialization.js

@@ -0,0 +1,159 @@
+import { Feature, Serializer, getCrossReferenceHeader, toCrossJSONStream, fromCrossJSON } 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 DEFAULT_WEB_PLUGINS = Object.freeze([AbortSignalPlugin,
+CustomEventPlugin, DOMExceptionPlugin, EventPlugin,
+FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin]);
+function resolveSerializerPlugins(customPlugins) {
+  return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
+}
+function createSerializer(options) {
+  return new Serializer({
+    ...options,
+    plugins: resolveSerializerPlugins(options.plugins),
+    disabledFeatures: (options.disabledFeatures === undefined ? DEFAULT_DISABLED_FEATURES : options.disabledFeatures) | serializeOnlyDisabledFeatures()
+  });
+}
+function createHydrationSerializer({
+  onData,
+  onDone,
+  scopeId,
+  onError,
+  plugins
+}) {
+  return createSerializer({
+    scopeId,
+    plugins,
+    globalIdentifier: HYDRATION_GLOBAL,
+    onData,
+    onDone,
+    onError
+  });
+}
+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,
+  onError,
+  ...codecOptions
+}) {
+  const resolved = resolveCodecOptions(codecOptions);
+  return toCrossJSONStream(value, {
+    onParse,
+    onDone,
+    onError,
+    ...resolved,
+    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,
+  onError,
+  plugins,
+  disabledFeatures,
+  depthLimit
+}) {
+  const resolved = resolveCodecOptions({
+    plugins,
+    disabledFeatures,
+    depthLimit
+  });
+  const refs = new Map();
+  const cancels = new Set();
+  let pendingWrites = 0;
+  let flushed = false;
+  let done = false;
+  const maybeDone = () => {
+    if (flushed && pendingWrites === 0 && !done) {
+      done = true;
+      onDone && onDone();
+    }
+  };
+  return {
+    write(key, value) {
+      if (flushed) return;
+      pendingWrites++;
+      let settled = false;
+      let cancel = null;
+      const stream = toCrossJSONStream(value, {
+        refs,
+        plugins: resolved.plugins,
+        disabledFeatures: resolved.disabledFeatures | serializeOnlyDisabledFeatures(),
+        onParse(node, initial) {
+          onData({
+            key,
+            node,
+            initial
+          });
+        },
+        onError,
+        onDone() {
+          settled = true;
+          if (cancel) cancels.delete(cancel);
+          pendingWrites--;
+          maybeDone();
+        }
+      });
+      if (!settled) {
+        cancel = stream;
+        cancels.add(cancel);
+      }
+    },
+    flush() {
+      flushed = true;
+      maybeDone();
+    },
+    close() {
+      flushed = true;
+      for (const cancel of cancels) cancel();
+      cancels.clear();
+    }
+  };
+}
+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/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@solidjs/web/serialization",
+  "main": "./dist/serialization.cjs",
+  "module": "./dist/serialization.js",
+  "types": "./types/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/serialization.js"
+      },
+      "require": {
+        "types": "./types-cjs/index.d.cts",
+        "default": "./dist/serialization.cjs"
+      }
+    }
+  }
+}

package/serialization/types/index.d.ts

@@ -0,0 +1,157 @@
+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). Outside
+   * development, `Error.prototype.stack` is additionally stripped on top of
+   * any override — serialized stacks leak server paths to the client.
+   */
+  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.
+   * 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
+   * (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/serialization/types-cjs/index.d.cts

@@ -0,0 +1,157 @@
+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). Outside
+   * development, `Error.prototype.stack` is additionally stripped on top of
+   * any override — serialized stacks leak server paths to the client.
+   */
+  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.
+   * 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
+   * (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/serialization/types-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}