@solidjs/web 2.0.0-rc.7 → 2.0.0-rc.9

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 (88) hide show
  1. package/dist/server.dev.js +638 -124
  2. package/dist/server.js +445 -94
  3. package/dist/{server.dev.cjs → server.observe.js} +602 -416
  4. package/dist/web.dev.js +229 -49
  5. package/dist/web.js +194 -46
  6. package/dist/{web.cjs → web.observe.js} +290 -275
  7. package/frames/dist/client.dev.js +103 -4
  8. package/frames/dist/client.js +5 -2
  9. package/frames/dist/{client.dev.cjs → client.observe.js} +139 -79
  10. package/frames/dist/server.dev.js +540 -79
  11. package/frames/dist/server.js +371 -52
  12. package/frames/dist/{server.cjs → server.observe.js} +544 -140
  13. package/frames/package.json +15 -21
  14. package/package.json +145 -294
  15. package/serialization/decode/package.json +3 -9
  16. package/serialization/package.json +3 -9
  17. package/serialization/types/serializer-decode.d.ts +49 -2
  18. package/server-functions/dist/{client.cjs → client.dev.js} +140 -107
  19. package/server-functions/dist/client.js +74 -69
  20. package/server-functions/dist/client.observe.js +1102 -0
  21. package/server-functions/dist/server.dev.js +430 -41
  22. package/server-functions/dist/server.js +367 -40
  23. package/server-functions/dist/{server.cjs → server.observe.js} +430 -85
  24. package/server-functions/package.json +15 -21
  25. package/server-functions/rich-args/package.json +3 -9
  26. package/storage/package.json +3 -9
  27. package/types/client.d.ts +39 -1
  28. package/types/diagnostics.d.ts +24 -0
  29. package/types/frames/frame-transport.d.ts +1 -1
  30. package/types/frames/serializer-decode.d.ts +49 -2
  31. package/types/index.d.ts +25 -15
  32. package/types/index.server.d.ts +35 -8
  33. package/types/jsx.d.ts +15 -4
  34. package/types/observe.d.ts +294 -0
  35. package/types/response.d.ts +18 -0
  36. package/types/serializer-decode.d.ts +49 -2
  37. package/types/server-functions/client.d.ts +32 -22
  38. package/types/server-functions/server.d.ts +55 -41
  39. package/types/server-functions/shared.d.ts +39 -9
  40. package/types/server-mock.d.ts +26 -4
  41. package/types/server-observe.d.ts +39 -0
  42. package/types/server.d.ts +105 -6
  43. package/types/trace.d.ts +79 -0
  44. package/dist/server.cjs +0 -3708
  45. package/dist/web.dev.cjs +0 -2285
  46. package/frames/dist/client.cjs +0 -2043
  47. package/frames/dist/server.dev.cjs +0 -4584
  48. package/serialization/dist/decode.cjs +0 -155
  49. package/serialization/dist/serialization.cjs +0 -275
  50. package/serialization/types-cjs/index.d.cts +0 -101
  51. package/serialization/types-cjs/package.json +0 -3
  52. package/serialization/types-cjs/serializer-decode.d.cts +0 -172
  53. package/serialization/types-cjs/serializer.d.cts +0 -101
  54. package/server-functions/dist/rich-args.cjs +0 -11
  55. package/server-functions/dist/server.dev.cjs +0 -2409
  56. package/storage/dist/storage.cjs +0 -12
  57. package/storage/types-cjs/index.d.cts +0 -28
  58. package/storage/types-cjs/package.json +0 -3
  59. package/types-cjs/client.d.cts +0 -197
  60. package/types-cjs/constants.d.cts +0 -20
  61. package/types-cjs/cookies.d.cts +0 -41
  62. package/types-cjs/frames/client.d.cts +0 -36
  63. package/types-cjs/frames/frame-client.d.cts +0 -370
  64. package/types-cjs/frames/frame-container-plugin.d.cts +0 -71
  65. package/types-cjs/frames/frame-sink.d.cts +0 -92
  66. package/types-cjs/frames/frame-transport.d.cts +0 -189
  67. package/types-cjs/frames/serializer-decode.d.cts +0 -172
  68. package/types-cjs/frames/serializer.d.cts +0 -101
  69. package/types-cjs/frames/server.d.cts +0 -52
  70. package/types-cjs/head.d.cts +0 -19
  71. package/types-cjs/index.d.cts +0 -191
  72. package/types-cjs/index.server.d.cts +0 -147
  73. package/types-cjs/jsx-properties.d.cts +0 -93
  74. package/types-cjs/jsx.d.cts +0 -4146
  75. package/types-cjs/package.json +0 -3
  76. package/types-cjs/reconcile.d.cts +0 -1
  77. package/types-cjs/render.d.cts +0 -6
  78. package/types-cjs/response.d.cts +0 -81
  79. package/types-cjs/serializer-decode.d.cts +0 -172
  80. package/types-cjs/serializer.d.cts +0 -101
  81. package/types-cjs/server-functions/client.d.cts +0 -184
  82. package/types-cjs/server-functions/flash.d.cts +0 -36
  83. package/types-cjs/server-functions/registry.d.cts +0 -100
  84. package/types-cjs/server-functions/rich-args.d.cts +0 -1
  85. package/types-cjs/server-functions/server.d.cts +0 -546
  86. package/types-cjs/server-functions/shared.d.cts +0 -283
  87. package/types-cjs/server-mock.d.cts +0 -337
  88. package/types-cjs/server.d.cts +0 -408
