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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/README.md +1 -1
  2. package/dist/server.dev.js +5065 -0
  3. package/dist/server.js +1757 -355
  4. package/dist/{server.cjs → server.observe.js} +1951 -558
  5. package/dist/{dev.cjs → web.dev.js} +945 -550
  6. package/dist/web.js +635 -332
  7. package/dist/{dev.js → web.observe.js} +688 -403
  8. package/frames/dist/assets.js +92 -0
  9. package/frames/dist/client.dev.js +1296 -1198
  10. package/frames/dist/client.js +1128 -1191
  11. package/frames/dist/client.observe.js +2041 -0
  12. package/frames/dist/regions.js +171 -0
  13. package/frames/dist/server.dev.js +2549 -0
  14. package/frames/dist/server.js +1688 -3005
  15. package/frames/dist/server.observe.js +2548 -0
  16. package/frames/dist/trace.js +45 -0
  17. package/frames/dist/wire.js +594 -0
  18. package/frames/package.json +2 -25
  19. package/package.json +244 -256
  20. package/performance-tracks/dist/performance-tracks.dev.js +679 -0
  21. package/performance-tracks/dist/performance-tracks.js +6 -0
  22. package/performance-tracks/dist/performance-tracks.observe.js +667 -0
  23. package/performance-tracks/package.json +7 -0
  24. package/performance-tracks/types/index.d.ts +69 -0
  25. package/serialization/decode/package.json +2 -15
  26. package/serialization/dist/decode.js +121 -25
  27. package/serialization/dist/serialization.js +242 -88
  28. package/serialization/package.json +2 -15
  29. package/serialization/types/index.d.ts +85 -158
  30. package/serialization/types/serializer-decode.d.ts +173 -114
  31. package/serialization/types/serializer.d.ts +109 -0
  32. package/server-functions/dist/client.dev.js +1462 -0
  33. package/server-functions/dist/client.js +667 -165
  34. package/server-functions/dist/client.observe.js +1441 -0
  35. package/server-functions/dist/rich-args.js +84 -1
  36. package/server-functions/dist/server.dev.js +2714 -297
  37. package/server-functions/dist/server.js +2595 -271
  38. package/server-functions/dist/server.observe.js +3594 -0
  39. package/server-functions/package.json +2 -35
  40. package/server-functions/rich-args/package.json +2 -15
  41. package/skills/server-components/SKILL.md +117 -0
  42. package/storage/package.json +2 -15
  43. package/types/client.d.ts +342 -288
  44. package/types/constants.d.ts +22 -0
  45. package/types/cookies.d.ts +32 -84
  46. package/types/diagnostics.d.ts +80 -0
  47. package/types/frames/assets-tier.d.ts +78 -0
  48. package/types/frames/client.d.ts +40 -1
  49. package/types/frames/frame-client.d.ts +443 -280
  50. package/types/frames/frame-container-plugin.d.ts +64 -0
  51. package/types/frames/frame-morph.d.ts +29 -0
  52. package/types/frames/frame-sink.d.ts +141 -161
  53. package/types/frames/frame-transport.d.ts +263 -184
  54. package/types/frames/regions-tier.d.ts +60 -0
  55. package/types/frames/serializer-decode.d.ts +241 -0
  56. package/types/frames/serializer.d.ts +85 -158
  57. package/types/frames/server.d.ts +2 -2
  58. package/types/frames/trace-tier.d.ts +2 -0
  59. package/types/frames/tree-rewrite.d.ts +39 -0
  60. package/types/frames/wire-tier.d.ts +169 -0
  61. package/types/head.d.ts +20 -0
  62. package/types/index.d.ts +98 -81
  63. package/types/index.server.d.ts +159 -0
  64. package/types/jsx.d.ts +49 -44
  65. package/types/observe.d.ts +535 -0
  66. package/types/reconcile.d.ts +1 -0
  67. package/types/render.d.ts +11 -0
  68. package/types/request-error-hook.d.ts +5 -0
  69. package/types/response.d.ts +95 -147
  70. package/types/serializer-decode.d.ts +173 -114
  71. package/types/serializer.d.ts +85 -158
  72. package/types/server-functions/argument-codec.d.ts +30 -0
  73. package/types/server-functions/client.d.ts +238 -223
  74. package/types/server-functions/flash.d.ts +28 -30
  75. package/types/server-functions/registry.d.ts +105 -0
  76. package/types/server-functions/rich-args.d.ts +1 -10
  77. package/types/server-functions/server.d.ts +539 -531
  78. package/types/server-functions/shared.d.ts +398 -425
  79. package/types/server-functions/uploads.d.ts +50 -0
  80. package/types/server-mock.d.ts +120 -13
  81. package/types/server-observe.d.ts +86 -0
  82. package/types/server.d.ts +571 -422
  83. package/types/trace.d.ts +127 -0
  84. package/LICENSE +0 -21
  85. package/dist/web.cjs +0 -2033
  86. package/frames/dist/client.cjs +0 -2002
  87. package/frames/dist/client.dev.cjs +0 -2022
  88. package/frames/dist/server.cjs +0 -3877
  89. package/serialization/dist/decode.cjs +0 -139
  90. package/serialization/dist/serialization.cjs +0 -261
  91. package/serialization/types-cjs/index.d.cts +0 -182
  92. package/serialization/types-cjs/package.json +0 -3
  93. package/serialization/types-cjs/serializer-decode.d.cts +0 -182
  94. package/server-functions/dist/client.cjs +0 -834
  95. package/server-functions/dist/rich-args.cjs +0 -11
  96. package/server-functions/dist/server.cjs +0 -1242
  97. package/server-functions/dist/server.dev.cjs +0 -1242
  98. package/storage/dist/storage.cjs +0 -12
  99. package/storage/types-cjs/index.d.cts +0 -28
  100. package/storage/types-cjs/package.json +0 -3
  101. package/types/core.d.ts +0 -9
  102. package/types-cjs/client.d.cts +0 -337
  103. package/types-cjs/cookies.d.cts +0 -93
  104. package/types-cjs/core.d.cts +0 -9
  105. package/types-cjs/frames/client.d.cts +0 -36
  106. package/types-cjs/frames/frame-client.d.cts +0 -356
  107. package/types-cjs/frames/frame-sink.d.cts +0 -194
  108. package/types-cjs/frames/frame-transport.d.cts +0 -222
  109. package/types-cjs/frames/serializer.d.cts +0 -182
  110. package/types-cjs/frames/server.d.cts +0 -52
  111. package/types-cjs/index.d.cts +0 -244
  112. package/types-cjs/jsx-properties.d.cts +0 -93
  113. package/types-cjs/jsx.d.cts +0 -4159
  114. package/types-cjs/package.json +0 -3
  115. package/types-cjs/response.d.cts +0 -174
  116. package/types-cjs/serializer-decode.d.cts +0 -182
  117. package/types-cjs/serializer.d.cts +0 -182
  118. package/types-cjs/server-functions/client.d.cts +0 -262
  119. package/types-cjs/server-functions/flash.d.cts +0 -38
  120. package/types-cjs/server-functions/rich-args.d.cts +0 -10
  121. package/types-cjs/server-functions/server.d.cts +0 -681
  122. package/types-cjs/server-functions/shared.d.cts +0 -523
  123. package/types-cjs/server-mock.d.cts +0 -286
  124. package/types-cjs/server.d.cts +0 -544
