@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,174 +1,122 @@
1
1
  /**
2
- * Envelope pairing HTTP metadata (a `Response`) with an in-memory value.
3
- * Produced by `respond()` and by server-function `transformResult`
4
- * implementations (e.g. single-flight payloads). The HTTP handler forwards
5
- * `response`'s headers and (non-redirect) status and encodes `value` as the
6
- * body through the codec, while client-only integrations read `value`
7
- * directly — no reparse. Mostly consumed by integrations (routers);
8
- * application code usually just returns what `respond()` gives it.
2
+ * Envelope pairing HTTP metadata with a value. Produced by `respond()` and
3
+ * by server-function `transformResult` implementations (e.g. single-flight
4
+ * payloads); the HTTP handler forwards `response`'s headers and
5
+ * (non-redirect) status and encodes `value` as the body through the codec,
6
+ * while client-only integrations read `value` directly — no reparse.
7
+ *
8
+ * The envelope IS a `Response` — the given response's body, status and
9
+ * headers — so a consumer that knows nothing of Solid (a filesystem
10
+ * router's API dispatch, any fetch-style handler) answers with it as-is.
11
+ * `response` is the envelope itself, or `undefined` when constructed
12
+ * without one.
9
13
  */
10
- export class ResponseEnvelope<T = unknown> {
11
- constructor(response: Response | undefined, value: T);
12
- /** The HTTP metadata: status and headers to forward (body ignored by integrations). */
13
- response: Response | undefined;
14
- /** The structured value the caller receives. */
15
- value: T;
14
+ export interface ResponseEnvelope<T = unknown> extends Response {
15
+ response: Response | undefined;
16
+ value: T;
16
17
  }
17
-
18
- /**
19
- * Whether `value` is a `ResponseEnvelope`. Uses a registered-symbol brand
20
- * rather than `instanceof`, so it stays correct when separately bundled
21
- * entries each carry a copy of the class. Integrations should always use
22
- * this over `instanceof`.
23
- */
24
- export function isResponseEnvelope(value: unknown): value is ResponseEnvelope;
25
-
26
- /**
27
- * Registered-symbol brand (`Symbol.for("solid.Href")`) marking URL-bearing
28
- * values. Declared `unique symbol` type-side; the runtime value is the
29
- * registered symbol, so separately bundled copies agree on identity.
30
- */
18
+ export declare const ResponseEnvelope: {
19
+ new <T>(response: Response | undefined, value: T): ResponseEnvelope<T>;
20
+ };
21
+ /** Whether `value` is a `ResponseEnvelope` (robust across module copies). */
22
+ export declare function isResponseEnvelope(value: unknown): value is ResponseEnvelope;
31
23
  export declare const HREF: unique symbol;
32
-
33
- /**
34
- * A URL-bearing value: coerces to its URL via `toString()` and carries the
35
- * `HREF` registered-symbol brand. Integrations mint these (e.g. a router's
36
- * typed path objects answer the brand from their proxy) and URL-accepting
37
- * APIs like `redirect()` accept them alongside plain strings. The brand is
38
- * what makes the type meaningful — every object has `toString()`.
39
- */
40
24
  export interface Href {
41
- [HREF]: true;
42
- toString(): string;
25
+ /**
26
+ * The brand doubles as a channel: when the slot holds a string it is the
27
+ * value's *logical* path — the routable pathname before an integration's
28
+ * display rendering (eg. a hash router's `#` prefix). `redirect()` prefers
29
+ * it over coercion so Location headers carry routable paths; `toString()`
30
+ * remains the display href for the DOM. `true` brands a value whose
31
+ * string form is already logical.
32
+ */
33
+ [HREF]: true | string;
34
+ toString(): string;
43
35
  }
44
-
45
- /**
46
- * Whether `value` is an `Href`-branded URL-bearing value. Registered-symbol
47
- * check, so it stays correct across duplicated module instances — same
48
- * rationale as `isResponseEnvelope`.
49
- */
50
- export function isHref(value: unknown): value is Href;
51
-
52
- /**
53
- * Registered-symbol brand (`Symbol.for("solid.SafeError")`) marking a thrown
54
- * value as safe to serialize to the client verbatim. Declared `unique
55
- * symbol` type-side; the runtime value is the registered symbol, so
56
- * separately bundled copies agree on identity.
57
- */
36
+ /** Whether `value` is an `Href`-branded URL-bearing value. */
37
+ export declare function isHref(value: unknown): value is Href;
58
38
  export declare const SAFE_ERROR: unique symbol;
59
-
60
39
  /**
61
40
  * Marks `error` as safe to serialize to the client verbatim, opting it out
62
- * of the server-function handler's production error sanitization.
63
- *
64
- * By default a plain `Error` thrown from a server function is sanitized to a
65
- * generic `Error` outside the dev build (the `development` export condition
66
- * selects the full-fidelity copy; every other resolution sanitizes):
67
- * its `message`, `stack`, and own-properties are dropped so a driver/ORM
68
- * error can't leak a failing query or connection string over the wire.
69
- * Dev builds keep full fidelity. This is the escape hatch for errors whose
70
- * content is *intentional* client-facing information — brand them and their
71
- * message/properties travel intact in every environment.
72
- *
73
- * The brand is a non-enumerable, symbol-keyed property, so it never itself
74
- * serializes as an own-property. Sets the brand and returns the same value.
75
- *
76
- * @example
77
- * ```ts
78
- * import { markSafeError } from "@solidjs/web";
79
- *
80
- * async function transfer(amount: number) {
81
- * "use server";
82
- * if (amount > balance) {
83
- * // The user must see this message; opt out of sanitization.
84
- * throw markSafeError(new Error("Insufficient funds"));
85
- * }
86
- * }
87
- * ```
41
+ * of production error sanitization (see `handleServerFunctionRequest`). Use
42
+ * for errors whose message/properties are intentional client-facing content.
43
+ * Returns the same value for convenient `throw markSafeError(new Error(...))`.
88
44
  */
89
- export function markSafeError<E>(error: E): E;
90
-
45
+ export declare function markSafeError<E>(error: E): E;
46
+ /** Whether `value` is branded safe to serialize (robust across module copies). */
47
+ export declare function isSafeError(value: unknown): value is Error;
91
48
  /**
92
- * Whether `value` is branded safe to serialize (via `markSafeError`).
93
- * Registered-symbol check, correct across duplicated module instances.
49
+ * Response header naming the cache keys a mutation invalidated, comma
50
+ * separated. Set by the helpers below and read by the client transport and
51
+ * by integrations; core never inspects the keys, so how they are matched
52
+ * (prefixes, exact names, namespaces) is the integration's business.
94
53
  */
95
- export function isSafeError(value: unknown): value is Error;
96
-
54
+ export declare const REVALIDATE_HEADER = "X-Revalidate";
97
55
  /**
98
- * Response header naming the cache keys a mutation invalidated
99
- * (`"X-Revalidate"`), comma separated. The response helpers below set it
100
- * from their `revalidate` option; the client transport treats its presence
101
- * as control flow, and integrations read it to invalidate their own cache.
102
- * Core never inspects the keys, so how they are matched (prefixes, exact
103
- * names, namespaces) is the integration's business.
56
+ * The reserved `revalidate` key meaning every entry, in every cache: the
57
+ * host-independent spelling of "all" (as `Clear-Site-Data: "*"` spells it),
58
+ * for authors who mean it rather than a host's default. Stands alone —
59
+ * naming it beside other keys is refused, since "everything and also
60
+ * these" is a mistake, not a scope.
104
61
  */
105
- export const REVALIDATE_HEADER: string;
106
-
62
+ export declare const REVALIDATE_ALL = "*";
107
63
  /** `ResponseInit` accepted by the response helpers, plus `revalidate`. */
108
64
  export interface ResponseHelperInit extends ResponseInit {
109
- /**
110
- * Cache keys the mutation invalidated, carried in the `X-Revalidate`
111
- * header. Opaque to the protocol — the integration's keyed cache (e.g.
112
- * the router's `query` cache) assigns them meaning.
113
- */
114
- revalidate?: string | string[];
65
+ /**
66
+ * The cache keys the mutation invalidated, sent as the `X-Revalidate`
67
+ * header for the client's integrations to apply. Three declarations, three
68
+ * scopes: omitted sends no header — the host's default (Solid Router
69
+ * revalidates everything after any mutation, form action or direct call;
70
+ * a router without that convention reloads only what it owns); an empty
71
+ * list (or `""`) sends an empty header — nothing, explicitly; `REVALIDATE_ALL` (`"*"`) — every entry,
72
+ * whatever the host's default. How named keys are matched (prefixes,
73
+ * namespaces) is each integration's business.
74
+ */
75
+ revalidate?: string | string[];
115
76
  }
116
-
77
+ /** @internal */
78
+ export declare const RESPONSE_HEADER_VALUE_LIMIT = 4096;
117
79
  /**
118
- * Response redirecting to `url` (default status 302). Return (or throw) it
119
- * from a server function — the HTTP handler forwards the redirect for the
120
- * client integration to follow — or return it from a client-side action,
121
- * where the integration interprets it in memory. Same object, same
122
- * meaning, both sides.
80
+ * Response redirecting to `url` (default 302). `revalidate` names the
81
+ * cache keys the mutation invalidated.
123
82
  *
124
- * @example
125
- * ```ts
126
- * import { redirect } from "@solidjs/web";
127
- *
128
- * async function login(form: FormData) {
129
- * "use server";
130
- * // ...
131
- * return redirect("/dashboard", { revalidate: "session" });
132
- * }
133
- * ```
83
+ * Typed so it never shows up in the type of the function returning it: a
84
+ * redirect is control flow for the integration to act on, not a value.
85
+ * `T` defaults to `never`, which vanishes from the inferred return type's
86
+ * union; where the context expects a type (an annotated return, a
87
+ * `Response`-typed request handler) `T` takes it. A literal `never` return
88
+ * would also mark code after a bare call unreachable; a type parameter
89
+ * does not. At runtime it is a real `Response`.
134
90
  */
135
- export function redirect(url: string | Href, init?: number | ResponseHelperInit): Response;
136
-
91
+ export declare function redirect<T = never>(url: string | Href, init?: number | ResponseHelperInit): T;
137
92
  /**
138
- * Empty response requesting revalidation of the named cache keys — all of
139
- * them when omitted. For mutations whose only effect the caller needs is
140
- * "refetch your data".
141
- *
142
- * @example
143
- * ```ts
144
- * import { reload } from "@solidjs/web";
93
+ * Empty response requesting revalidation of the named cache keys (all of
94
+ * them when omitted).
145
95
  *
146
- * async function addTodo(title: string) {
147
- * "use server";
148
- * await db.insert(title);
149
- * return reload({ revalidate: "todos" });
150
- * }
151
- * ```
96
+ * Typed as `redirect` is, for the same reason: it never shows up in the
97
+ * type of the function returning it. At runtime it is a real `Response`.
152
98
  */
153
- export function reload(init?: ResponseHelperInit): Response;
154
-
99
+ export declare function reload<T = never>(init?: ResponseHelperInit): T;
100
+ /**
101
+ * Statuses HTTP forbids a body on — the `Response` constructor enforces it
102
+ * by throwing on ANY body, `JSON.stringify(undefined)`'s `"undefined"`
103
+ * included. Shared with the server-function encoder, which answers void
104
+ * results on these statuses with a real null-body response and reports
105
+ * value-carrying ones as authoring errors (#3095).
106
+ * @internal
107
+ */
108
+ export declare const NULL_BODY_STATUSES: ReadonlySet<number>;
155
109
  /**
156
110
  * A value paired with response metadata (status, headers, `revalidate`) —
157
- * for the things a naked return can't express. Scripted callers receive
158
- * `value` transparently (the transport unwraps the envelope), and
159
- * progressive enhancement stays invisible: the carried response holds a
160
- * plain JSON body so consumers without the client runtime (no-JS form
161
- * posts, direct HTTP) get real JSON.
162
- *
163
- * @example
164
- * ```ts
165
- * import { respond } from "@solidjs/web";
111
+ * for the things a naked return can't express. Progressive enhancement
112
+ * stays invisible: the carried response holds a plain JSON body so
113
+ * consumers without the client runtime (no-JS form posts, direct HTTP)
114
+ * get real JSON, while integrations read `value` — no reparse. The body is
115
+ * encoded when read, so `value` may be anything a plain return may.
166
116
  *
167
- * async function createItem(input: Item) {
168
- * "use server";
169
- * const item = await db.create(input);
170
- * return respond(item, { status: 201, revalidate: "items" });
171
- * }
172
- * ```
117
+ * Typed as `value`'s type: every caller of the function returning it —
118
+ * over HTTP or in-process — receives the value, never the envelope. At
119
+ * runtime it is a `ResponseEnvelope`, a real `Response` that integrations
120
+ * recognize with `isResponseEnvelope()`.
173
121
  */
174
- export function respond<T>(value: T, init?: ResponseHelperInit): ResponseEnvelope<T>;
122
+ export declare function respond<T>(value: T, init?: ResponseHelperInit): T;
@@ -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;