@@ -0,0 +1,294 @@
1
+ import type { ChangeOrigin, Records } from "solid-js";
2
+ import type { RequestEvent } from "./server.js";
3
+ /**
4
+ * The records channel — `OBSERVE.records` — or `undefined` outside observe
5
+ * builds and where no observing core has loaded. An emitter's first check.
6
+ */
7
+ export declare function records(): Records | undefined;
8
+ /**
9
+ * One server function execution, delivered on
10
+ * `OBSERVE.records.subscribe("invocation", …)` once it settled.
11
+ * Serializable — the live handles (`event`, `args`, the thrown error)
12
+ * travel beside it in `InvocationLive`, not on it.
13
+ */
14
+ export interface InvocationEvent {
15
+ /** The function id — the name a span or a log line carries. */
16
+ id: string;
17
+ /** `true` for an in-process call during SSR, `false` for HTTP dispatch. */
18
+ direct: boolean;
19
+ /** `performance.now()` when the execution started. */
20
+ at: number;
21
+ /**
22
+ * Start → settle of the execution, in milliseconds. The execution is the
23
+ * `wrapInvocation`-wrapped run: what the request spent on the call,
24
+ * policy included (auth guards, per-function middleware). A generator or
25
+ * stream body settles at handoff — see `deferred`.
26
+ */
27
+ durationMs: number;
28
+ outcome: "ok" | "error";
29
+ /**
30
+ * The settled value is a body the caller drives — a generator, a
31
+ * `ReadableStream` — so `durationMs` covers the call that produced it,
32
+ * not its consumption.
33
+ */
34
+ deferred?: true;
35
+ /**
36
+ * Direct calls only: the hydration id of the `<Loading>` boundary whose
37
+ * render pass made the call — the `id` of that boundary's `"boundary"`
38
+ * record — so a boundary's wait can be read as the server-function calls
39
+ * it consisted of. Absent for a call outside any boundary's pass (the
40
+ * shell, or HTTP dispatch).
41
+ */
42
+ boundary?: string;
43
+ }
44
+ /**
45
+ * The live half of an invocation, for in-process consumers. Not part of the
46
+ * record: `args` and `result` are application data (name/PII policy belongs
47
+ * to the consumer), `error` is the value AS THROWN — before the HTTP
48
+ * handler's production sanitization replaces it on the wire — and `event`
49
+ * is the request event the call ran under (the per-call derived event for
50
+ * direct calls).
51
+ */
52
+ export interface InvocationLive {
53
+ event: RequestEvent;
54
+ /** HTTP dispatch only; absent for direct calls. */
55
+ request?: Request;
56
+ args: unknown[];
57
+ /** The settled value, when `outcome` is `"ok"`. */
58
+ result?: unknown;
59
+ /** The thrown value, when `outcome` is `"error"`. */
60
+ error?: unknown;
61
+ }
62
+ export type InvocationListener = (event: InvocationEvent, live: InvocationLive) => void;
63
+ /**
64
+ * One server-function call made from the browser — the fetch and its
65
+ * decode, as the caller awaited it — delivered on
66
+ * `OBSERVE.records.subscribe("call", …)` once it settled. The client twin
67
+ * of the server's `"invocation"` record: the two join by `id` (this is the
68
+ * call; that is the execution it caused), and the difference between their
69
+ * durations is the wire. A call an integration answered locally (a
70
+ * handler's `intercept`, at t = 0) made no request and emits nothing.
71
+ */
72
+ export interface CallEvent {
73
+ /** The function id — the same `id` the server's `"invocation"` record carries. */
74
+ id: string;
75
+ /** `performance.now()` when the call was made. */
76
+ at: number;
77
+ /**
78
+ * Call → settle, in milliseconds: the request built and sent, the
79
+ * response received and decoded (or claimed by the configured
80
+ * `responseHandler`) — the whole await the caller saw. A streaming
81
+ * result settles at handoff — see `deferred`.
82
+ */
83
+ durationMs: number;
84
+ /** `GET` for a GET-encoded read (`GET(fn)`), `POST` otherwise. */
85
+ method: "GET" | "POST";
86
+ outcome: "ok" | "error";
87
+ /**
88
+ * The response's HTTP status, once one arrived. Absent when the call
89
+ * failed before a response (the fetch itself rejected).
90
+ */
91
+ status?: number;
92
+ /**
93
+ * What the call ran for, when the attribution engine
94
+ * (`solid-js/attribution`) is enabled and knows: the interaction whose
95
+ * handler made it (`kind: "interaction"`), the navigation whose data
96
+ * needed it (`kind: "navigation"`, its `interaction` the click), the
97
+ * effect or action step, the async landing whose recompute called again —
98
+ * the engine's own origin object, so it IS `InteractionEvent.origin` /
99
+ * `NavigationEvent.origin` / `HoldEvent.origin` by identity: an observer
100
+ * puts the call under the interaction's record without a time join. Read
101
+ * at dispatch, so a call made after an `await` in a handler stamps
102
+ * nothing (the same escape a write there has). Absent without an engine.
103
+ */
104
+ origin?: ChangeOrigin;
105
+ /**
106
+ * The settled value is a body the caller drives — an async iterable
107
+ * (a `live()` source, a generator result) — so `durationMs` covers the
108
+ * call that produced it, not its consumption.
109
+ */
110
+ deferred?: true;
111
+ }
112
+ /**
113
+ * The live half of a call, for in-process consumers. `response` is the
114
+ * transport's own object, not a clone: its status and headers are
115
+ * readable, its body is the decode's (already consumed, or being consumed
116
+ * by the caller for a streaming result). `error` is the value as thrown to
117
+ * the caller — a decoded server error, or the transport's own failure.
118
+ */
119
+ export interface CallLive {
120
+ args: unknown[];
121
+ response?: Response;
122
+ /** The settled value, when `outcome` is `"ok"`. */
123
+ result?: unknown;
124
+ /** The thrown value, when `outcome` is `"error"`. */
125
+ error?: unknown;
126
+ }
127
+ export type CallListener = (event: CallEvent, live: CallLive) => void;
128
+ interface FrameEventBase {
129
+ /**
130
+ * The frame id on the wire: the server function's id when the stream is a
131
+ * server-function response (the same `id` that call's `"invocation"` and
132
+ * `"call"` records carry), or what the producer named it; `""` for a bare
133
+ * `renderToFrameStream` with no `frame` option.
134
+ */
135
+ id: string;
136
+ /**
137
+ * The stream version: as the producer stamped it on the server; as the
138
+ * client restamped it on the client (the consumer owns versions — one
139
+ * per stream a boundary consumed — so this is the number the frame's
140
+ * stale-guard saw).
141
+ */
142
+ version: number;
143
+ /** `performance.now()` at the stream's `start` chunk — written, or read. */
144
+ at: number;
145
+ /**
146
+ * Start → `complete`, in milliseconds: the whole stream, fragments
147
+ * included. On the client this is the body's read and apply — the
148
+ * request that produced the response is the `"call"` record's time.
149
+ */
150
+ durationMs: number;
151
+ /**
152
+ * Start → the shell (`html`) chunk, in milliseconds: the time to first
153
+ * content. Absent when the stream carried no shell (the server's
154
+ * synchronous failure path).
155
+ */
156
+ shellMs?: number;
157
+ /** Chunks between `start` and `complete` (exclusive), all types. */
158
+ chunks: number;
159
+ /** `fragment` chunks: `<Loading>` content that settled after the shell. */
160
+ fragments: number;
161
+ /** `slot` chunks: render-prop invocations the client fills. */
162
+ slots: number;
163
+ /**
164
+ * Nested server-content regions (a server JSX slot argument): `html`
165
+ * chunks addressed to a child frame id rather than the stream's own.
166
+ */
167
+ regions: number;
168
+ /** `error` chunks: fragments that failed (their fallback still revealed), plus a sync failure. */
169
+ errors: number;
170
+ }
171
+ /**
172
+ * The server half of a `"frame"` record: one frame stream produced — a
173
+ * server component rendered to the frame transport
174
+ * (`renderServerComponent` / `renderToFrameStream`), from its `start`
175
+ * chunk to its `complete` — delivered once it completed.
176
+ */
177
+ export interface FrameProducedEvent extends FrameEventBase {
178
+ side: "server";
179
+ /**
180
+ * `complete` — the render ran to the end (fragment failures, if any, are
181
+ * in `errors`); `error` — the render threw synchronously, the stream
182
+ * carried the failure as its only content and completed.
183
+ */
184
+ outcome: "complete" | "error";
185
+ }
186
+ /**
187
+ * The client half of a `"frame"` record: one frame stream applied — a
188
+ * frame-stream response read chunk by chunk into the frame host
189
+ * (`applyFrameResponse`), from its `start` to its `complete` — delivered
190
+ * once the stream ended. A single-flight response carries one stream per
191
+ * frame it refreshed; each is its own record, as on the server.
192
+ */
193
+ export interface FrameAppliedEvent extends FrameEventBase {
194
+ side: "client";
195
+ /**
196
+ * The local id the chunks were applied under, when the consumer remapped
197
+ * the producer's root id onto its own boundary (`applyFrameResponse`'s
198
+ * `as` — the call's address, for the server-component transport).
199
+ * Absent when applied under the wire id.
200
+ */
201
+ address?: string;
202
+ /**
203
+ * `complete` — the `complete` chunk arrived; `truncated` — the body ended
204
+ * before it (the connection dropped, the producer abandoned the stream);
205
+ * `error` — the read failed (a malformed chunk, a body error), with the
206
+ * failure in `live.error`.
207
+ */
208
+ outcome: "complete" | "truncated" | "error";
209
+ }
210
+ /**
211
+ * One frame stream, from whichever end observed it — delivered on
212
+ * `OBSERVE.records.subscribe("frame", …)`; `side` says which. The two
213
+ * halves share their shape (the same census, the same timings measured
214
+ * where each stands), so a consumer joins them by `id` and `version` and
215
+ * the difference is the wire.
216
+ */
217
+ export type FrameEvent = FrameProducedEvent | FrameAppliedEvent;
218
+ /** The live half of a frame record. */
219
+ export interface FrameLive {
220
+ /** The value thrown: the server's sync failure, or the client's read failure. */
221
+ error?: unknown;
222
+ /** Client only: the response the stream was read from. */
223
+ response?: Response;
224
+ }
225
+ export type FrameListener = (event: FrameEvent, live: FrameLive) => void;
226
+ declare module "solid-js" {
227
+ interface HostRecordTypes {
228
+ /** Server-function executions, on the server — see `InvocationEvent`. */
229
+ invocation: {
230
+ event: InvocationEvent;
231
+ live: InvocationLive;
232
+ };
233
+ /** Server-function calls, from the client — see `CallEvent`. */
234
+ call: {
235
+ event: CallEvent;
236
+ live: CallLive;
237
+ };
238
+ /** Frame streams, produced or applied — see `FrameEvent`. */
239
+ frame: {
240
+ event: FrameEvent;
241
+ live: FrameLive;
242
+ };
243
+ }
244
+ }
245
+ export declare function settledPromise(value: unknown): Promise<unknown> | undefined;
246
+ export declare function isDeferredBody(value: unknown): boolean;
247
+ /**
248
+ * The census one frame stream's chunks add up to, kept by either half: one
249
+ * chunk of `type`, addressed to the stream's own frame (`own`) or to a
250
+ * nested region's.
251
+ */
252
+ export declare function frameCensus(event: FrameEventBase, type: string, own: boolean): void;
253
+ /** What the client runtime hands a call observation as the call proceeds. */
254
+ export interface CallObservation {
255
+ /** The response arrived (before decode); its status goes on the record. */
256
+ response(response: Response): void;
257
+ /** The call settled as the caller sees it: the value returned, or the error thrown. */
258
+ settle(outcome: "ok" | "error", value: unknown): void;
259
+ }
260
+ /**
261
+ * Opens the observation of one server-function call from the client, as
262
+ * the request is about to be built; the runtime reports the response when
263
+ * it arrives and the settle when the caller gets its answer. `undefined`
264
+ * with no listener or outside observe builds — the runtime then does
265
+ * nothing extra, not even read the clock.
266
+ */
267
+ export declare function observeCall(id: string, method: "GET" | "POST", args: unknown[]): CallObservation | undefined;
268
+ /** What the client's stream reader hands a frame observation. */
269
+ export interface FrameApplyObservation {
270
+ /**
271
+ * Every chunk read, after the consumer's remapping (`as`, `version`) —
272
+ * `wireId` is the id the chunk carried before it.
273
+ */
274
+ chunk(chunk: {
275
+ type: string;
276
+ id: string;
277
+ version: number;
278
+ }, wireId: string): void;
279
+ /**
280
+ * The apply ended — cleanly, or with the failure it threw (a read that
281
+ * failed, a chunk that would not parse, a host that rejected a chunk).
282
+ */
283
+ end(error?: unknown): void;
284
+ }
285
+ /**
286
+ * Opens the observation of one frame-stream response on the client: every
287
+ * `start` chunk opens a stream record (a single-flight response carries
288
+ * several, in sequence), every chunk until its `complete` is counted to
289
+ * it, and the record is delivered at `complete` — or at the body's end as
290
+ * `truncated`, or at a read failure as `error`. `undefined` with no
291
+ * listener or outside observe builds.
292
+ */
293
+ export declare function observeFrameApply(response: Response): FrameApplyObservation | undefined;
294
+ export {};
@@ -46,8 +46,26 @@ export declare function isSafeError(value: unknown): value is Error;
46
46
  * (prefixes, exact names, namespaces) is the integration's business.