@@ -1,182 +1,109 @@
1
- // Serialization surface (published as `@solidjs/web/serialization`): the
2
- // runtime's Seroval machinery, exposed for the runtime's own entries and
3
- // for integrations building transports on the same codec. This is
4
- // INTEGRATION-FACING plumbing, not application API — it is exempt from the
5
- // 2.0 stability guarantee and may change between releases. Application and
6
- // router code should configure `codec` on the server-function entries
7
- // instead of importing from here.
8
- import type { Serializer } from "seroval";
9
- import {
10
- JSONCodecOptions,
11
- PluginInfo,
12
- SerializerPlugin,
13
- SerovalNode
14
- } from "./serializer-decode.js";
15
-
16
- // The decode half — `SerovalNode`, the plugin TYPES, `DEFAULT_WEB_PLUGINS`,
17
- // `resolveSerializerPlugins`, `JSONCodecOptions`, `createJSONDeserializer`,
18
- // `createJSONDataTable` — is declared in serializer-decode.d.ts (published
19
- // as `@solidjs/web/serialization/decode`, the module lazy client consumers
20
- // load) and re-exported here so this remains the full surface.
21
- export * from "./serializer-decode.js";
22
-
23
- // ---- Plugin authoring ----
24
- //
25
- // Unlike the rest of this entry, plugin authoring is APPLICATION-FACING —
26
- // it is the supported way to feed the serializers' `plugins` options and
27
- // the server-function entries' `codec.plugins`. The values re-export
28
- // seroval's own (`createPlugin`, `OpaqueReference` — see serializer.js);
29
- // the plugin TYPES live in serializer-decode.d.ts (hand-declared there —
30
- // see its banner for why).
31
-
32
- /**
33
- * Builds a `SerializerPlugin` — seroval's `createPlugin`, re-exported so
34
- * plugin authors stay on the exact seroval instance/version the runtime
35
- * serializes with. Import it from HERE, not from your own `seroval`
36
- * dependency: a plugin built against a different copy/version would not
37
- * fail the build — it would emit nodes the other peer can't interpret.
38
- *
39
- * Application-facing (see the plugin-authoring banner above).
40
- */
41
- export function createPlugin<Value, Info extends PluginInfo>(
42
- plugin: SerializerPlugin<Value, Info>
43
- ): SerializerPlugin<Value, Info>;
44
-
45
- /**
46
- * Seroval's `OpaqueReference`, re-exported from the runtime's own instance
47
- * (an `OpaqueReference` from another seroval copy fails the serializer's
48
- * instanceof check and serializes as a plain value): wraps a value so it
49
- * crosses the wire as its `replacement` (default `undefined`) while
50
- * staying readable in-process through `.value`.
51
- *
52
- * Application-facing (see the plugin-authoring banner above).
53
- */
54
- export class OpaqueReference<V, R = undefined> {
55
- readonly value: V;
56
- readonly replacement?: R;
57
- constructor(value: V, replacement?: R);
58
- }
59
-
1
+ import { Serializer } from "seroval";
2
+ import type { JSONCodecOptions, PluginInfo, SerializerPlugin, SerovalNode } from "./serializer-decode.js";
3
+ export { DEFAULT_WEB_PLUGINS, createJSONDataTable, createJSONDeserializer, resolveSerializerPlugins } from "./serializer-decode.js";
4
+ export type * from "./serializer-decode.js";
60
5
  /**
61
6
  * Options for `createSerializer`.
62
7
  *
63
8
  * Integration-facing; may change (see the entry banner).
64
9
  */
