@solidjs/web 2.0.0-rc.2 → 2.0.0-rc.3

package/serialization/types-cjs/serializer-decode.d.cts

@@ -1,23 +1,3 @@
-// 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`.
@@ -29,59 +9,53 @@
  * 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;
+    /** 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;
+    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 };
-
+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<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<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;
+    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;
+    serialize(node: SerovalNode): string;
 }
-
 /** Deserialize context: revives child nodes to runtime values. */
 export interface DeserializePluginContext {
-  deserialize<T>(node: SerovalNode): T;
+    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,
@@ -92,44 +66,23 @@ export interface DeserializePluginContext {
  * 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;
+    /** 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
@@ -139,32 +92,20 @@ export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): Se
  * 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;
+    /** 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
@@ -176,7 +117,43 @@ export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: Se
  * 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;
+    apply(chunk: {
+        key?: string;
+        node?: unknown;
+        initial?: boolean;
+    }): void;
+    resolve<T = unknown>(ref: {
+        $ref: string;
+    }): T;
 }
-export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;
+/**
+ * Baseline plugin set for serializing web-platform values. Shared by the
+ * hydration serializer and any consumer building its own serializer (e.g.
+ * server function transports). Plugin objects carry both their serialize
+ * and deserialize halves, so the set lives on the decode side and the
+ * encode module composes over it.
+ */
+export declare const DEFAULT_WEB_PLUGINS: any; /**
+ * 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 declare function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+export declare function resolveCodecOptions({ plugins, disabledFeatures, depthLimit }?: JSONCodecOptions): {
+    plugins: SerializerPlugin<any, any>[];
+    disabledFeatures: any;
+    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 declare function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+export declare function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;

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

@@ -0,0 +1,94 @@
+import { Serializer } from "seroval";
+import type { JSONCodecOptions, PluginInfo, SerializerPlugin, SerovalNode } from "./serializer-decode.cjs";
+export { DEFAULT_WEB_PLUGINS, createJSONDataTable, createJSONDeserializer, resolveSerializerPlugins } from "./serializer-decode.cjs";
+export type * from "./serializer-decode.cjs";
+/**
+ * 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;
+    /** 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;
+}
+/**
+ * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
+ * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
+ * @internal
+ */
+export type HydrationSerializerOptions = Omit<WebSerializerOptions, "globalIdentifier" | "disabledFeatures">;
+/**
+ * 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
+     * (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;
+}
+/** 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;
+}
+export declare const createPlugin: <Value, Info extends PluginInfo>(plugin: SerializerPlugin<Value, Info>) => SerializerPlugin<Value, Info>;
+export interface OpaqueReference<V = unknown, R = undefined> {
+    readonly value: V;
+    readonly replacement?: R;
+}
+export declare const OpaqueReference: {
+    new <V, R = undefined>(value: V, replacement?: R): OpaqueReference<V, R>;
+};
+/**
+ * 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.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export declare function createSerializer(options: WebSerializerOptions): Serializer;
+export declare function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+export declare function getLocalHeaderScript(id?: string): string;
+export declare function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+export declare function createJSONSerializer(options: JSONSerializerOptions): {
+    write(key: string, value: unknown): void;
+    flush(): void;
+    close(): void;
+};