47
47
  */
48
48
  export declare const REVALIDATE_HEADER = "X-Revalidate";
49
+ /**
50
+ * The reserved `revalidate` key meaning every entry, in every cache: the
51
+ * host-independent spelling of "all" (as `Clear-Site-Data: "*"` spells it),
52
+ * for authors who mean it rather than a host's default. Stands alone —
53
+ * naming it beside other keys is refused, since "everything and also
54
+ * these" is a mistake, not a scope.
55
+ */
56
+ export declare const REVALIDATE_ALL = "*";
49
57
  /** `ResponseInit` accepted by the response helpers, plus `revalidate`. */
50
58
  export interface ResponseHelperInit extends ResponseInit {
59
+ /**
60
+ * The cache keys the mutation invalidated, sent as the `X-Revalidate`
61
+ * header for the client's integrations to apply. Three declarations, three
62
+ * scopes: omitted sends no header — the host's default (Solid Router
63
+ * revalidates everything after an action; a router without that
64
+ * convention reloads only what it owns); an empty list sends an empty
65
+ * header — nothing, explicitly; `REVALIDATE_ALL` (`"*"`) — every entry,
66
+ * whatever the host's default. How named keys are matched (prefixes,
67
+ * namespaces) is each integration's business.
68
+ */
51
69
  revalidate?: string | string[];
52
70
  }