65
10
  export interface WebSerializerOptions {
66
- /** Name of the global object the emitted scripts write resolved values into. */
67
- globalIdentifier: string;
68
- /** Cross-reference scope id, for isolating multiple streams on one page. */
69
- scopeId?: string;
70
- /**
71
- * Seroval feature bitflags to exclude from output. Defaults to disabling
72
- * post-ES2017 features (AggregateError, BigInt typed arrays). Outside
73
- * development, `Error.prototype.stack` is additionally stripped on top of
74
- * any override — serialized stacks leak server paths to the client.
75
- */
76
- disabledFeatures?: number;
77
- /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
78
- plugins?: SerializerPlugin[];
79
- /** Receives each emitted script chunk. */
80
- onData: (result: string) => void;
81
- onError?: (error: unknown) => void;
82
- /** Fires once all async values have settled. */
83
- onDone?: () => void;
11
+ /** Name of the global object the emitted scripts write resolved values into. */
12
+ globalIdentifier: string;
13
+ /** Cross-reference scope id, for isolating multiple streams on one page. */
14
+ scopeId?: string;
15
+ /**
16
+ * Seroval feature bitflags to exclude from output. Defaults to disabling
17
+ * post-ES2017 features (AggregateError, BigInt typed arrays). Outside
18
+ * development, `Error.prototype.stack` is additionally stripped on top of
19
+ * any override — serialized stacks leak server paths to the client.
20
+ */
21
+ disabledFeatures?: number;
22
+ /**
23
+ * Whether serialized `Error`s carry their `.stack`. Defaults to
24
+ * `NODE_ENV === "development"`; set `false` to pin production disclosure
25
+ * to the deployment rather than the ambient variable (#3152 — see
26
+ * `JSONCodecOptions.serializeErrorStacks`).
27
+ */
28
+ serializeErrorStacks?: boolean;
29
+ /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
30
+ plugins?: SerializerPlugin[];
31
+ /** Receives each emitted script chunk. */
32
+ onData: (result: string) => void;
33
+ onError?: (error: unknown) => void;
34
+ /** Fires once all async values have settled. */
35
+ onDone?: () => void;
84
36
  }
