@solidjs/web 2.0.0-rc.6 → 2.0.0-rc.8

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 (82) hide show
  1. package/dist/{server.cjs → server.dev.js} +274 -272
  2. package/dist/server.js +119 -36
  3. package/dist/{dev.js → web.dev.js} +131 -399
  4. package/dist/web.js +78 -388
  5. package/dist/{web.cjs → web.observe.js} +174 -622
  6. package/frames/dist/client.dev.js +11 -3
  7. package/frames/dist/client.js +11 -3
  8. package/frames/dist/{server.cjs → server.dev.js} +375 -125
  9. package/frames/dist/server.js +253 -32
  10. package/frames/package.json +7 -15
  11. package/package.json +88 -251
  12. package/serialization/decode/package.json +3 -9
  13. package/serialization/dist/decode.js +18 -4
  14. package/serialization/dist/serialization.js +18 -4
  15. package/serialization/package.json +3 -9
  16. package/serialization/types/serializer-decode.d.ts +49 -2
  17. package/server-functions/dist/client.js +13 -14
  18. package/server-functions/dist/server.dev.js +359 -85
  19. package/server-functions/dist/server.js +352 -86
  20. package/server-functions/package.json +6 -24
  21. package/server-functions/rich-args/package.json +3 -9
  22. package/storage/package.json +3 -9
  23. package/types/client.d.ts +17 -3
  24. package/types/frames/frame-client.d.ts +1 -1
  25. package/types/frames/serializer-decode.d.ts +49 -2
  26. package/types/head.d.ts +3 -0
  27. package/types/index.d.ts +18 -7
  28. package/types/index.server.d.ts +31 -9
  29. package/types/render.d.ts +3 -1
  30. package/types/serializer-decode.d.ts +49 -2
  31. package/types/server-functions/flash.d.ts +12 -3
  32. package/types/server-functions/server.d.ts +50 -3
  33. package/types/server-mock.d.ts +43 -7
  34. package/types/server.d.ts +48 -6
  35. package/dist/dev.cjs +0 -2590
  36. package/frames/dist/client.cjs +0 -2035
  37. package/frames/dist/client.dev.cjs +0 -2055
  38. package/serialization/dist/decode.cjs +0 -141
  39. package/serialization/dist/serialization.cjs +0 -261
  40. package/serialization/types-cjs/index.d.cts +0 -101
  41. package/serialization/types-cjs/package.json +0 -3
  42. package/serialization/types-cjs/serializer-decode.d.cts +0 -172
  43. package/serialization/types-cjs/serializer.d.cts +0 -101
  44. package/server-functions/dist/client.cjs +0 -1070
  45. package/server-functions/dist/rich-args.cjs +0 -11
  46. package/server-functions/dist/server.cjs +0 -2133
  47. package/server-functions/dist/server.dev.cjs +0 -2153
  48. package/storage/dist/storage.cjs +0 -12
  49. package/storage/types-cjs/index.d.cts +0 -28
  50. package/storage/types-cjs/package.json +0 -3
  51. package/types/patch-driver.d.ts +0 -3
  52. package/types-cjs/client.d.cts +0 -200
  53. package/types-cjs/constants.d.cts +0 -20
  54. package/types-cjs/cookies.d.cts +0 -41
  55. package/types-cjs/frames/client.d.cts +0 -36
  56. package/types-cjs/frames/frame-client.d.cts +0 -370
  57. package/types-cjs/frames/frame-container-plugin.d.cts +0 -71
  58. package/types-cjs/frames/frame-sink.d.cts +0 -92
  59. package/types-cjs/frames/frame-transport.d.cts +0 -189
  60. package/types-cjs/frames/serializer-decode.d.cts +0 -172
  61. package/types-cjs/frames/serializer.d.cts +0 -101
  62. package/types-cjs/frames/server.d.cts +0 -52
  63. package/types-cjs/head.d.cts +0 -16
  64. package/types-cjs/index.d.cts +0 -180
  65. package/types-cjs/index.server.d.cts +0 -125
  66. package/types-cjs/jsx-properties.d.cts +0 -93
  67. package/types-cjs/jsx.d.cts +0 -4146
  68. package/types-cjs/package.json +0 -3
  69. package/types-cjs/patch-driver.d.cts +0 -3
  70. package/types-cjs/reconcile.d.cts +0 -1
  71. package/types-cjs/render.d.cts +0 -4
  72. package/types-cjs/response.d.cts +0 -81
  73. package/types-cjs/serializer-decode.d.cts +0 -172
  74. package/types-cjs/serializer.d.cts +0 -101
  75. package/types-cjs/server-functions/client.d.cts +0 -184
  76. package/types-cjs/server-functions/flash.d.cts +0 -27
  77. package/types-cjs/server-functions/registry.d.cts +0 -100
  78. package/types-cjs/server-functions/rich-args.d.cts +0 -1
  79. package/types-cjs/server-functions/server.d.cts +0 -522
  80. package/types-cjs/server-functions/shared.d.cts +0 -283
  81. package/types-cjs/server-mock.d.cts +0 -301
  82. package/types-cjs/server.d.cts +0 -366