53
71
  /** @internal */
@@ -145,7 +145,54 @@ export interface JSONDataTable {
145
145
  * and deserialize halves, so the set lives on the decode side and the
146
146
  * encode module composes over it.
147
147
  */
148
- export declare const DEFAULT_WEB_PLUGINS: any; /**
148
+ export declare const DEFAULT_WEB_PLUGINS: readonly ({
149
+ tag: string;
150
+ test(value: any): boolean;
151
+ parse: {
152
+ sync(): never;
153
+ async(value: any, ctx: any): Promise<{
154
+ a: number;
155
+ i: any;
156
+ }>;
157
+ stream: (value: any, ctx: any) => {
158
+ a: number;
159
+ i: any;
160
+ };
161
+ };
162
+ serialize(node: any, ctx: any): string;
163
+ deserialize(node: any, ctx: any): any;
164
+ } | import("seroval").Plugin<AbortSignal, {
165
+ reason?: import("seroval").SerovalNode;
166
+ controller?: import("seroval").SerovalNode;
167
+ factory?: import("seroval").SerovalNode;
168
+ }> | import("seroval").Plugin<CustomEvent<any>, {
169
+ type: import("seroval").SerovalNode;
170
+ options: import("seroval").SerovalNode;
171
+ }> | import("seroval").Plugin<DOMException, {
172
+ name: import("seroval").SerovalNode;
173
+ message: import("seroval").SerovalNode;
174
+ }> | import("seroval").Plugin<Event, {
175
+ type: import("seroval").SerovalNode;
176
+ options: import("seroval").SerovalNode;
177
+ }> | import("seroval").Plugin<FormData, {
178
+ factory: import("seroval").SerovalNode;
179
+ entries: import("seroval").SerovalNode;
180
+ }> | import("seroval").Plugin<Headers, {
181
+ value: import("seroval").SerovalNode;
182
+ }> | import("seroval").Plugin<ReadableStream<any>, {
183
+ factory: import("seroval").SerovalNode;
184
+ stream: import("seroval").SerovalNode;
185
+ }> | import("seroval").Plugin<Request, {
186
+ url: import("seroval").SerovalNode;
187
+ options: import("seroval").SerovalNode;
188
+ }> | import("seroval").Plugin<Response, {
189
+ body: import("seroval").SerovalNode;
190
+ options: import("seroval").SerovalNode;
191
+ }> | import("seroval").Plugin<URLSearchParams, {
192
+ value: import("seroval").SerovalNode;
193
+ }> | import("seroval").Plugin<URL, {
194
+ value: import("seroval").SerovalNode;
195
+ }>)[]; /**
149
196
  * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
150
197
  * first so they can shadow a default for values both would match. Returns a
151
198
  * fresh array; the defaults are never mutated. Useful when handing a full
@@ -156,7 +203,7 @@ export declare const DEFAULT_WEB_PLUGINS: any; /**
156
203
  export declare function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
157
204
  export declare function resolveCodecOptions({ plugins, disabledFeatures, depthLimit, serializeErrorStacks }?: JSONCodecOptions): {
158
205
  plugins: SerializerPlugin<any, any>[];
159
- disabledFeatures: any;
206
+ disabledFeatures: number;
160
207
  depthLimit: number;
161
208
  serializeErrorStacks: boolean;
162
209
  }; /**
@@ -1,5 +1,5 @@
1
1
  import type { ServerFunction, ServerFunctionMetadata } from "./shared.js";
2
- export { ChunkReader, ERROR_HEADER, FLASH_COOKIE, INSTANCE_HEADER, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, createChunk, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, deserializeStream, encodeErrorHeaderValue, frameAddress, getFlightDataConsumer, getFlightDataSourceIds, getServerFunctionMetadata, getServerFunctionsCodec, hasFlashCookie, invoke, isServerFunction, serializeString, subscribeFlightData, withMeta } from "./shared.js";
2
+ export { ChunkReader, ERROR_HEADER, FLASH_COOKIE, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, createChunk, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, deserializeStream, encodeErrorHeaderValue, frameAddress, getFlightDataConsumer, getFlightDataSourceIds, getServerFunctionMetadata, getServerFunctionsCodec, hasFlashCookie, invoke, isServerFunction, serializeString, subscribeFlightData, withMeta } from "./shared.js";
3
3
  export { REVALIDATE_HEADER } from "../response.js";
4
4
  import { JSONCodecOptions } from "../serializer-decode.js";
5
5
  export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.js";
@@ -44,7 +44,7 @@ export interface ServerFunctionsClientConfig {
44
44
  * Sends every server-function request — retries, telemetry, a test
45
45
  * double, or an app's own route. Always called as `(address, init)`, the
46
46
  * address relative to the document as the global one receives it, so
47
- * `parseServerFunctionUrl` reads the id back out for telemetry. `null`
47
+ * `parseServerFunctionActionUrl` reads the id back out for telemetry. `null`
48
48
  * restores the global.
49
49
  *
50
50
  * ```ts
@@ -116,23 +116,6 @@ export interface ServerFunctionsClientConfig {
116
116
  */
117
117
  serializeArgs?(args: unknown[]): string | Promise<string>;
118
118
  }