85
-
86
- /**
87
- * Creates a streaming Seroval serializer preconfigured with the web plugin
88
- * set and the default feature policy. Emits JavaScript chunks (through
89
- * `onData`) that reconstruct the values under `globalIdentifier` when
90
- * evaluated — the script-injection form of serialization renderers build
91
- * on. For a JSON-based wire codec (no eval on the receiving side), use
92
- * `serializeJSON` / `createJSONDeserializer` instead.
93
- *
94
- * Integration-facing; may change (see the entry banner).
95
- */
96
- export function createSerializer(options: WebSerializerOptions): Serializer;
97
-
98
37
  /**
99
38
  * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
100
- * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
101
- * @internal
102
- */
103
- export type HydrationSerializerOptions = Omit<
104
- WebSerializerOptions,
105
- "globalIdentifier" | "disabledFeatures"
106
- >;
107
-
108
- /**
109
- * Renderer primitive — the serializer SSR uses for hydration output. Pins
110
- * the hydration global (`_$HY.r`) and feature policy; only the wiring
111
- * options (callbacks, scope, extra plugins) are configurable. Not meant
112
- * for hand-written code — custom serialization should use
113
- * `createSerializer` or the JSON codec.
39
+ * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`,
40
+ * `serializeErrorStacks`: its stacks follow `NODE_ENV`).
114
41
  * @internal
115
42
  */
116
- export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
117
-
118
- /**
119
- * Renderer primitive — returns the cross-reference bootstrap script SSR
120
- * emits ahead of hydration data for a render scope. Not meant for
121
- * hand-written code.
122
- * @internal
123
- */
124
- export function getLocalHeaderScript(id?: string): string;
125
-
126
- // ---- JSON codec (server function transports) ----
127
- // (`JSONCodecOptions` and the decode half are declared in
128
- // serializer-decode.d.ts and re-exported above.)
129
-
43
+ export type HydrationSerializerOptions = Omit<WebSerializerOptions, "globalIdentifier" | "disabledFeatures" | "serializeErrorStacks">;
130
44
  /**
131
45
  * Options for `serializeJSON`.
132
46
  *
133
47
  * Integration-facing; may change (see the entry banner).
134
48
  */
135
49
  export interface JSONSerializeOptions extends JSONCodecOptions {
136
- /**
137
- * Receives each serialized node; `initial` is true for the first chunk
138
- * (the source value itself). Async values produce additional chunks as
139
- * they resolve.
140
- */
141
- onParse: (node: SerovalNode, initial: boolean) => void;
142
- onError?: (error: unknown) => void;
143
- /** Fires once all async values have settled. */
144
- onDone?: () => void;
50
+ /**
51
+ * Receives each serialized node; `initial` is true for the first chunk
52
+ * (the source value itself). Async values produce additional chunks as
53
+ * they resolve.
54
+ */
55
+ onParse: (node: SerovalNode, initial: boolean) => void;
56
+ onError?: (error: unknown) => void;
57
+ /** Fires once all async values have settled. */
58
+ onDone?: () => void;
145
59
  }
146
-
147
- /**
148
- * Serializes `value` as SerovalNode chunks delivered through `onParse` —
149
- * the encoding half of the eval-free JSON codec (RPC-style transports;
150
- * the deserializing peer needs no script evaluation, so CSP-safe). Wire
151
- * framing of the nodes is the transport's concern. Returns a cancel
152
- * function that aborts pending async serialization.
153
- *
154
- * Integration-facing; may change (see the entry banner).
155
- */
156
- export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
157
-
158
60
  /** Options for `createJSONSerializer`. */
159
61
  export interface JSONSerializerOptions extends JSONCodecOptions {
160
- /**
161
- * Receives each keyed record — `initial` is true for a key's first node
162
- * (the written value itself); async values patch through later records
163
- * under the same key. The decoding peer is `createJSONDataTable`.
164
- */
165
- onData: (record: { key: string; node: SerovalNode; initial: boolean }) => void;
166
- onError?: (error: unknown) => void;
167
- /** Fires once `flush()` has been called and every pending value settled. */
168
- onDone?: () => void;
62
+ /**
63
+ * Receives each keyed record — `initial` is true for a key's first node
64
+ * (the written value itself); async values patch through later records
65
+ * under the same key. The decoding peer is `createJSONDataTable`.
66
+ */
67
+ onData: (record: {
68
+ key: string;
69
+ node: SerovalNode;
70
+ initial: boolean;
71
+ }) => void;
72
+ onError?: (error: unknown) => void;
73
+ /**
74
+ * Fires once `flush()` has been called and every pending value settled, or
75
+ * once `close()` runs.
76
+ */
77
+ onDone?: () => void;
169
78
  }
