@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.
- package/README.md +1 -1
- package/dist/server.dev.js +5065 -0
- package/dist/server.js +1757 -355
- package/dist/{server.cjs → server.observe.js} +1951 -558
- package/dist/{dev.cjs → web.dev.js} +945 -550
- package/dist/web.js +635 -332
- package/dist/{dev.js → web.observe.js} +688 -403
- package/frames/dist/assets.js +92 -0
- package/frames/dist/client.dev.js +1296 -1198
- package/frames/dist/client.js +1128 -1191
- package/frames/dist/client.observe.js +2041 -0
- package/frames/dist/regions.js +171 -0
- package/frames/dist/server.dev.js +2549 -0
- package/frames/dist/server.js +1688 -3005
- package/frames/dist/server.observe.js +2548 -0
- package/frames/dist/trace.js +45 -0
- package/frames/dist/wire.js +594 -0
- package/frames/package.json +2 -25
- package/package.json +244 -256
- package/performance-tracks/dist/performance-tracks.dev.js +679 -0
- package/performance-tracks/dist/performance-tracks.js +6 -0
- package/performance-tracks/dist/performance-tracks.observe.js +667 -0
- package/performance-tracks/package.json +7 -0
- package/performance-tracks/types/index.d.ts +69 -0
- package/serialization/decode/package.json +2 -15
- package/serialization/dist/decode.js +121 -25
- package/serialization/dist/serialization.js +242 -88
- package/serialization/package.json +2 -15
- package/serialization/types/index.d.ts +85 -158
- package/serialization/types/serializer-decode.d.ts +173 -114
- package/serialization/types/serializer.d.ts +109 -0
- package/server-functions/dist/client.dev.js +1462 -0
- package/server-functions/dist/client.js +667 -165
- package/server-functions/dist/client.observe.js +1441 -0
- package/server-functions/dist/rich-args.js +84 -1
- package/server-functions/dist/server.dev.js +2714 -297
- package/server-functions/dist/server.js +2595 -271
- package/server-functions/dist/server.observe.js +3594 -0
- package/server-functions/package.json +2 -35
- package/server-functions/rich-args/package.json +2 -15
- package/skills/server-components/SKILL.md +117 -0
- package/storage/package.json +2 -15
- package/types/client.d.ts +342 -288
- package/types/constants.d.ts +22 -0
- package/types/cookies.d.ts +32 -84
- package/types/diagnostics.d.ts +80 -0
- package/types/frames/assets-tier.d.ts +78 -0
- package/types/frames/client.d.ts +40 -1
- package/types/frames/frame-client.d.ts +443 -280
- package/types/frames/frame-container-plugin.d.ts +64 -0
- package/types/frames/frame-morph.d.ts +29 -0
- package/types/frames/frame-sink.d.ts +141 -161
- package/types/frames/frame-transport.d.ts +263 -184
- package/types/frames/regions-tier.d.ts +60 -0
- package/types/frames/serializer-decode.d.ts +241 -0
- package/types/frames/serializer.d.ts +85 -158
- package/types/frames/server.d.ts +2 -2
- package/types/frames/trace-tier.d.ts +2 -0
- package/types/frames/tree-rewrite.d.ts +39 -0
- package/types/frames/wire-tier.d.ts +169 -0
- package/types/head.d.ts +20 -0
- package/types/index.d.ts +98 -81
- package/types/index.server.d.ts +159 -0
- package/types/jsx.d.ts +49 -44
- package/types/observe.d.ts +535 -0
- package/types/reconcile.d.ts +1 -0
- package/types/render.d.ts +11 -0
- package/types/request-error-hook.d.ts +5 -0
- package/types/response.d.ts +95 -147
- package/types/serializer-decode.d.ts +173 -114
- package/types/serializer.d.ts +85 -158
- package/types/server-functions/argument-codec.d.ts +30 -0
- package/types/server-functions/client.d.ts +238 -223
- package/types/server-functions/flash.d.ts +28 -30
- package/types/server-functions/registry.d.ts +105 -0
- package/types/server-functions/rich-args.d.ts +1 -10
- package/types/server-functions/server.d.ts +539 -531
- package/types/server-functions/shared.d.ts +398 -425
- package/types/server-functions/uploads.d.ts +50 -0
- package/types/server-mock.d.ts +120 -13
- package/types/server-observe.d.ts +86 -0
- package/types/server.d.ts +571 -422
- package/types/trace.d.ts +127 -0
- package/LICENSE +0 -21
- package/dist/web.cjs +0 -2033
- package/frames/dist/client.cjs +0 -2002
- package/frames/dist/client.dev.cjs +0 -2022
- package/frames/dist/server.cjs +0 -3877
- package/serialization/dist/decode.cjs +0 -139
- package/serialization/dist/serialization.cjs +0 -261
- package/serialization/types-cjs/index.d.cts +0 -182
- package/serialization/types-cjs/package.json +0 -3
- package/serialization/types-cjs/serializer-decode.d.cts +0 -182
- package/server-functions/dist/client.cjs +0 -834
- package/server-functions/dist/rich-args.cjs +0 -11
- package/server-functions/dist/server.cjs +0 -1242
- package/server-functions/dist/server.dev.cjs +0 -1242
- package/storage/dist/storage.cjs +0 -12
- package/storage/types-cjs/index.d.cts +0 -28
- package/storage/types-cjs/package.json +0 -3
- package/types/core.d.ts +0 -9
- package/types-cjs/client.d.cts +0 -337
- package/types-cjs/cookies.d.cts +0 -93
- package/types-cjs/core.d.cts +0 -9
- package/types-cjs/frames/client.d.cts +0 -36
- package/types-cjs/frames/frame-client.d.cts +0 -356
- package/types-cjs/frames/frame-sink.d.cts +0 -194
- package/types-cjs/frames/frame-transport.d.cts +0 -222
- package/types-cjs/frames/serializer.d.cts +0 -182
- package/types-cjs/frames/server.d.cts +0 -52
- package/types-cjs/index.d.cts +0 -244
- package/types-cjs/jsx-properties.d.cts +0 -93
- package/types-cjs/jsx.d.cts +0 -4159
- package/types-cjs/package.json +0 -3
- package/types-cjs/response.d.cts +0 -174
- package/types-cjs/serializer-decode.d.cts +0 -182
- package/types-cjs/serializer.d.cts +0 -182
- package/types-cjs/server-functions/client.d.cts +0 -262
- package/types-cjs/server-functions/flash.d.cts +0 -38
- package/types-cjs/server-functions/rich-args.d.cts +0 -10
- package/types-cjs/server-functions/server.d.cts +0 -681
- package/types-cjs/server-functions/shared.d.cts +0 -523
- package/types-cjs/server-mock.d.cts +0 -286
- package/types-cjs/server.d.cts +0 -544
package/types/response.d.ts
CHANGED
|
@@ -1,174 +1,122 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Envelope pairing HTTP metadata
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
42
|
-
|
|
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
|
|
63
|
-
*
|
|
64
|
-
*
|
|
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
|
-
*
|
|
93
|
-
*
|
|
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
|
|
96
|
-
|
|
54
|
+
export declare const REVALIDATE_HEADER = "X-Revalidate";
|
|
97
55
|
/**
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
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
|
|
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
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
|
119
|
-
*
|
|
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
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
*
|
|
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):
|
|
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
|
|
139
|
-
* them when omitted.
|
|
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
|
-
*
|
|
147
|
-
*
|
|
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):
|
|
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.
|
|
158
|
-
*
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
*
|
|
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
|
-
*
|
|
168
|
-
*
|
|
169
|
-
*
|
|
170
|
-
*
|
|
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):
|
|
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
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
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 = {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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
|
-
|
|
53
|
+
serialize(node: SerovalNode): string;
|
|
78
54
|
}
|
|
79
|
-
|
|
80
55
|
/** Deserialize context: revives child nodes to runtime values. */
|
|
81
56
|
export interface DeserializePluginContext {
|
|
82
|
-
|
|
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
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
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
|
|
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
|
-
|
|
180
|
-
|
|
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
|
-
|
|
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;
|