119
- export interface ServerFunctionRequestCall {
120
- type: "request";
121
- id: string;
122
- instance: string;
123
- request: Request;
124
- meta: ServerFunctionMetadata | undefined;
125
- time: number;
126
- }
127
- export interface ServerFunctionResponseCall {
128
- type: "response";
129
- id: string;
130
- instance: string;
131
- response: Response;
132
- meta: ServerFunctionMetadata | undefined;
133
- time: number;
134
- }
135
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
136
119
  /** Wire-state transitions a live call's iterable can report. */
137
120
  export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
138
121
  /**
@@ -154,9 +137,36 @@ export type LiveSource<R> = R & {
154
137
  export interface ServerFunctionInvocation {
155
138
  id: string;
156
139
  }
157
- export declare function observeServerFunctionCalls(observer: (call: ServerFunctionCall) => void): () => void;
158
- export declare function serverFunctionUrl(id: string, boundArgs?: readonly unknown[]): string;
159
- export declare function parseServerFunctionUrl(url: string): string | null;
140
+ /**
141
+ * The url a `GET()` reference's own call requests — the address to preload
142
+ * (`<link rel="preload" as="fetch">`), prefetch, warm in a service worker, or
143
+ * fetch by hand — built the way the transport builds it, so a fetch of it IS
144
+ * the call and matches the reference's later call in every cache that keys
145
+ * on the url. Arguments ride the query as they do on the wire (`?args=`,
146
+ * JSON), and must be JSON-safe here: the codec's encoding is asynchronous,
147
+ * and a url rendered as a value cannot wait for it. Resolved against the
148
+ * configured endpoint. The answer at this url is the transport's (codec
149
+ * shape) — read one by hand with `decodeResponse`.
150
+ *
151
+ * Defined for declared reads only. A reference on the default transport
152
+ * POSTs, and a POST is not described by its url; this throws with a pointer
153
+ * (declare `GET(fn)`, or start the call with `invoke(fn, { priority: "low"
154
+ * }, ...args)`). Also throws when the url would be long enough for the call
155
+ * to fall back to POST — a url you hold is always one the transport would
156
+ * request.
157
+ *
158
+ * ```tsx
159
+ * const getUser = GET(async (id: string) => { "use server"; ... });
160
+ * <link rel="preload" as="fetch" crossorigin href={serverFunctionUrl(getUser, id)} />
161
+ * ```
162
+ *
163
+ * The form-post address is a different url — `fn.url`, or
164
+ * `serverFunctionActionUrl` for one with bound arguments. The server entry
165
+ * exports the same function so isomorphic imports resolve.
166
+ */
167
+ export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
168
+ export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
169
+ export declare function parseServerFunctionActionUrl(url: string): string | null;
160
170
  export declare function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
