@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,681 +0,0 @@
1
- import { ResponseEnvelope } from "../response.cjs";
2
- import { JSONCodecOptions } from "../serializer-decode.cjs";
3
- import { RequestEvent } from "../server.cjs";
4
-
5
- export {
6
- ERROR_HEADER,
7
- FLASH_COOKIE,
8
- FUNCTION_HEADER,
9
- INSTANCE_HEADER,
10
- SINGLE_FLIGHT_HEADER,
11
- clearFlashCookie,
12
- decodeErrorHeaderValue,
13
- decodeResponse,
14
- decodeResponsePayload,
15
- encodeErrorHeaderValue,
16
- getServerFunctionMetadata,
17
- hasFlashCookie,
18
- isServerFunction,
19
- subscribeFlightData,
20
- withMeta
21
- } from "./shared.cjs";
22
- export type {
23
- FlightDataConsumer,
24
- FlightDataContext,
25
- ServerFunction,
26
- ServerFunctionMetadata,
27
- SingleFlightPayload
28
- } from "./shared.cjs";
29
- export { decodeFlashCookie, encodeFlashCookie } from "./flash.cjs";
30
- export type { FlashSubmission } from "./flash.cjs";
31
- import { ServerFunction, ServerFunctionMetadata } from "./shared.cjs";
32
-
33
- /**
34
- * The request event a server function call runs under: the base
35
- * `RequestEvent` (request + locals) with `serverOnly` added, set when the
36
- * call is an in-process SSR invocation whose result never serializes to a
37
- * client.
38
- */
39
- export interface ServerFunctionEvent extends RequestEvent {
40
- serverOnly?: boolean;
41
- }
42
-
43
- /**
44
- * What a server function call resolved to, as seen by the single-flight
45
- * hook — enough context for any data-production strategy without core
46
- * assuming one.
47
- */
48
- export interface ServerFunctionOutcome {
49
- /** The build-stable id of the function that ran. */
50
- id: string;
51
- /**
52
- * The value the caller will receive: the raw return for plain results,
53
- * the unwrapped `value` for `ResponseEnvelope`s, `null` for body-less
54
- * control-flow `Response`s (redirect/reload).
55
- */
56
- value: unknown;
57
- /**
58
- * The `Response` carrying the result's HTTP metadata, when there is one
59
- * (from a returned/thrown `Response` or a `ResponseEnvelope`). Read
60
- * `Location` here for redirect-with-data — the data should describe the
61
- * destination route — and `X-Revalidate` for the invalidated keys.
62
- * Undefined for plain values.
63
- */
64
- response: Response | undefined;
65
- /**
66
- * The original HTTP request, untouched: headers the client integration
67
- * sent (referrer, custom route context) ride here for the hook to read —
68
- * core assigns them no meaning.
69
- */
70
- request: Request;
71
- /** Whether the result was thrown rather than returned. */
72
- thrown: boolean;
73
- /**
74
- * The URL the client will show after the mutation — the redirect
75
- * `Location` when the outcome carries one (resolved against the request
76
- * URL, as a browser would), the referring page otherwise. Undefined
77
- * without a usable referer (a non-browser caller has no page to produce
78
- * data for) and for redirects leaving the app's origin: produce no data
79
- * when this is undefined.
80
- */
81
- targetUrl: string | undefined;
82
- /**
83
- * The outcome's `X-Revalidate` keys, split — the invalidation scope the
84
- * mutation declared. Undefined when the outcome carries none (integrations
85
- * typically collect everything for the target in that case).
86
- */
87
- revalidateKeys: string[] | undefined;
88
- /**
89
- * The request headers with the mutation's cookie effects applied: the
90
- * event response's `Set-Cookie`s (set during the call), then the
91
- * outcome's own (e.g. `redirect(to, { headers })`), later winning on
92
- * conflict, deletions honored. Build the data-collection request from
93
- * these so re-run reads observe post-mutation cookie state.
94
- */
95
- foldedHeaders: Headers;
96
- }
97
-
98
- /**
99
- * The single-flight server hook: given the request event and the function's
100
- * outcome, optionally produce a data payload (possibly async) to fold into
101
- * the response alongside the return value. Data production is a black box
102
- * to the protocol — render data-only, run route preloads, query a cache,
103
- * whatever the integration chooses; the payload just has to be
104
- * codec-serializable. Return undefined to send the response unchanged
105
- * (byte-identical to a call without the hook).
106
- *
107
- * Runs after `transformResult`, only for scripted calls that sent
108
- * `SINGLE_FLIGHT_HEADER` on the request, on returned results and thrown
109
- * `Response`/`ResponseEnvelope` control-flow signals alike (plain thrown
110
- * errors never collect, and neither do raw body-carrying `Response` values
111
- * — those are the caller's verbatim payload). The handler owns the
112
- * enveloping: contributed data ships as `{ value, data }` under the
113
- * single-flight response header. The generic halves of collection arrive
114
- * pre-digested on the outcome (`targetUrl`, `revalidateKeys`,
115
- * `foldedHeaders`); the hook supplies only the data strategy.
116
- */
117
- export type CollectFlightDataHook = (
118
- event: ServerFunctionEvent,
119
- outcome: ServerFunctionOutcome
120
- ) => unknown | Promise<unknown>;
121
-
122
- /**
123
- * Wraps a server function execution — the per-invocation seam for
124
- * framework policies (per-function middleware, auth, logging, error
125
- * mapping). Called inside the call's event scope with the invocation
126
- * identity already established: `getServerFunctionInvocation()` answers
127
- * before, during and after `run()`. Must return (or resolve to) `run()`'s
128
- * result — replacing it replaces the function's result; throwing routes
129
- * through the handler's normal error encoding.
130
- *
131
- * The context carries the call's identity (`id`, parsed `args`), its
132
- * `event`, and how it arrived: `direct` is `true` for in-process SSR calls
133
- * (where `request` is absent) and `false` for HTTP dispatch. On the direct
134
- * path the wrapper must stay transparent for synchronous functions —
135
- * return `run()`'s value, not an unconditional promise, unless it needs to
136
- * be async.
137
- */
138
- export type WrapInvocationHook = (
139
- run: () => unknown,
140
- context: {
141
- id: string;
142
- args: unknown[];
143
- event: ServerFunctionEvent;
144
- request?: Request;
145
- direct: boolean;
146
- }
147
- ) => unknown;
148
-
149
- /**
150
- * Request headers with `setCookies` folded into the `Cookie` header, as the
151
- * browser would have applied them before its next request. Later entries
152
- * win on conflict, and deletions are honored (`Max-Age` at or below zero,
153
- * `Expires` in the past). The input headers are not modified.
154
- *
155
- * For work re-run on the server after a mutation — a
156
- * `CollectFlightDataHook` gathering fresh data, typically. That pass starts
157
- * from the request that triggered the mutation, whose cookies are
158
- * pre-mutation by definition, so a read depending on a session the mutation
159
- * just established would otherwise see the old state. Which responses
160
- * contribute their `Set-Cookie`s, and in what order, is the caller's
161
- * decision.
162
- *
163
- * @example
164
- * ```ts
165
- * const headers = foldSetCookies(event.request.headers, [
166
- * ...(event.response?.headers?.getSetCookie() ?? []),
167
- * ...(outcome.response?.headers?.getSetCookie() ?? [])
168
- * ]);
169
- * ```
170
- */
171
- export function foldSetCookies(headers: Headers, setCookies: readonly string[]): Headers;
172
-
173
- /** Options for `createNoJSHandler`. */
174
- export interface NoJSHandlerOptions {
175
- /** The app's mount path, for resolving a relative redirect `Location`. */
176
- base?: string;
177
- }
178
-
179
- /**
180
- * Builds the `handleNoJS` implementation for the no-JS form convention: a
181
- * form posted without the client runtime has no way to receive a value, so
182
- * the call redirects back to the referring page (or to the result's own
183
- * `Location`, resolved against `base`) with the outcome riding a one-shot
184
- * flash cookie. `303 See Other` turns the POST into a GET unless the result
185
- * names a redirect status of its own. A result that is already a `Response`
186
- * carries its meaning in its metadata and is not flashed.
187
- *
188
- * The render that follows reads the cookie with `decodeFlashCookie` and
189
- * surfaces the outcome however it likes — that half is the integration's.
190
- *
191
- * The handler applies to every call it receives. `handleServerFunctionRequest`
192
- * already uses it for browser form posts, so wire it explicitly only to set
193
- * a `base`, or to extend the convention to direct HTTP calls by registering
194
- * it through `configureServerFunctionsServer`.
195
- */
196
- export function createNoJSHandler(
197
- options?: NoJSHandlerOptions
198
- ): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response;
199
-
200
- export type ServerFunctionOriginMatcher =
201
- | string
202
- | readonly string[]
203
- | ((origin: string, request: Request) => boolean | Promise<boolean>);
204
-
205
- /** Same-origin validation options for server function requests. */
206
- export interface ServerFunctionCSRFOptions {
207
- /**
208
- * Expected public origin. Defaults to the incoming request URL's origin.
209
- * A function can validate origins dynamically for multi-tenant hosts.
210
- */
211
- origin?: ServerFunctionOriginMatcher;
212
- /**
213
- * Allows requests without `Sec-Fetch-Site`, `Origin`, or `Referer`.
214
- * Cross-origin metadata is still rejected.
215
- * @default false
216
- */
217
- allowRequestsWithoutOriginCheck?: boolean;
218
- }
219
-
220
- /** Options for `configureServerFunctionsServer`. */
221
- export interface ServerFunctionsServerConfig {
222
- /**
223
- * Establishes the request-event scope for a call — the function passed
224
- * runs with `event` visible to `getRequestEvent()`. Wire it to
225
- * `provideRequestEvent` from `@solidjs/web/storage` (or the framework's
226
- * equivalent). When omitted, falls back to the AsyncLocalStorage instance
227
- * an established request scope parks on the global.
228
- */
229
- provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
230
- /**
231
- * Wraps every server function execution — HTTP dispatch and direct SSR
232
- * calls alike — with the invocation identity already established (see
233
- * `WrapInvocationHook`). The per-invocation seam for framework policies:
234
- * per-function middleware, auth, logging, error mapping. A per-request
235
- * option overrides it for HTTP dispatch.
236
- */
237
- wrapInvocation?: WrapInvocationHook;
238
- /**
239
- * The single-flight hook: produces the data payload folded into
240
- * responses of calls that opted in (see `CollectFlightDataHook`).
241
- * Registered once by the integration that owns data production (a
242
- * router); per-handler `collectFlightData` options override it.
243
- */
244
- collectFlightData?: CollectFlightDataHook;
245
- /**
246
- * Server-wide default for the handler's `transformResult` (same contract
247
- * — see `HandleServerFunctionRequestOptions`); a per-request option
248
- * overrides it. Registering it here makes result policies (e.g. frames'
249
- * `frameTransformResult`) work through generic dispatchers that call
250
- * `handleServerFunctionRequest(request)` with no options.
251
- */
252
- transformResult?(
253
- event: ServerFunctionEvent,
254
- result: unknown,
255
- context: {
256
- id: string;
257
- args: unknown[];
258
- instance: string | null;
259
- request: Request;
260
- thrown?: boolean;
261
- }
262
- ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
263
- /**
264
- * `transformResult`'s counterpart for the single-flight fold: when a
265
- * call's flight payload needs a body only a policy knows how to build
266
- * (frames' `frameTransformFlightResult` — an invalidated entry is
267
- * markup), this gets first refusal on the `{ value, data }` outcome.
268
- * Return a `Response` to carry the outcome (call headers and cookies are
269
- * copied onto it), or `undefined` to decline and keep the plain
270
- * serialized envelope. A per-request option overrides it.
271
- */
272
- transformFlightResult?(
273
- event: ServerFunctionEvent,
274
- outcome: { value: unknown; data: unknown },
275
- context: { id: string; args: unknown[]; instance: string | null; request: Request }
276
- ): Response | undefined | Promise<Response | undefined>;
277
- /**
278
- * The in-process mirror of `transformResult` for direct (same-server)
279
- * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
280
- */
281
- transformDirectResult?(
282
- value: unknown,
283
- options: { id: string; args: unknown[]; event: ServerFunctionEvent }
284
- ): unknown;
285
- /**
286
- * Server-wide response builder for calls made without the client runtime
287
- * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
288
- * per-request option overrides it. Set it to `createNoJSHandler({ base })`
289
- * to apply the convention to every non-scripted call rather than only to
290
- * browser form posts, to a handler of your own to replace it, or to
291
- * `null` to disable the built-in convention and answer form posts with
292
- * the plain serialized response.
293
- */
294
- handleNoJS?:
295
- | ((
296
- result: unknown,
297
- request: Request,
298
- args: unknown[],
299
- thrown?: boolean
300
- ) => Response | Promise<Response>)
301
- | null;
302
- /**
303
- * Endpoint the HTTP handler is mounted on, used for the `url` of SSR'd
304
- * references (e.g. form actions) — must match the client configuration.
305
- * Prefix it when the app serves from a base path (e.g.
306
- * `` `${BASE_URL}_server` ``).
307
- * @default "/_server"
308
- */
309
- endpoint?: string;
310
- /**
311
- * Same-origin protection for HTTP server function calls. Enabled by
312
- * default. Set to `false` only when another trusted layer protects the
313
- * endpoint.
314
- */
315
- csrf?: boolean | ServerFunctionCSRFOptions;
316
- /**
317
- * Codec options (extra plugins etc.) for decoding arguments and encoding
318
- * results — must match the client's. Stored in the shared layer, so
319
- * `decodeResponse` sees them too.
320
- */
321
- codec?: JSONCodecOptions;
322
- }
323
-
324
- /**
325
- * Configures the server runtime. Call once at server startup, before
326
- * handling requests. Only needed when deviating from the defaults (custom
327
- * endpoint, codec plugins, an explicit event provider, or a single-flight
328
- * hook).
329
- */
330
- export function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
331
-
332
- /**
333
- * A registered server function: its build-stable id paired with the
334
- * original implementation. Returned by `registerServerReference` and
335
- * consumed by the server-side `createServerReference`.
336
- *
337
- * Compiler ABI shape; hand-written code rarely constructs these.
338
- * @internal
339
- */
340
- export interface ServerFunctionReference<T extends any[] = any[], R = any> {
341
- id: string;
342
- fn: (...args: T) => R;
343
- /**
344
- * The function's source name, emitted by development builds only —
345
- * `createServerReference` seeds the metadata channel with it.
346
- * @internal
347
- */
348
- name?: string;
349
- }
350
-
351
- /**
352
- * Adds a function to the dispatch registry under an id and returns it
353
- * unchanged. The low-level registry write for integrations registering
354
- * functions outside the compiler (e.g. a router registering its own
355
- * endpoints); compiled output goes through `registerServerReference`
356
- * instead. Ids must be stable across the client and server builds.
357
- */
358
- export function registerServerFunction<T extends any[], R>(
359
- id: string,
360
- callback: (...args: T) => R
361
- ): (...args: T) => R;
362
-
363
- /**
364
- * Looks up a registered server function by id; throws for unknown ids.
365
- * The HTTP handler uses this for dispatch — integrations building custom
366
- * dispatch (or introspection) can too.
367
- */
368
- export function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
369
-
370
- /**
371
- * Compiler ABI — emitted by compiled `"use server"` server output for
372
- * every server function: registers `fn` for HTTP dispatch under its
373
- * build-stable id and returns the reference the server-side
374
- * `createServerReference` consumes. Development builds pass the function's
375
- * source name as the trailing argument (dev-only metadata; never emitted in
376
- * production). Not meant for hand-written code.
377
- * @internal
378
- */
379
- export function registerServerReference<T extends any[], R>(
380
- id: string,
381
- fn: (...args: T) => R,
382
- name?: string
383
- ): ServerFunctionReference<T, R>;
384
-
385
- /**
386
- * Compiler ABI — emitted by compiled `"use server"` server output where
387
- * the function was referenced; produces the server-side callable. Calling
388
- * it during SSR runs the original function in-process (no HTTP), under a
389
- * request event derived from the current one — marked `serverOnly` and
390
- * carrying the function's meta. Not meant for hand-written code.
391
- * @internal
392
- */
393
- export function createServerReference<T extends any[], R>(
394
- reference: ServerFunctionReference<T, R>
395
- ): (...args: T) => R;
396
-
397
- /**
398
- * Declares a server function callable over HTTP GET. The server half is
399
- * identity-flavored — SSR calls stay in-process — but it brands the
400
- * declaration on the reference's metadata channel
401
- * (`getServerFunctionMetadata(fn)?.method === "GET"`) and records the
402
- * declared method for the function's id so `handleServerFunctionRequest`
403
- * honors it: GET-declared functions accept GET requests in addition to the
404
- * default POST transport (declaring GET grants, it does not revoke);
405
- * functions that never declared GET answer GET requests with 405.
406
- *
407
- * Wrap the reference at its declaration; the compiler round-trips the call
408
- * in both builds:
409
- *
410
- * ```ts
411
- * export const getUser = GET(async (id: string) => {
412
- * "use server";
413
- * return db.users.find(id);
414
- * });
415
- * ```
416
- */
417
- export function GET<A extends readonly any[], R>(
418
- fn: (...args: A) => R
419
- ): ServerFunction<A, Awaited<R>>;
420
-
421
- /** Wire-state transitions a live call's iterable can report (client side).
422
- * `"closed"` carries the error when a definite rejection (4xx) ended the
423
- * call instead of the retry loop. */
424
- export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
425
-
426
- /**
427
- * Type-level mirror of the client's live answer shape so isomorphic code
428
- * assigning `onstatus` typechecks against either build's declarations. On
429
- * the server the hook is inert: in-process calls hand back the source's
430
- * own iterable — there is no connection to report on.
431
- */
432
- export type LiveSource<R> = R & {
433
- onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
434
- };
435
-
436
- /**
437
- * Declares a value-shaped live source: a server function returning an async
438
- * iterable whose yields are successive VALUES of one logical query, with
439
- * the contract that the source re-yields current state on every invocation.
440
- * Writes `live: true` on the metadata channel and brands the resolved
441
- * iterable (registered symbol `solid.LiveSource`) so SSR faces meeting the
442
- * value in-process can apply live policy (document face: first value, then
443
- * client takeover). Dispatch is untouched — over-the-wire calls stream the
444
- * raw registered function's result. Declare live outermost:
445
- * `live(GET(fn))`.
446
- */
447
- export function live<A extends readonly any[], R>(
448
- fn: (...args: A) => R
449
- ): ServerFunction<A, LiveSource<Awaited<R>>>;
450
-
451
- /** Identity of the currently executing server function call. */
452
- export interface ServerFunctionInvocation {
453
- id: string;
454
- }
455
-
456
- /**
457
- * Reads the in-flight server function invocation (its id) for the current
458
- * request event — usable inside a server function body, e.g. to key caches
459
- * or logs by function. Returns undefined outside a server function call.
460
- * The state lives in a module-private WeakMap keyed by the per-call request
461
- * event (never in `event.locals`, which derived events share with their
462
- * outer event). Distinct from `getServerFunctionMetadata(fn)`, which reads
463
- * a reference's static declaration metadata; this describes the call
464
- * currently executing.
465
- */
466
- export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
467
-
468
- /**
469
- * The event-keyed half of `getServerFunctionInvocation`, for callers handed
470
- * an event outside its provideEvent scope (the handler's result transforms
471
- * run after the scope has exited). Integration plumbing — application code
472
- * reads the ambient accessor instead.
473
- * @internal
474
- */
475
- export function getEventServerFunctionInvocation(
476
- event: RequestEvent | undefined
477
- ): ServerFunctionInvocation | undefined;
478
-
479
- /**
480
- * Hooks layering framework policy onto `handleServerFunctionRequest`.
481
- * All are optional — the bare handler dispatches, scopes events, and
482
- * encodes results on its own.
483
- */
484
- export interface HandleServerFunctionOptions {
485
- /**
486
- * Builds the request event a call runs under (default: bare
487
- * `{ request, locals: {} }`). Integrations supply their richer event
488
- * (cookies, response helpers, platform handles).
489
- */
490
- createEvent?(request: Request): ServerFunctionEvent;
491
- /**
492
- * Overrides the configured event provider for this handler — same
493
- * contract as the `provideEvent` config option.
494
- */
495
- provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
496
- /**
497
- * Overrides the configured per-invocation wrap for this handler — same
498
- * contract as the `wrapInvocation` config option (see
499
- * `WrapInvocationHook`), except it only applies to HTTP dispatch (a
500
- * per-request option can't see direct SSR calls).
501
- */
502
- wrapInvocation?: WrapInvocationHook;
503
- /**
504
- * Observes or replaces the function's result before encoding — the
505
- * extension point for response metadata policies (headers, statuses,
506
- * substituted results). Runs for returned and thrown results alike
507
- * (`context.thrown` distinguishes); `context.instance` is null for no-JS
508
- * calls. The context carries the call's identity — the function `id` and
509
- * the parsed `args` the implementation was invoked with — matching the
510
- * direct-call mirror (`transformDirectResult`), so a policy keying state
511
- * by the call works over either dispatch path. Return the result
512
- * unchanged to pass through, or a `ResponseEnvelope` (exposed through
513
- * the core entry) to send HTTP metadata plus a structured payload. Runs
514
- * before `collectFlightData`, so the flight hook sees the transformed
515
- * outcome — use `collectFlightData`, not this, to fold data into the
516
- * response.
517
- */
518
- transformResult?(
519
- event: ServerFunctionEvent,
520
- result: unknown,
521
- context: {
522
- id: string;
523
- args: unknown[];
524
- instance: string | null;
525
- request: Request;
526
- thrown?: boolean;
527
- }
528
- ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
529
- /**
530
- * Overrides the configured single-flight hook for this handler — same
531
- * contract as the `collectFlightData` config option (see
532
- * `CollectFlightDataHook`).
533
- */
534
- collectFlightData?: CollectFlightDataHook;
535
- /**
536
- * Overrides the configured single-flight fold policy for this handler —
537
- * same contract as the `transformFlightResult` config option.
538
- */
539
- transformFlightResult?(
540
- event: ServerFunctionEvent,
541
- outcome: { value: unknown; data: unknown },
542
- context: { id: string; args: unknown[]; instance: string | null; request: Request }
543
- ): Response | undefined | Promise<Response | undefined>;
544
- /**
545
- * Builds the response for calls made without the client runtime (no
546
- * instance header — no-JS form posts, direct HTTP). Receives the
547
- * (transformed) result, the request, and the decoded arguments; `thrown`
548
- * is set when the result was thrown rather than returned.
549
- *
550
- * Overrides the configured hook, which in turn overrides the built-in
551
- * `createNoJSHandler()` applied to browser form posts. Other
552
- * no-instance callers get the normal serialized response.
553
- */
554
- handleNoJS?(
555
- result: unknown,
556
- request: Request,
557
- args: unknown[],
558
- thrown?: boolean
559
- ): Response | Promise<Response>;
560
- /**
561
- * Overrides same-origin protection for this handler. Set to `false` only
562
- * when another trusted layer protects the endpoint.
563
- */
564
- csrf?: boolean | ServerFunctionCSRFOptions;
565
- /** Overrides the configured codec options for this handler. */
566
- codec?: JSONCodecOptions;
567
- }
568
-
569
- /**
570
- * Web-standard HTTP handler for server function calls: resolves the
571
- * function id from the request, gates GET dispatch on the declaration (405
572
- * for a GET request to a function that never declared `GET`; POST is always
573
- * accepted), decodes arguments, runs the function under a request-event scope,
574
- * and encodes the result (forwarding redirect/revalidation metadata
575
- * through headers). Mount it on the endpoint the client transport targets
576
- * (default `/_server`); platform adapters (h3, express, ...) convert their
577
- * request shape to a web `Request` around it.
578
- *
579
- * Requests are same-origin by default. The handler accepts browser requests
580
- * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
581
- * without usable metadata unless explicitly configured otherwise.
582
- *
583
- * When the event carries a `response` head stub (`event.response`, see the
584
- * server entry's `ResponseStub`), the handler folds it onto every outgoing
585
- * response as the head freezes — its `Set-Cookie` values (cookies appended
586
- * during the call) append cookie-by-cookie alongside the result's own,
587
- * other stub headers fill gaps (the call's response metadata wins; the
588
- * protocol-owned family — the error/format/single-flight tags, `Location`,
589
- * `X-Revalidate` — never fills, and neither does `Content-Type`/`Content-
590
- * Length` onto a bodiless response) — and marks the stub `committed`, so
591
- * later cookie/header writes report instead of silently missing the wire.
592
- *
593
- * ## Thrown-error sanitization (security default)
594
- *
595
- * A thrown `Response`/envelope (`redirect`/`reload`/`respond`) is intentional
596
- * control flow and is forwarded untouched. A *plain* thrown value (a bare
597
- * `Error`, string, or object) is different: serialized verbatim it would ship
598
- * its `message` and every own-property to the client — a driver/ORM error's
599
- * failing query, connection string, or bound parameters included. So outside
600
- * the dev build a plain thrown value is replaced with a generic `Error`
601
- * before serialization; the client still receives *an* `Error` (the shape
602
- * `submission.error` etc. expect), just with no leaked content. The dev
603
- * build keeps full fidelity (message, stack, own-props) for DX and the dev
604
- * toolbar inspector. Dev/prod is the BUILD VARIANT, not `NODE_ENV`:
605
- * `@solidjs/web` publishes a dev copy of this entry behind the
606
- * `development` export condition (what Vite dev resolves) and the default
607
- * resolution sanitizes — as does importing the runtime source directly with
608
- * no bundler signal (fail-safe).
609
- *
610
- * Escape hatch: brand the value with `markSafeError` (`Symbol.for(
611
- * "solid.SafeError")`) to send its content intact in every environment.
612
- * A `wrapInvocation`/`transformResult` override that maps errors expresses
613
- * intent the same way — throw a `Response`/envelope, or brand the mapped
614
- * error safe; an unbranded plain error it lets propagate is sanitized like
615
- * any other, so a framework onError policy must brand its result to keep a
616
- * custom client-facing message in production.
617
- *
618
- * @example
619
- * ```ts
620
- * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
621
- * import "virtual:solid-server-function-manifest";
622
- *
623
- * // in the server's request handling:
624
- * if (url.pathname.startsWith("/_server")) {
625
- * return handleServerFunctionRequest(request);
626
- * }
627
- * ```
628
- */
629
- export function handleServerFunctionRequest(
630
- request: Request,
631
- options?: HandleServerFunctionOptions
632
- ): Promise<Response>;
633
-
634
- /** Message a sanitized (production) server error carries on the wire. */
635
- export const GENERIC_SERVER_ERROR_MESSAGE: string;
636
-
637
- /**
638
- * The production error-sanitization policy `handleServerFunctionRequest`
639
- * applies to a plain thrown value before serialization. Returns `value`
640
- * unchanged in the dev build or when it is branded safe (`markSafeError`);
641
- * otherwise returns a generic `Error` carrying `GENERIC_SERVER_ERROR_MESSAGE`.
642
- * Exposed for frameworks composing their own dispatch around the same policy.
643
- */
644
- export function sanitizeServerError(value: unknown): unknown;
645
-
646
- export interface ServerFunctionRequestCall {
647
- type: "request";
648
- id: string;
649
- instance: string;
650
- request: Request;
651
- meta: ServerFunctionMetadata | undefined;
652
- time: number;
653
- }
654
-
655
- export interface ServerFunctionResponseCall {
656
- type: "response";
657
- id: string;
658
- instance: string;
659
- response: Response;
660
- meta: ServerFunctionMetadata | undefined;
661
- time: number;
662
- }
663
-
664
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
665
-
666
- /**
667
- * Client-only inspection seam. A no-op on this entry so isomorphic
668
- * `@solidjs/web/server-functions` imports resolve.
669
- */
670
- export function observeServerFunctionCalls(
671
- observer: (call: ServerFunctionCall) => void
672
- ): () => void;
673
-
674
- /**
675
- * Overrides the build-variant dev flag for this module instance — the seam
676
- * for test harnesses and hand-rolled bundles whose packaging cannot replace
677
- * `_DX_DEV_`. Applications never call this; select the dev build through
678
- * the `development` export condition instead.
679
- * @internal
680
- */
681
- export function setServerFunctionsDev(dev: boolean): void;