170
-
79
+ export declare const createPlugin: <Value, Info extends PluginInfo>(plugin: SerializerPlugin<Value, Info>) => SerializerPlugin<Value, Info>;
80
+ export interface OpaqueReference<V = unknown, R = undefined> {
81
+ readonly value: V;
82
+ readonly replacement?: R;
83
+ }
84
+ export declare const OpaqueReference: {
85
+ new <V, R = undefined>(value: V, replacement?: R): OpaqueReference<V, R>;
86
+ };
171
87
  /**
172
- * The keyed, streaming encoder of the eval-free JSON codec — the render
173
- * stream's data serializer (frames default to it). Each `write(key, value)`
174
- * shares one reference space, so cross-record identity holds; `flush()`
175
- * marks the write set complete (writes after it are dropped, mirroring the
176
- * hydration serializer); `close()` aborts pending async serialization.
88
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
89
+ * set and the default feature policy. Emits JavaScript chunks (through
90
+ * `onData`) that reconstruct the values under `globalIdentifier` when
91
+ * evaluated — the script-injection form of serialization renderers build
92
+ * on. For a JSON-based wire codec (no eval on the receiving side), use
93
+ * `serializeJSON` / `createJSONDeserializer` instead.
94
+ *
95
+ * Integration-facing; may change (see the entry banner).
177
96
  */