161
171
  export declare function createServerReference(id: string, name?: string, base?: string): ServerFunction;
162
172
  export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
@@ -1,9 +1,9 @@
1
- export { ERROR_HEADER, FLASH_COOKIE, INSTANCE_HEADER, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, encodeErrorHeaderValue, getServerFunctionMetadata, hasFlashCookie, invoke, isServerFunction, subscribeFlightData, withMeta } from "./shared.js";
1
+ export { ERROR_HEADER, FLASH_COOKIE, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, encodeErrorHeaderValue, getServerFunctionMetadata, hasFlashCookie, invoke, isServerFunction, subscribeFlightData, withMeta } from "./shared.js";
2
2
  export { decodeFlashCookie, encodeFlashCookie } from "./flash.js";
3
3
  import { ResponseEnvelope } from "../response.js";
4
4
  import { JSONCodecOptions } from "../serializer-decode.js";
5
- import { RequestEvent } from "../server.js";
6
- import type { ServerFunction, ServerFunctionMetadata } from "./shared.js";
5
+ import { RequestEvent, ServerErrorHook } from "../server.js";
6
+ import type { ServerFunction } from "./shared.js";
7
7
  export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.js";
8
8
  export type { FlashSubmission } from "./flash.js";
9
9
  /**
@@ -57,7 +57,9 @@ export interface ServerFunctionOutcome {
57
57
  /**
58
58
  * The outcome's `X-Revalidate` keys, split — the invalidation scope the
59
59
  * mutation declared. Undefined when the outcome carries none (integrations
60
- * typically collect everything for the target in that case).
60
+ * typically collect everything for the target in that case); `[""]` for
61
+ * an empty declaration (nothing); `["*"]` for `REVALIDATE_ALL`, delivered
62
+ * as declared so a collector can tell "everything" from named keys.
61
63
  */