@@ -1,100 +0,0 @@
1
- export type { InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, ServerFunctionRPC } from "./shared.cjs";
2
- import type { InvokeOptions } from "./shared.cjs";
3
- export declare const SERVER_FUNCTION_METADATA: unique symbol;
4
- /**
5
- * Reads a server function reference's declaration metadata (e.g.
6
- * `method: "GET"` for `GET(fn)` references). Returns undefined when `fn`
7
- * is not a server function reference; plain references carry an empty
8
- * metadata object.
9
- */
10
- export declare function getServerFunctionMetadata(fn: any): any;
11
- /**
12
- * Whether `fn` is a server function reference (a client proxy or a
13
- * server-side registered callable). Detection is by the registered-symbol
14
- * metadata brand, so it holds across duplicated module instances.
15
- */
16
- export declare function isServerFunction(fn: any): boolean;
17
- /**
18
- * Attaches user-declared transport metadata to a server function reference
19
- * (client proxy or server-registered callable) and returns the reference.
20
- * Writes ride the same channel `GET` uses: later writes shallow-merge over
21
- * earlier ones, and `getServerFunctionMetadata(fn)` reads the merged bag —
22
- * so `withMeta` composes with `GET` in either order.
23
- *
24
- * The pattern is declare-on-function, react-in-hook: metadata declared
25
- * here is what `prepareRequest` receives as `context.meta`, letting
26
- * session-dynamic transport policy key on declarations instead of
27
- * comparing function ids:
28
- *
29
- * ```ts
30
- * export const chargeCard = withMeta(async (amount: number) => {
31
- * "use server";
32
- * // ...
33
- * }, { requiresAuth: true });
34
- *
35
- * configureServerFunctionsClient({
36
- * prepareRequest(init, { meta }) {
37
- * if (meta?.requiresAuth) {
38
- * return {
39
- * ...init,
40
- * headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
41
- * };
42
- * }
43
- * return init;
44
- * }
45
- * });
46
- * ```
47
- */
48
- export declare function withMeta(fn: any, meta: any): any;
49
- export declare const SERVER_FUNCTION_INVOKE: unique symbol;
50
- /**
51
- * Applies a server function once with per-call, invocation-scoped options —
52
- * `Function.prototype.call` for server functions, the options bag in the
53
- * `thisArg` slot (declaration wrappers like `GET` and `withMeta` are `bind`:
54
- * they return a new reference with context baked in; `invoke` applies one
55
- * call and leaves no residue on the reference).
56
- *
57
- * ```ts
58
- * import { invoke } from "@solidjs/web/server-functions";
59
- *
60
- * const user = await invoke(getUser, { signal: controller.signal }, id);
61
- * ```
62
- *
63
- * Options are strictly invocation-scoped — things that vary between calls
64
- * of the SAME function and cannot be declared or configured: `signal`
65
- * (the call's lifecycle; aborting rejects the call and cancels the
66
- * request), `keepalive` (calls made while the page unloads), `priority`
67
- * (fetch priority hint). Anything with a longer lifetime is refused with a
68
- * pointer to its home: session-dynamic transport policy → `prepareRequest`;
69
- * declaration-static shape → `GET`/`withMeta`; call policy (retries,
70
- * dedupe, deadlines) → the data layer that owns the call, wired through
71
- * `signal`.
72
- *
73
- * Dispatches through the reference's invocation channel
74
- * (`SERVER_FUNCTION_INVOKE`). Core's declaration wrappers forward it —
75
- * `GET` invokes over its query encoding, `live` ends its iteration on
76
- * abort. Wrappers that share calls (caches, channels) may adapt or decline
77
- * it; a data layer needs neither — it holds the reference below such
78
- * wrappers and invokes it directly with its own signal. On the server the
79
- * call runs in-process: `signal`
80
- * rejects the caller (the work, like a server behind HTTP, runs on unless
81
- * the function observes a signal itself) and the transport hints are
82
- * no-ops, since they describe a wire that does not exist.
83
- */
84
- export declare function invoke<A extends readonly any[], R>(fn: (...args: A) => R, options: InvokeOptions, ...args: A): R;
85
- export declare const LIVE_SOURCE: unique symbol;
86
- /**
87
- * Fills the RPC seam. Called by the transport halves (client fetch RPC,
88
- * server in-process dispatch) when the first server function reference is
89
- * created; first write wins — both halves register equivalent surfaces, and
90
- * a per-build half never coexists with the other build's.
91
- * @internal
92
- */
93
- export declare function provideServerFunctionRPC(rpc: any): void;
94
- /**
95
- * The registered RPC surface, or undefined when no server function exists
96
- * in this build's graph. Integration plumbing (routers): gate every use of
97
- * the transport/codec behind this read instead of importing it.
98
- * @internal
99
- */
100
- export declare function getServerFunctionRPC(): any;
@@ -1 +0,0 @@
1
- export declare function enableRichArguments(): void;
@@ -1,522 +0,0 @@
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.cjs";
2
- export { decodeFlashCookie, encodeFlashCookie } from "./flash.cjs";
3
- import { ResponseEnvelope } from "../response.cjs";
4
- import { JSONCodecOptions } from "../serializer-decode.cjs";
5
- import { RequestEvent } from "../server.cjs";
6
- import type { ServerFunction, ServerFunctionMetadata } from "./shared.cjs";
7
- export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.cjs";
8
- export type { FlashSubmission } from "./flash.cjs";
9
- /**
10
- * The request event a server function call runs under: the base
11
- * `RequestEvent` (request + locals) with `serverOnly` added, set when the
12
- * call is an in-process SSR invocation whose result never serializes to a
13
- * client.
14
- */
15
- export interface ServerFunctionEvent extends RequestEvent {
16
- serverOnly?: boolean;
17
- }
18
- /**
19
- * What a server function call resolved to, as seen by the single-flight
20
- * hook — enough context for any data-production strategy without core
21
- * assuming one.
22
- */
23
- export interface ServerFunctionOutcome {
24
- /** The build-stable id of the function that ran. */
25
- id: string;
26
- /**
27
- * The value the caller will receive: the raw return for plain results,
28
- * the unwrapped `value` for `ResponseEnvelope`s, `null` for body-less
29
- * control-flow `Response`s (redirect/reload).
30
- */
31
- value: unknown;
32
- /**
33
- * The `Response` carrying the result's HTTP metadata, when there is one
34
- * (from a returned/thrown `Response` or a `ResponseEnvelope`). Read
35
- * `Location` here for redirect-with-data — the data should describe the
36
- * destination route — and `X-Revalidate` for the invalidated keys.
37
- * Undefined for plain values.
38
- */
39
- response: Response | undefined;
40
- /**
41
- * The original HTTP request, untouched: headers the client integration
42
- * sent (referrer, custom route context) ride here for the hook to read —
43
- * core assigns them no meaning.
44
- */
45
- request: Request;
46
- /** Whether the result was thrown rather than returned. */
47
- thrown: boolean;
48
- /**
49
- * The URL the client will show after the mutation — the redirect
50
- * `Location` when the outcome carries one (resolved against the request
51
- * URL, as a browser would), the referring page otherwise. Undefined
52
- * without a usable referer (a non-browser caller has no page to produce
53
- * data for) and for redirects leaving the app's origin: produce no data
54
- * when this is undefined.
55
- */
56
- targetUrl: string | undefined;
57
- /**
58
- * The outcome's `X-Revalidate` keys, split — the invalidation scope the
59
- * mutation declared. Undefined when the outcome carries none (integrations
60
- * typically collect everything for the target in that case).
61
- */
62
- revalidateKeys: string[] | undefined;
63
- /**
64
- * The request headers with the mutation's cookie effects applied: the
65
- * event response's `Set-Cookie`s (set during the call), then the
66
- * outcome's own (e.g. `redirect(to, { headers })`), later winning on
67
- * conflict, deletions honored. Build the data-collection request from
68
- * these so re-run reads observe post-mutation cookie state.
69
- */
70
- foldedHeaders: Headers;
71
- }
72
- /**
73
- * The single-flight server hook: given the request event and the function's
74
- * outcome, optionally produce a data payload (possibly async) to fold into
75
- * the response alongside the return value. Data production is a black box
76
- * to the protocol — render data-only, run route preloads, query a cache,
77
- * whatever the integration chooses; the payload just has to be
78
- * codec-serializable. Return undefined to send the response unchanged
79
- * (byte-identical to a call without the hook).
80
- *
81
- * Runs after `transformResult`, only for scripted calls that sent
82
- * `SINGLE_FLIGHT_HEADER` on the request, on returned results and thrown
83
- * `Response`/`ResponseEnvelope` control-flow signals alike (plain thrown
84
- * errors never collect, and neither do raw body-carrying `Response` values
85
- * — those are the caller's verbatim payload). The handler owns the
86
- * enveloping: contributed data ships as `{ value, data }` under the
87
- * single-flight response header. The generic halves of collection arrive
88
- * pre-digested on the outcome (`targetUrl`, `revalidateKeys`,
89
- * `foldedHeaders`); the hook supplies only the data strategy.
90
- */
91
- export type CollectFlightDataHook = (event: ServerFunctionEvent, outcome: ServerFunctionOutcome) => unknown | Promise<unknown>;
92
- /**
93
- * Wraps a server function execution — the per-invocation seam for
94
- * framework policies (per-function middleware, auth, logging, error
95
- * mapping). Called inside the call's event scope with the invocation
96
- * identity already established: `getServerFunctionInvocation()` answers
97
- * before, during and after `run()`. Must return (or resolve to) `run()`'s
98
- * result — replacing it replaces the function's result; throwing routes
99
- * through the handler's normal error encoding.
100
- *
101
- * The context carries the call's identity (`id`, parsed `args`), its
102
- * `event`, and how it arrived: `direct` is `true` for in-process SSR calls
103
- * (where `request` is absent) and `false` for HTTP dispatch. On the direct
104
- * path the wrapper must stay transparent for synchronous functions —
105
- * return `run()`'s value, not an unconditional promise, unless it needs to
106
- * be async.
107
- */
108
- export type WrapInvocationHook = (run: () => unknown, context: {
109
- id: string;
110
- args: unknown[];
111
- event: ServerFunctionEvent;
112
- request?: Request;
113
- direct: boolean;
114
- }) => unknown;
115
- /** Options for `createNoJSHandler`. */
116
- export interface NoJSHandlerOptions {
117
- /** The app's mount path, for resolving a relative redirect `Location`. */
118
- base?: string;
119
- }
120
- export type ServerFunctionOriginMatcher = string | readonly string[] | ((origin: string, request: Request) => boolean | Promise<boolean>);
121
- /** Same-origin validation options for server function requests. */
122
- export interface ServerFunctionCSRFOptions {
123
- /**
124
- * Expected public origin. Defaults to the incoming request URL's origin.
125
- * A function can validate origins dynamically for multi-tenant hosts.
126
- */
127
- origin?: ServerFunctionOriginMatcher;
128
- /**
129
- * Allows requests without `Sec-Fetch-Site`, `Origin`, or `Referer`.
130
- * Cross-origin metadata is still rejected.
131
- * @default false
132
- */
133
- allowRequestsWithoutOriginCheck?: boolean;
134
- /**
135
- * Applies the origin gate to GET-declared reads as well. By default the
136
- * gate is skipped for declared reads: same-origin policy already keeps a
137
- * cross-site caller from READING the response, and the gate's `Vary`
138
- * fragments (or, on CDNs that ignore Vary, poisons) the shared-cache
139
- * entries the `GET` helper exists to enable (#3071). The premise that
140
- * skip rests on is `GET()`'s safety contract — declared reads are safe
141
- * to EXECUTE from any origin (#3114). A deployment that does not rely
142
- * on shared caches can enable this to gate its reads too.
143
- * @default false
144
- */
145
- protectDeclaredReads?: boolean;
146
- }
147
- /** Options for `configureServerFunctionsServer`. */
148
- export interface ServerFunctionsServerConfig {
149
- /**
150
- * Establishes the request-event scope for a call — the function passed
151
- * runs with `event` visible to `getRequestEvent()`. Wire it to
152
- * `provideRequestEvent` from `@solidjs/web/storage` (or the framework's
153
- * equivalent). When omitted, falls back to the AsyncLocalStorage instance
154
- * an established request scope parks on the global.
155
- */
156
- provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
157
- /**
158
- * Wraps every server function execution — HTTP dispatch and direct SSR
159
- * calls alike — with the invocation identity already established (see
160
- * `WrapInvocationHook`). The per-invocation seam for framework policies:
161
- * per-function middleware, auth, logging, error mapping. A per-request
162
- * option overrides it for HTTP dispatch.
163
- */
164
- wrapInvocation?: WrapInvocationHook;
165
- /**
166
- * The unnamed single-flight hook: produces the data payload folded into
167
- * responses of calls that opted in (see `CollectFlightDataHook`).
168
- * Registered once by the integration that owns data production (a
169
- * router); per-handler `collectFlightData` options override it. Other
170
- * integrations contribute additively through
171
- * `registerFlightDataSource(id, hook)` instead of competing for this
172
- * slot.
173
- */
174
- collectFlightData?: CollectFlightDataHook;
175
- /**
176
- * Server-wide default for the handler's `transformResult` (same contract
177
- * — see `HandleServerFunctionRequestOptions`); a per-request option
178
- * overrides it. Registering it here makes result policies (e.g. frames'
179
- * `frameTransformResult`) work through generic dispatchers that call
180
- * `handleServerFunctionRequest(request)` with no options.
181
- */
182
- transformResult?(event: ServerFunctionEvent, result: unknown, context: {
183
- id: string;
184
- args: unknown[];
185
- instance: string | null;
186
- request: Request;
187
- thrown?: boolean;
188
- }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
189
- /**
190
- * `transformResult`'s counterpart for the single-flight fold: when a
191
- * call's flight payload needs a body only a policy knows how to build
192
- * (frames' `frameTransformFlightResult` — an invalidated entry is
193
- * markup), this gets first refusal on the `{ value, data }` outcome.
194
- * Return a `Response` to carry the outcome (call headers and cookies are
195
- * copied onto it), or `undefined` to decline and keep the plain
196
- * serialized envelope. A per-request option overrides it.
197
- */
198
- transformFlightResult?(event: ServerFunctionEvent, outcome: {
199
- value: unknown;
200
- data: unknown;
201
- }, context: {
202
- id: string;
203
- args: unknown[];
204
- instance: string | null;
205
- request: Request;
206
- }): Response | undefined | Promise<Response | undefined>;
207
- /**
208
- * The in-process mirror of `transformResult` for direct (same-server)
209
- * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
210
- */
211
- transformDirectResult?(value: unknown, options: {
212
- id: string;
213
- args: unknown[];
214
- event: ServerFunctionEvent;
215
- }): unknown;
216
- /**
217
- * Server-wide response builder for calls made without the client runtime
218
- * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
219
- * per-request option overrides it. Set it to `createNoJSHandler({ base })`
220
- * to apply the convention to every non-scripted call rather than only to
221
- * browser form posts, to a handler of your own to replace it, or to
222
- * `null` to disable the built-in convention and answer form posts with
223
- * the plain serialized response.
224
- */
225
- handleNoJS?: ((result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response | Promise<Response>) | null;
226
- /**
227
- * Mount path the HTTP handler answers on. Must match the client
228
- * configuration — the id travels as the segment after it, a request whose
229
- * path does not start with it is not a call, and SSR'd reference `url`s
230
- * (e.g. form actions) derive from it. Prefix it when the app serves from
231
- * a base path (e.g. `` `${BASE_URL}_server` ``).
232
- * @default "/_server"
233
- */
234
- endpoint?: string;
235
- /**
236
- * Same-origin protection for HTTP server function calls. Enabled by
237
- * default. Set to `false` only when another trusted layer protects the
238
- * endpoint.
239
- */
240
- csrf?: boolean | ServerFunctionCSRFOptions;
241
- /**
242
- * Codec options (extra plugins etc.) for decoding arguments and encoding
243
- * results — must match the client's. Stored in the shared layer, so
244
- * `decodeResponse` sees them too. When `serializeErrorStacks` is omitted,
245
- * the server-function boundary defaults it from this module's compiled
246
- * development variant.
247
- */
248
- codec?: JSONCodecOptions;
249
- /**
250
- * Upper bound, in bytes, on a call's argument payload — the POST body,
251
- * or the `?args=` query encoding. The payload is buffered and decoded
252
- * before dispatch, so its cost is paid before application code can
253
- * decline it; the bound is enforced up front and a request over it is
254
- * refused with `413` before any decoding (#3115). Raise it for functions
255
- * that accept large uploads, or set `Infinity` to remove the bound.
256
- * @default 1_048_576 (1 MiB)
257
- */
258
- bodySizeLimit?: number;
259
- /**
260
- * Upper bound on the number of arguments a call may carry. The decoded
261
- * argument array is spread into the function call, so an unbounded list
262
- * forces a range error out of any function regardless of what it does;
263
- * past the bound the request is refused with `400` (#3115).
264
- * @default 1000
265
- */
266
- maxArguments?: number;
267
- }
268
- /**
269
- * A registered server function: its build-stable id paired with the
270
- * original implementation. Returned by `registerServerReference` and
271
- * consumed by the server-side `createServerReference`.
272
- *
273
- * Compiler ABI shape; hand-written code rarely constructs these.
274
- * @internal
275
- */
276
- export interface ServerFunctionReference<T extends any[] = any[], R = any> {
277
- id: string;
278
- fn: (...args: T) => R;
279
- /**
280
- * The function's source name, emitted by development builds only —
281
- * `createServerReference` seeds the metadata channel with it.
282
- * @internal
283
- */
284
- name?: string;
285
- }
286
- /** Wire-state transitions a live call's iterable can report (client side).
287
- * `"closed"` carries the error when a definite rejection (4xx) ended the
288
- * call instead of the retry loop. */
289
- export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
290
- /**
291
- * Type-level mirror of the client's live answer shape so isomorphic code
292
- * assigning `onstatus` typechecks against either build's declarations. On
293
- * the server the hook is inert: in-process calls hand back the source's
294
- * own iterable — there is no connection to report on.
295
- */
296
- export type LiveSource<R> = R & {
297
- onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
298
- };
299
- /** Identity of the currently executing server function call. */
300
- export interface ServerFunctionInvocation {
301
- id: string;
302
- }
303
- /**
304
- * Hooks layering framework policy onto `handleServerFunctionRequest`.
305
- * All are optional — the bare handler dispatches, scopes events, and
306
- * encodes results on its own.
307
- */
308
- export interface HandleServerFunctionOptions {
309
- /**
310
- * Builds the request event a call runs under (default: bare
311
- * `{ request, locals: {} }`). Integrations supply their richer event
312
- * (cookies, response helpers, platform handles).
313
- */
314
- createEvent?(request: Request): ServerFunctionEvent;
315
- /**
316
- * Overrides the configured event provider for this handler — same
317
- * contract as the `provideEvent` config option.
318
- */
319
- provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
320
- /**
321
- * Overrides the configured per-invocation wrap for this handler — same
322
- * contract as the `wrapInvocation` config option (see
323
- * `WrapInvocationHook`), except it only applies to HTTP dispatch (a
324
- * per-request option can't see direct SSR calls).
325
- */
326
- wrapInvocation?: WrapInvocationHook;
327
- /**
328
- * Observes or replaces the function's result before encoding — the
329
- * extension point for response metadata policies (headers, statuses,
330
- * substituted results). Runs for returned and thrown results alike
331
- * (`context.thrown` distinguishes); `context.instance` is null for no-JS
332
- * calls. The context carries the call's identity — the function `id` and
333
- * the parsed `args` the implementation was invoked with — matching the
334
- * direct-call mirror (`transformDirectResult`), so a policy keying state
335
- * by the call works over either dispatch path. Return the result
336
- * unchanged to pass through, or a `ResponseEnvelope` (exposed through
337
- * the core entry) to send HTTP metadata plus a structured payload. Runs
338
- * before `collectFlightData`, so the flight hook sees the transformed
339
- * outcome — use `collectFlightData`, not this, to fold data into the
340
- * response.
341
- */
342
- transformResult?(event: ServerFunctionEvent, result: unknown, context: {
343
- id: string;
344
- args: unknown[];
345
- instance: string | null;
346
- request: Request;
347
- thrown?: boolean;
348
- }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
349
- /**
350
- * Overrides the configured single-flight hook for this handler — same
351
- * contract as the `collectFlightData` config option (see
352
- * `CollectFlightDataHook`).
353
- */
354
- collectFlightData?: CollectFlightDataHook;
355
- /**
356
- * Overrides the configured single-flight fold policy for this handler —
357
- * same contract as the `transformFlightResult` config option.
358
- */
359
- transformFlightResult?(event: ServerFunctionEvent, outcome: {
360
- value: unknown;
361
- data: unknown;
362
- }, context: {
363
- id: string;
364
- args: unknown[];
365
- instance: string | null;
366
- request: Request;
367
- }): Response | undefined | Promise<Response | undefined>;
368
- /**
369
- * Builds the response for calls made without the client runtime (no
370
- * instance header — no-JS form posts, direct HTTP). Receives the
371
- * (transformed) result, the request, and the decoded arguments; `thrown`
372
- * is set when the result was thrown rather than returned.
373
- *
374
- * Overrides the configured hook, which in turn overrides the built-in
375
- * `createNoJSHandler()` applied to browser form posts. Other
376
- * no-instance callers get the normal serialized response.
377
- */
378
- handleNoJS?(result: unknown, request: Request, args: unknown[], thrown?: boolean): Response | Promise<Response>;
379
- /**
380
- * Overrides same-origin protection for this handler. Set to `false` only
381
- * when another trusted layer protects the endpoint.
382
- */
383
- csrf?: boolean | ServerFunctionCSRFOptions;
384
- /** Overrides the configured codec options for this handler. */
385
- codec?: JSONCodecOptions;
386
- /**
387
- * Overrides the configured argument payload bound for this handler (see
388
- * `ServerFunctionsServerConfig.bodySizeLimit`).
389
- */
390
- bodySizeLimit?: number;
391
- /**
392
- * Overrides the configured argument count bound for this handler (see
393
- * `ServerFunctionsServerConfig.maxArguments`).
394
- */
395
- maxArguments?: number;
396
- }
397
- export interface ServerFunctionRequestCall {
398
- type: "request";
399
- id: string;
400
- instance: string;
401
- request: Request;
402
- meta: ServerFunctionMetadata | undefined;
403
- time: number;
404
- }
405
- export interface ServerFunctionResponseCall {
406
- type: "response";
407
- id: string;
408
- instance: string;
409
- response: Response;
410
- meta: ServerFunctionMetadata | undefined;
411
- time: number;
412
- }
413
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
414
- export declare function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
415
- export declare function registerFlightDataSource(source: string, hook: CollectFlightDataHook): () => void;
416
- export declare function registerServerFunction<T extends any[], R>(id: string, callback: (...args: T) => R): (...args: T) => R;
417
- export declare function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
418
- export declare function registerServerReference<T extends any[], R>(id: string, fn: (...args: T) => R, name?: string): ServerFunctionReference<T, R>;
419
- export declare function createServerReference<T extends any[], R>(reference: ServerFunctionReference<T, R>): (...args: T) => R;
420
- export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
421
- export declare function live<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, LiveSource<Awaited<R>>>;
422
- export declare function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
423
- export declare function getEventServerFunctionInvocation(event: RequestEvent | undefined): ServerFunctionInvocation | undefined;
424
- export declare function foldSetCookies(headers: Headers, setCookies: readonly string[]): Headers;
425
- export declare function createNoJSHandler(options?: NoJSHandlerOptions): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response;
426
- /** @internal */
427
- export declare function guardFailures(value: any, state: any): any;
428
- /**
429
- * The response-side codec stream: `serializeStream` (shared.js) hardened
430
- * with request-lifetime teardown. Server-only on purpose — the shared half
431
- * is re-exported into client bundles, where this plumbing is dead weight.
432
- *
433
- * An abort of `signal` (the platform fires request.signal when the caller's
434
- * fetch aborts or the tab goes away) or the consumer cancelling the
435
- * ReadableStream (how platforms surface a dropped connection to the body)
436
- * stops pending serialization and tears down EVERY async-iterable or
437
- * ReadableStream source in the result graph, nested ones included (#3125) —
438
- * each producer's `iterator.return()` / `reader.cancel()` runs, so
439
- * generator `finally` blocks execute instead of the server pumping streams
440
- * nobody is reading. The wiring rides guardFailures' walk: it already wraps
441
- * every channel before the codec sees the value, so the demand gate and the
442
- * teardown registry are threaded through its state (`{ items: rows() }` —
443
- * a cursor beside a total — gets the same two guarantees as `return rows()`).
444
- */
445
- export declare function serializeResponseStream(value: any, codecOptions: any, signal: any, scope: any): ReadableStream<any>;
446
- /** Message a sanitized (production) server error carries on the wire. */
447
- export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
448
- export declare function setServerFunctionsDev(dev: boolean): void;
449
- export declare function sanitizeServerError(value: unknown): unknown;
450
- export declare function observeServerFunctionCalls(observer: (call: ServerFunctionCall) => void): () => void;
451
- export declare function serverFunctionUrl(id: string, boundArgs?: readonly unknown[]): string;
452
- export declare function parseServerFunctionUrl(url: string): string | null;
453
- /**
454
- * Web-standard HTTP handler for server function calls: resolves the
455
- * function id from the request, enforces the method allowlist (POST always
456
- * dispatches; GET and HEAD dispatch only to functions that declared `GET`,
457
- * with HEAD returning the equivalent GET's status and headers minus the
458
- * body; every other method answers 405), decodes arguments, runs the
459
- * function under a request-event scope, and encodes the result (forwarding
460
- * redirect/revalidation metadata through headers). Mount it on the endpoint
461
- * the client transport targets (default `/_server`); platform adapters (h3,
462
- * express, ...) convert their request shape to a web `Request` around it.
463
- *
464
- * Requests are same-origin by default. The handler accepts browser requests
465
- * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
466
- * without usable metadata unless explicitly configured otherwise. GET/HEAD
467
- * requests to `GET`-declared functions skip this gate: they are reads by
468
- * contract, cross-site response READING is already blocked by same-origin
469
- * policy, and skipping it keeps the `Vary: Sec-Fetch-Site, Origin, Referer`
470
- * it would impose off the responses shared caches are meant to store.
471
- *
472
- * Every response leaves with `Cache-Control: no-store` unless the function
473
- * set its own cache policy (via `respond()` headers or a returned
474
- * `Response`) — caching is opt-in on the wire, not just in prose.
475
- *
476
- * When the event carries a `response` head stub (`event.response`, see the
477
- * server entry's `ResponseStub`), the handler folds it onto every outgoing
478
- * response as the head freezes — its `Set-Cookie` values (cookies appended
479
- * during the call) append cookie-by-cookie alongside the result's own,
480
- * other stub headers fill gaps (the call's response metadata wins; the
481
- * protocol-owned family — the error/format/single-flight tags, `Location`,
482
- * `X-Revalidate` — never fills, and neither does `Content-Type`/`Content-
483
- * Length` onto a bodiless response) — and marks the stub `committed`, so
484
- * later cookie/header writes report instead of silently missing the wire.
485
- *
486
- * ## Thrown-error sanitization (security default)
487
- *
488
- * A thrown `Response`/envelope (`redirect`/`reload`/`respond`) is intentional
489
- * control flow and is forwarded untouched. A *plain* thrown value (a bare
490
- * `Error`, string, or object) is different: serialized verbatim it would ship
491
- * its `message` and every own-property to the client — a driver/ORM error's
492
- * failing query, connection string, or bound parameters included. So outside
493
- * the dev build a plain thrown value is replaced with a generic `Error`
494
- * before serialization; the client still receives *an* `Error` (the shape
495
- * `submission.error` etc. expect), just with no leaked content. The dev
496
- * build keeps full fidelity (message, stack, own-props) for DX and the dev
497
- * toolbar inspector. Dev/prod is the BUILD VARIANT, not `NODE_ENV`:
498
- * `@solidjs/web` publishes a dev copy of this entry behind the
499
- * `development` export condition (what Vite dev resolves) and the default
500
- * resolution sanitizes — as does importing the runtime source directly with
501
- * no bundler signal (fail-safe).
502
- *
503
- * Escape hatch: brand the value with `markSafeError` (`Symbol.for(
504
- * "solid.SafeError")`) to send its content intact in every environment.
505
- * A `wrapInvocation`/`transformResult` override that maps errors expresses
506
- * intent the same way — throw a `Response`/envelope, or brand the mapped
507
- * error safe; an unbranded plain error it lets propagate is sanitized like
508
- * any other, so a framework onError policy must brand its result to keep a
509
- * custom client-facing message in production.
510
- *
511
- * @example
512
- * ```ts
513
- * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
514
- * import "virtual:solid-server-function-manifest";
515
- *
516
- * // in the server's request handling:
517
- * if (url.pathname.startsWith("/_server")) {
518
- * return handleServerFunctionRequest(request);
519
- * }
520
- * ```
521
- */
522
- export declare function handleServerFunctionRequest(request: Request, options?: HandleServerFunctionOptions): Promise<Response>;