178
- export function createJSONSerializer(options: JSONSerializerOptions): {
179
- write(key: string, value: unknown): void;
180
- flush(): void;
181
- close(): void;
97
+ export declare function createSerializer(options: WebSerializerOptions): Serializer;
98
+ export declare function createHydrationSerializer(options: HydrationSerializerOptions): {
99
+ write(key: string, value: unknown): void;
100
+ flush(): void;
101
+ close(): void;
102
+ };
103
+ export declare function getLocalHeaderScript(id?: string): string;
104
+ export declare function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
105
+ export declare function createJSONSerializer(options: JSONSerializerOptions): {
106
+ write(key: string, value: unknown): void;
107
+ flush(): void;
108
+ close(): void;
182
109
  };
@@ -1,23 +1,3 @@
1
- // The DECODE half of the serialization surface (published as
2
- // `@solidjs/web/serialization/decode`): what reading a serialized payload
3
- // needs — `fromCrossJSON`-backed deserializers and the shared plugin set —
4
- // with none of the encode machinery. Lazy client consumers (the frames
5
- // data tables, `deserializeStream`) load this module so the encode half
6
- // never ships to a browser that only reads. The full serializer.d.ts
7
- // re-exports everything here; see its banner for the stability contract
8
- // (integration-facing, exempt from the 2.0 stability guarantee).
9
- // ---- Plugin types ----
10
- //
11
- // Declared here by hand (seroval's published d.ts use extensionless
12
- // ESM-relative imports that `moduleResolution: "nodenext"` cannot follow —
13
- // a bare type re-export would silently degrade the surface to `any` under
14
- // skipLibCheck, and an import would make every entry whose types reach
15
- // this module — the MAIN client entry included, via the server-function
16
- // seam's `JSONCodecOptions` — unimportable from a strict Node16 CJS
17
- // consumer). The declarations mirror seroval ~1.5 exactly; the `~` pin is
18
- // what makes mirroring safe. Plugin AUTHORING (`createPlugin`,
19
- // `OpaqueReference`) lives on the full serialization entry.
20
-
21
1
  /**
22
2
  * Seroval's node shape — the intermediate representation `serializeJSON`
23
3
  * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
@@ -29,59 +9,53 @@
29
9
  * Integration-facing; may change (see the entry banner).
30
10
  */
31
11
  export interface SerovalNode {
32
- /** Node type tag (seroval-internal enum). */
33
- t: number;
34
- /** Reference id, when the node participates in cross-referencing. */
35
- i?: number | undefined;
36
- [key: string]: unknown;
12
+ /** Node type tag (seroval-internal enum). */
13
+ t: number;
14
+ /** Reference id, when the node participates in cross-referencing. */
15
+ i?: number | undefined;
16
+ [key: string]: unknown;
37
17
  }
38
-
39
18
  /** Per-plugin bookkeeping seroval hands each plugin callback. */
40
19
  export interface PluginData {
41
- id: number;
20
+ id: number;
42
21
  }
43
-
44
22
  /**
45
23
  * The shape of a plugin's parsed payload: a map of `SerovalNode`s produced
46
24
  * by the parse contexts, consumed by `serialize`/`deserialize`.
47
25
  */
48
- export type PluginInfo = { [key: string]: SerovalNode };
49
-
26
+ export type PluginInfo = {
27
+ [key: string]: SerovalNode;
28
+ };
50
29
  /** Parse context for `parse.sync`: turns child values into nodes. */
51
30
  export interface SyncParsePluginContext {
52
- parse<T>(current: T): SerovalNode;
31
+ parse<T>(current: T): SerovalNode;
53
32
  }
54
-
55
33
  /** Parse context for `parse.async`: like sync, but child parses await. */
56
34
  export interface AsyncParsePluginContext {
57
- parse<T>(current: T): Promise<SerovalNode>;
35
+ parse<T>(current: T): Promise<SerovalNode>;
58
36
  }
59
-
60
37
  /**
61
38
  * Parse context for `parse.stream`: sync parsing plus the streaming
62
39
  * lifecycle (pending-state tracking, late node emission, cleanup).
63
40
  */
64
41
  export interface StreamParsePluginContext {
65
- parse<T>(current: T): SerovalNode;
66
- parseWithError<T>(current: T): SerovalNode | undefined;
67
- isAlive(): boolean;
68
- pushPendingState(): void;
69
- popPendingState(): void;
70
- onParse(node: SerovalNode): void;
71
- onError(error: unknown): void;
72
- addCleanup(callback: () => void): void;
42
+ parse<T>(current: T): SerovalNode;
43
+ parseWithError<T>(current: T): SerovalNode | undefined;
44
+ isAlive(): boolean;
45
+ pushPendingState(): void;
46
+ popPendingState(): void;
47
+ onParse(node: SerovalNode): void;
48
+ onError(error: unknown): void;
49
+ addCleanup(callback: () => void): void;
73
50
  }
74
-
75
51
  /** Serialize context: renders child nodes to JS source. */
76
52
  export interface SerializePluginContext {
77
- serialize(node: SerovalNode): string;
53
+ serialize(node: SerovalNode): string;
78
54
  }
79
-
80
55
  /** Deserialize context: revives child nodes to runtime values. */
81
56
  export interface DeserializePluginContext {
82
- deserialize<T>(node: SerovalNode): T;
57
+ deserialize<T>(node: SerovalNode): T;
83
58
  }
84
-
85
59
  /**
86
60
  * A Seroval plugin usable with the web serializers — teaches the codec how
87
61
  * to encode/decode a custom value type (`Value` is the value it matches,
@@ -92,44 +66,23 @@ export interface DeserializePluginContext {
92
66
  * Integration-facing; may change (see the entry banner).
93
67
  */
94
68
  export interface SerializerPlugin<Value = any, Info extends PluginInfo = any> {
95
- /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
96
- tag: string;
97
- /** Dependency plugins, resolved ahead of this one. */
98
- extends?: SerializerPlugin[];
99
- /** Whether `value` is this plugin's to encode. */
100
- test(value: unknown): boolean;
101
- /** Parsing modes — provide the ones the transports you target use. */
102
- parse: {
103
- sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
104
- async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
105
- stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
106
- };
107
- /** Renders the parsed payload as JS source (script-injection form). */
108
- serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
109
- /** Revives the parsed payload back into the runtime value. */
110
- deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
69
+ /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
70
+ tag: string;
71
+ /** Dependency plugins, resolved ahead of this one. */
72
+ extends?: SerializerPlugin[];
73
+ /** Whether `value` is this plugin's to encode. */
74
+ test(value: unknown): boolean;
75
+ /** Parsing modes — provide the ones the transports you target use. */
76
+ parse: {
77
+ sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
78
+ async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
79
+ stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
80
+ };
81
+ /** Renders the parsed payload as JS source (script-injection form). */
82
+ serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
83
+ /** Revives the parsed payload back into the runtime value. */
84
+ deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
111
85
  }
112
-
113
- /**
114
- * Baseline plugin set for serializing web-platform values (AbortSignal,
115
- * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
116
- * Applied by every serializer in this module; custom plugins compose ahead
117
- * of it via `resolveSerializerPlugins`.
118
- *
119
- * Integration-facing; may change (see the entry banner).
120
- */
121
- export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
122
-
123
- /**
124
- * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
125
- * first so they can shadow a default for values both would match. Returns a
126
- * fresh array; the defaults are never mutated. Useful when handing a full
127
- * plugin list to another serialization layer.
128
- *
129
- * Integration-facing; may change (see the entry banner).
130
- */
131
- export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
132
-
133
86
  /**
134
87
  * Options shared by both halves of the JSON codec. All of them must match
135
88
  * on the serializing and deserializing peer or payloads will not
@@ -139,44 +92,150 @@ export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): Se
139
92
  * Integration-facing; may change (see the entry banner).
140
93
  */
141
94
  export interface JSONCodecOptions {
142
- /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
143
- plugins?: SerializerPlugin[];
144
- /**
145
- * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
146
- * (payloads may come from an untrusted peer). Must match on both peers.
147
- * Outside development, the encoding side additionally strips
148
- * `Error.prototype.stack` on top of any override — serialized stacks leak
149
- * server paths to the client. Decoding stays permissive, so payloads from
150
- * a development peer still round-trip.
151
- */
152
- disabledFeatures?: number;
153
- /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
154
- depthLimit?: number;
95
+ /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
96
+ plugins?: SerializerPlugin[];
97
+ /**
98
+ * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
99
+ * (payloads may come from an untrusted peer). Must match on both peers.
100
+ * Outside development, the encoding side additionally strips
101
+ * `Error.prototype.stack` on top of any override — serialized stacks leak
102
+ * server paths to the client. Decoding stays permissive, so payloads from
103
+ * a development peer still round-trip.
104
+ */
105
+ disabledFeatures?: number;
106
+ /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
107
+ depthLimit?: number;
108
+ /**
109
+ * Whether serialized `Error`s carry their `.stack` — server file paths,
110
+ * internal function names, the shape of the deployment — to the peer.
111
+ * Defaults to `NODE_ENV === "development"`, but that signal describes the
112
+ * PROCESS, not the artifact: a production build running with
113
+ * `NODE_ENV=development` (a base image, a stray dotenv) ships stacks to
114
+ * the wire — including for errors marked safe with `markSafeError`, whose
115
+ * stacks traverse application code (#3152). Set `false` to pin production
116
+ * disclosure regardless of the ambient variable. Encode-side only; the
117
+ * decode side is always permissive, so it need not match peers.
118
+ */
119
+ serializeErrorStacks?: boolean;
155
120
  }
156
-
157
- /**
158
- * Creates the decoding counterpart of `serializeJSON`. Cross-references
159
- * between chunks resolve through state shared across calls, so all chunks
160
- * from one stream must go through the same deserializer instance. The first
161
- * chunk's return value is the decoded source value; feeding later chunks
162
- * settles the async values referenced inside it.
163
- *
164
- * Integration-facing; may change (see the entry banner).
165
- */
166
- export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
167
-
168
121
  /**
169
122
  * A resident, response-scoped decode table over the keyed JSON codec: apply
170
123
  * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
171
- * `resolve`. The frames client host wires one per response
172
- * (`applyData: c => table.apply(c)`).
124
+ * `resolve`, and `close` it when the response ends. The frames client host
125
+ * wires one per response (`applyData: c => table.apply(c)`,
126
+ * `closeData: (…) => table.close(error)`).
127
+ *
128
+ * A `{ $ref }` to a key no `apply` has delivered yet is a PENDING READ the
129
+ * table owns (`@internal` behaviour — the frames client is its consumer): a
130
+ * promise marked `s = 0`, settled by the key's `apply` and rejected by
131
+ * `close` — the response ended without delivering the key, so a value that
132
+ * never comes is an error where it is read, not a silence. Stamped `s`/`v`
133
+ * as it settles (`1` fulfilled, `2` rejected — the hydration serializer's
134
+ * marks, which a reader adopts synchronously).
173
135
  *
174
136
  * Integration-facing; may change (see the entry banner). This serialization
175
137
  * entry is the single home of the data table — the frames client consumes
176
138
  * it internally rather than re-exporting it.
177
139
  */
178
140
  export interface JSONDataTable {
179
- apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
180
- resolve<T = unknown>(ref: { $ref: string }): T;
141
+ apply(chunk: {
142
+ key?: string;
143
+ node?: unknown;
144
+ initial?: boolean;
145
+ }): void;
146
+ /**
147
+ * The value under `ref`, or the table's pending read of it: a promise
148
+ * marked `s = 0` carrying `c`, the callbacks the table runs in the
149
+ * `apply` / `close` that settles it — the key delivered (whatever its
150
+ * value's shape: a delivered promise is adopted by the read, the
151
+ * callbacks do not wait for it) or the table closed.
152
+ */
153
+ resolve<T = unknown>(ref: {
154
+ $ref: string;
155
+ }): T;
156
+ /**
157
+ * The response has ended: every pending read of a key it never
158
+ * delivered rejects — with `error` (the response's own) when given, with
159
+ * an `Error` naming the key otherwise. Idempotent.
160
+ */
161
+ close(error?: unknown): void;
181
162
  }
182
- export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;
163
+ /**
164
+ * Baseline plugin set for serializing web-platform values. Shared by the
165
+ * hydration serializer and any consumer building its own serializer (e.g.
166
+ * server function transports). Plugin objects carry both their serialize
167
+ * and deserialize halves, so the set lives on the decode side and the
168
+ * encode module composes over it.
169
+ */
170
+ export declare const DEFAULT_WEB_PLUGINS: readonly ({
171
+ tag: string;
172
+ test(value: any): boolean;
173
+ parse: {
174
+ sync(): never;
175
+ async(value: any, ctx: any): Promise<{
176
+ a: number;
177
+ i: any;
178
+ }>;
179
+ stream: (value: any, ctx: any) => {
180
+ a: number;
181
+ i: any;
182
+ };
183
+ };
184
+ serialize(node: any, ctx: any): string;
185
+ deserialize(node: any, ctx: any): any;
186
+ } | import("seroval").Plugin<AbortSignal, {
187
+ reason?: import("seroval").SerovalNode;
188
+ controller?: import("seroval").SerovalNode;
189
+ factory?: import("seroval").SerovalNode;
190
+ }> | import("seroval").Plugin<CustomEvent<any>, {
191
+ type: import("seroval").SerovalNode;
192
+ options: import("seroval").SerovalNode;
193
+ }> | import("seroval").Plugin<DOMException, {
194
+ name: import("seroval").SerovalNode;
195
+ message: import("seroval").SerovalNode;
196
+ }> | import("seroval").Plugin<Event, {
197
+ type: import("seroval").SerovalNode;
198
+ options: import("seroval").SerovalNode;
199
+ }> | import("seroval").Plugin<FormData, {
200
+ factory: import("seroval").SerovalNode;
201
+ entries: import("seroval").SerovalNode;
202
+ }> | import("seroval").Plugin<Headers, {
203
+ value: import("seroval").SerovalNode;
204
+ }> | import("seroval").Plugin<ReadableStream<any>, {
205
+ factory: import("seroval").SerovalNode;
206
+ stream: import("seroval").SerovalNode;
207
+ }> | import("seroval").Plugin<Request, {
208
+ url: import("seroval").SerovalNode;
209
+ options: import("seroval").SerovalNode;
210
+ }> | import("seroval").Plugin<Response, {
211
+ body: import("seroval").SerovalNode;
212
+ options: import("seroval").SerovalNode;
213
+ }> | import("seroval").Plugin<URLSearchParams, {
214
+ value: import("seroval").SerovalNode;
215
+ }> | import("seroval").Plugin<URL, {
216
+ value: import("seroval").SerovalNode;
217
+ }>)[]; /**
218
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
219
+ * first so they can shadow a default for values both would match. Returns a
220
+ * fresh array; the defaults are never mutated. Useful when handing a full
221
+ * plugin list to another serialization layer.
222
+ *
223
+ * Integration-facing; may change (see the entry banner).
224
+ */
225
+ export declare function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
226
+ export declare function resolveCodecOptions(options?: JSONCodecOptions): {
227
+ plugins: any;
228
+ disabledFeatures: number;
229
+ depthLimit: number;
230
+ serializeErrorStacks: boolean;
231
+ }; /**
232
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
233
+ * between chunks resolve through state shared across calls, so all chunks
234
+ * from one stream must go through the same deserializer instance. The first
235
+ * chunk's return value is the decoded source value; feeding later chunks
236
+ * settles the async values referenced inside it.
237
+ *
238
+ * Integration-facing; may change (see the entry banner).
239
+ */
240
+ export declare function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
241
+ export declare function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;