62
64
  revalidateKeys: string[] | undefined;
63
65
  /**
@@ -182,7 +184,6 @@ export interface ServerFunctionsServerConfig {
182
184
  transformResult?(event: ServerFunctionEvent, result: unknown, context: {
183
185
  id: string;
184
186
  args: unknown[];
185
- instance: string | null;
186
187
  request: Request;
187
188
  thrown?: boolean;
188
189
  }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
@@ -201,7 +202,6 @@ export interface ServerFunctionsServerConfig {
201
202
  }, context: {
202
203
  id: string;
203
204
  args: unknown[];
204
- instance: string | null;
205
205
  request: Request;
206
206
  }): Response | undefined | Promise<Response | undefined>;
207
207
  /**
@@ -277,10 +277,24 @@ export interface ServerFunctionsServerConfig {
277
277
  * back to the one the Solid bundler plugin injects into the server build
278
278
  * (a fresh value per build), and with neither present the outcome is
279
279
  * simply not flashed — the form post still redirects cleanly, and dev
280
- * builds warn once. Any non-empty string works; rotating it (or
281
- * redeploying with the plugin's value) invalidates in-flight flashes,
282
- * which are 60-second one-shot cookies — the next render reads "no
283
- * flash".
280
+ * builds warn once.
281
+ *
282
+ * Use a HIGH-ENTROPY value, 32 bytes or more, and keep it out of source
283
+ * control:
284
+ *
285
+ * ```sh
286
+ * node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
287
+ * ```
288
+ *
289
+ * A captured cookie is an offline oracle for this value. Key derivation
290
+ * stretches it (PBKDF2-HMAC-SHA-256), which raises the price of a guess
291
+ * but does not make a guessable secret safe, and recovering it means
292
+ * reading every flash payload and forging new ones. A passphrase, an app
293
+ * name, or anything else a person would think up is not enough.
294
+ *
295
+ * Rotating it (or redeploying with the plugin's value) invalidates
296
+ * in-flight flashes. They are 60-second one-shot cookies, so the next
297
+ * render reads "no flash".
284
298
  */
285
299
  secret?: string;
286
300
  }
@@ -329,6 +343,15 @@ export interface HandleServerFunctionOptions {
329
343
  * Builds the request event a call runs under (default: bare
330
344
  * `{ request, locals: {} }`). Integrations supply their richer event
331
345
  * (cookies, response helpers, platform handles).
346
+ *
347
+ * `request` is a standards-shaped `Request` — url, method, headers,
348
+ * signal, readable body — and nothing more. Enforcing `bodySizeLimit`
349
+ * puts the runtime between the host's stream and the decoder, so the
350
+ * object handed here may be one the runtime rebuilt; host-specific
351
+ * fields on the inbound object (`request.cf`, srvx's `runtime`, `ip`,
352
+ * `waitUntil`) are not carried. The host has its own request in closure
353
+ * when it calls the handler: read platform handles there and put them on
354
+ * the event (`locals`) rather than through `request`.
332
355
  */
333
356
  createEvent?(request: Request): ServerFunctionEvent;
334
357
  /**
@@ -348,15 +371,25 @@ export interface HandleServerFunctionOptions {
348
371
  * `wrapInvocation`, not here.
349
372
  */
350
373
  wrapInvocation?: WrapInvocationHook;
374
+ /**
375
+ * This request's server error hook, ahead of `configureServerErrors`' (see
376
+ * `ServerErrorHook` in `@solidjs/web`): the function's throw
377
+ * (`handling: "thrown"`) and a failure escaping through its result graph
378
+ * (`"channel"`), once per error, before the wire policy applies. Entry-only
379
+ * like `wrapInvocation`: a direct call the body makes during a render
380
+ * reports through the ambient hook.
381
+ */
382
+ onError?: ServerErrorHook;
351
383
  /**
352
384
  * Observes or replaces the function's result before encoding — the
353
385
  * extension point for response metadata policies (headers, statuses,
354
386
  * substituted results). Runs for returned and thrown results alike
355
- * (`context.thrown` distinguishes); `context.instance` is null for no-JS
356
- * calls. The context carries the call's identity — the function `id` and
357
- * the parsed `args` the implementation was invoked with — matching the
358
- * direct-call mirror (`transformDirectResult`), so a policy keying state
359
- * by the call works over either dispatch path. Return the result
387
+ * (`context.thrown` distinguishes). The context carries the call's
388
+ * identity — the function `id` and the parsed `args` the implementation
389
+ * was invoked with — matching the direct-call mirror
390
+ * (`transformDirectResult`), so a policy keying state by the call works
391
+ * over either dispatch path; `context.request` tells a scripted call (the
392
+ * `/data/` address) from a bare-address one. Return the result
360
393
  * unchanged to pass through, or a `ResponseEnvelope` (exposed through
361
394
  * the core entry) to send HTTP metadata plus a structured payload. Runs
362
395
  * before `collectFlightData`, so the flight hook sees the transformed
@@ -366,7 +399,6 @@ export interface HandleServerFunctionOptions {
366
399
  transformResult?(event: ServerFunctionEvent, result: unknown, context: {
367
400
  id: string;
368
401
  args: unknown[];
369
- instance: string | null;
370
402
  request: Request;
371
403
  thrown?: boolean;
372
404
  }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
@@ -386,18 +418,17 @@ export interface HandleServerFunctionOptions {
386
418
  }, context: {
387
419
  id: string;
388
420
  args: unknown[];
389
- instance: string | null;
390
421
  request: Request;
391
422
  }): Response | undefined | Promise<Response | undefined>;
392
423
  /**
393
- * Builds the response for calls made without the client runtime (no
394
- * instance header — no-JS form posts, direct HTTP). Receives the
424
+ * Builds the response for calls made without the client runtime (at
425
+ * the bare address — no-JS form posts, direct HTTP). Receives the
395
426
  * (transformed) result, the request, and the decoded arguments; `thrown`
396
427
  * is set when the result was thrown rather than returned.
397
428
  *
398
429
  * Overrides the configured hook, which in turn overrides the built-in
399
430
  * `createNoJSHandler()` applied to browser form posts. Other
400
- * no-instance callers get the normal serialized response.
431
+ * bare-address callers get the normal serialized response.
401
432
  */
402
433
  handleNoJS?(result: unknown, request: Request, args: unknown[], thrown?: boolean): Response | Promise<Response>;
403
434
  /**
@@ -418,23 +449,6 @@ export interface HandleServerFunctionOptions {
418
449
  */
419
450
  maxArguments?: number;
420
451
  }
421
- export interface ServerFunctionRequestCall {
422
- type: "request";
423
- id: string;
424
- instance: string;
425
- request: Request;
426
- meta: ServerFunctionMetadata | undefined;
427
- time: number;
428
- }
429
- export interface ServerFunctionResponseCall {
430
- type: "response";
431
- id: string;
432
- instance: string;
433
- response: Response;
434
- meta: ServerFunctionMetadata | undefined;
435
- time: number;
436
- }
437
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
438
452
  export declare function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
439
453
  export declare function registerFlightDataSource(source: string, hook: CollectFlightDataHook): () => void;
440
454
  export declare function registerServerFunction<T extends any[], R>(id: string, callback: (...args: T) => R): (...args: T) => R;
@@ -471,9 +485,9 @@ export declare function serializeResponseStream(value: any, codecOptions: any, s
471
485
  export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
472
486
  export declare function setServerFunctionsDev(dev: boolean): void;
473
487
  export declare function sanitizeServerError(value: unknown): unknown;
474
- export declare function observeServerFunctionCalls(observer: (call: ServerFunctionCall) => void): () => void;
475
- export declare function serverFunctionUrl(id: string, boundArgs?: readonly unknown[]): string;
476
- export declare function parseServerFunctionUrl(url: string): string | null;
488
+ export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
489
+ export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
490
+ export declare function parseServerFunctionActionUrl(url: string): string | null;
477
491
  /**
478
492
  * Web-standard HTTP handler for server function calls: resolves the
479
493
  * function id from the request, enforces the method allowlist (POST always
@@ -534,7 +548,7 @@ export declare function parseServerFunctionUrl(url: string): string | null;
534
548
  *
535
549
  * @example
536
550
  * ```ts
537
- * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
551
+ * import { handleServerFunctionRequest } from "@solidjs/web/server-functions/server";
538
552
  * import "virtual:solid-server-function-manifest";
539
553
  *
540
554
  * // in the server's request handling: