@solidjs/web 2.0.0-rc.2 → 2.0.0-rc.21

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 +5165 -0
  3. package/dist/server.js +1876 -374
  4. package/dist/{server.cjs → server.observe.js} +2070 -577
  5. package/dist/{dev.cjs → web.dev.js} +955 -567
  6. package/dist/web.js +646 -350
  7. package/dist/{dev.js → web.observe.js} +699 -421
  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 +2545 -0
  14. package/frames/dist/server.js +1683 -3004
  15. package/frames/dist/server.observe.js +2544 -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 +282 -88
  28. package/serialization/package.json +2 -15
  29. package/serialization/types/index.d.ts +115 -153
  30. package/serialization/types/serializer-decode.d.ts +173 -114
  31. package/serialization/types/serializer.d.ts +144 -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 +102 -1
  36. package/server-functions/dist/server.dev.js +2802 -299
  37. package/server-functions/dist/server.js +2724 -314
  38. package/server-functions/dist/server.observe.js +3680 -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 +115 -153
  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 +115 -153
  72. package/types/server-functions/argument-codec.d.ts +30 -0
  73. package/types/server-functions/client.d.ts +237 -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 +538 -531
  78. package/types/server-functions/shared.d.ts +398 -425
  79. package/types/server-functions/uploads.d.ts +53 -0
  80. package/types/server-mock.d.ts +154 -20
  81. package/types/server-observe.d.ts +86 -0
  82. package/types/server.d.ts +601 -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,50 +1,18 @@
1
- import { JSONCodecOptions } from "../serializer-decode.js";
2
- import { ServerFunction, ServerFunctionMetadata } from "./shared.js";
3
-
4
- export {
5
- ChunkReader,
6
- ERROR_HEADER,
7
- FLASH_COOKIE,
8
- FUNCTION_HEADER,
9
- INSTANCE_HEADER,
10
- SINGLE_FLIGHT_HEADER,
11
- clearFlashCookie,
12
- createChunk,
13
- decodeErrorHeaderValue,
14
- decodeResponse,
15
- decodeResponsePayload,
16
- deserializeStream,
17
- encodeErrorHeaderValue,
18
- frameAddress,
19
- getFlightDataConsumer,
20
- getServerFunctionMetadata,
21
- getServerFunctionsCodec,
22
- hasFlashCookie,
23
- isServerFunction,
24
- serializeString,
25
- subscribeFlightData,
26
- withMeta
27
- } from "./shared.js";
1
+ import type { ServerFunction, ServerFunctionMetadata } from "./shared.js";
2
+ export { ChunkReader, ERROR_HEADER, EVENT_STREAM_HEARTBEAT, EventStreamReader, FLASH_COOKIE, LAST_EVENT_ID_HEADER, LIVE_WIRE, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, createChunk, createEventChunk, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, deliverFlightData, deserializeStream, encodeErrorHeaderValue, frameAddress, getFlightDataConsumer, getFlightDataSourceIds, getServerFunctionMetadata, getServerFunctionsCodec, hasFlashCookie, hasFlightMetadata, invoke, isEventStream, isServerFunction, positionDigest, serializeString, subscribeFlightData, withMeta } from "./shared.js";
28
3
  export { REVALIDATE_HEADER } from "../response.js";
29
- export type {
30
- FlightDataConsumer,
31
- FlightDataContext,
32
- ServerFunction,
33
- ServerFunctionMetadata,
34
- SingleFlightPayload
35
- } from "./shared.js";
36
-
4
+ import { JSONCodecOptions } from "../serializer-decode.js";
5
+ export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.js";
37
6
  /** The context `prepareRequest` receives alongside the outgoing RequestInit. */
38
7
  export interface PrepareRequestContext {
39
- /** The build-stable id of the function being called. */
40
- id: string;
41
- /**
42
- * The reference's declaration metadata (e.g. `method: "GET"` for
43
- * `GET(fn)` references). Plain references carry an empty object.
44
- */
45
- meta: ServerFunctionMetadata | undefined;
8
+ /** The build-stable id of the function being called. */
9
+ id: string;
10
+ /**
11
+ * The reference's declaration metadata (e.g. `method: "GET"` for
12
+ * `GET(fn)` references). Plain references carry an empty object.
13
+ */
14
+ meta: ServerFunctionMetadata | undefined;
46
15
  }
47
-
48
16
  /**
49
17
  * Client-side session-dynamic transport hook: runs before every
50
18
  * server-function fetch. Return (or mutate and return) the RequestInit the
@@ -54,141 +22,171 @@ export interface PrepareRequestContext {
54
22
  * the client-side symmetric of the server handler hooks. Single hook, not
55
23
  * a chain — compose by wrapping functions in userland.
56
24
  */
57
- export type PrepareRequestHook = (
58
- init: RequestInit,
59
- context: PrepareRequestContext
60
- ) => RequestInit | Promise<RequestInit>;
61
-
25
+ export type PrepareRequestHook = (init: RequestInit, context: PrepareRequestContext) => RequestInit | Promise<RequestInit>;
26
+ /** How the transport sends a request: `fetch`'s shape, as the runtime calls it. */
27
+ export type ServerFunctionsSend = (address: string, init: RequestInit) => Response | Promise<Response>;
62
28
  /** Options for `configureServerFunctionsClient`. */
63
29
  export interface ServerFunctionsClientConfig {
64
- /**
65
- * Endpoint the server's HTTP handler is mounted on. Must match the
66
- * server configuration — SSR'd reference `url`s (e.g. form actions) and
67
- * client fetches both derive from it. Prefix it when the app serves from
68
- * a base path (e.g. `` `${BASE_URL}_server` ``).
69
- * @default "/_server"
70
- */
71
- endpoint?: string;
72
- /**
73
- * Codec options (extra plugins etc.) for encoding arguments and decoding
74
- * results — must match the server's. Stored in the shared layer, so
75
- * `decodeResponse` sees them too.
76
- */
77
- codec?: JSONCodecOptions;
78
- /**
79
- * Runs before every server-function fetch. Return (or mutate and return)
80
- * the RequestInit the transport will use; `context.meta` is the
81
- * reference's declaration metadata (e.g. method). For session-dynamic
82
- * cross-cutting concerns — bearer tokens, tracing headers:
83
- *
84
- * ```ts
85
- * configureServerFunctionsClient({
86
- * prepareRequest(init) {
87
- * return {
88
- * ...init,
89
- * headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
90
- * };
91
- * }
92
- * });
93
- * ```
94
- */
95
- prepareRequest?: PrepareRequestHook;
96
- /**
97
- * Response-side integration seam — the client mirror of the handler's
98
- * `transformResult`. `handle(response, ctx)` sees every response before
99
- * the transport decodes it; returning anything but undefined resolves the
100
- * call with that value. `capture(info)` runs synchronously at the call
101
- * site (before any await) and its return arrives as `ctx.context`, so
102
- * ambient per-call state (e.g. a reactive owner) survives to response
103
- * time. See `createServerComponentHandler` in frame-transport for the
104
- * canonical implementation.
105
- */
106
- responseHandler?: {
107
- capture?(info: { id: string; meta: unknown }): unknown;
108
- handle(
109
- response: Response,
110
- ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
111
- ): unknown;
112
- };
113
- /**
114
- * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
115
- * always go as plain JSON (no codec in the bundle); anything else throws
116
- * unless this is set. Installed by `enableRichArguments()` from the
117
- * rich-args entry — set directly only for custom wire encodings.
118
- */
119
- serializeArgs?(args: unknown[]): string | Promise<string>;
120
- }
121
-
122
- /**
123
- * Configures the client transport. Call once, before any server function is
124
- * invoked — typically in the client entry, next to `hydrate()`. Only needed
125
- * when deviating from the defaults (custom endpoint, codec plugins, or a
126
- * `prepareRequest` hook).
127
- */
128
- export function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
129
-
130
- export interface ServerFunctionRequestCall {
131
- type: "request";
132
- id: string;
133
- instance: string;
134
- request: Request;
135
- meta: ServerFunctionMetadata | undefined;
136
- time: number;
137
- }
138
-
139
- export interface ServerFunctionResponseCall {
140
- type: "response";
141
- id: string;
142
- instance: string;
143
- response: Response;
144
- meta: ServerFunctionMetadata | undefined;
145
- time: number;
30
+ /**
31
+ * Mount path the server's HTTP handler answers on. Must match the server
32
+ * configuration — the id travels as the segment after it, and SSR'd
33
+ * reference `url`s (e.g. form actions) and client fetches both derive
34
+ * from it. Prefix it when the app serves from a base path
35
+ * (e.g. `` `${BASE_URL}_server` ``).
36
+ *
37
+ * An absolute URL (`"https://api.example.com/_server"`) targets a handler
38
+ * on another origin — for a client-only build served from elsewhere: a
39
+ * static site, a browser extension, a WebView (`capacitor://localhost`)
40
+ * whose local server owns every path on its own hostname. The call is
41
+ * then cross-origin, and the server admits it only when its
42
+ * `configureServerFunctionsServer({ csrf: { origin } })` allowlist names
43
+ * the page's origin; it answers with the CORS headers the browser needs
44
+ * (`Access-Control-Allow-Origin`, the preflight, the protocol's headers
45
+ * exposed). Authenticate such a client with a bearer token through
46
+ * `prepareRequest` rather than cookies; cookies travel cross-site only
47
+ * with a `credentials: "include"` init, `SameSite=None; Secure` on the
48
+ * cookie, and `csrf.allowCredentials` on the server.
49
+ * @default "/_server"
50
+ */
51
+ endpoint?: string;
52
+ /**
53
+ * Codec options (extra plugins etc.) for encoding arguments and decoding
54
+ * results — must match the server's. Stored in the shared layer, so
55
+ * `decodeResponse` sees them too. Arguments never carry `Response` or
56
+ * `Request` values, whatever plugins are configured: the server refuses
57
+ * them, and the rich-args encoder rejects the call before sending.
58
+ */
59
+ codec?: JSONCodecOptions;
60
+ /**
61
+ * Sends every server-function request — retries, telemetry, a test
62
+ * double, or an app's own route. Called as `(address, init)`, the
63
+ * address relative to the document as the global one receives it, so
64
+ * `parseServerFunctionActionUrl` reads the id back out for telemetry (a
65
+ * trailing third argument is the transport's own; ignore it). `null`
66
+ * restores the global.
67
+ *
68
+ * ```ts
69
+ * configureServerFunctionsClient({
70
+ * fetch: (address, init) => fetch(rewrite(address), init)
71
+ * });
72
+ * ```
73
+ *
74
+ * Forward `init` — the call's `signal` rides on it, and dropping it voids
75
+ * both the caller's abort and the teardown a live source's `break`
76
+ * performs. Keep the call on the configured `endpoint`'s origin: a send
77
+ * to any other is stamped `Sec-Fetch-Site: cross-site`, and the handler
78
+ * admits it only when its `csrf.origin` allowlist names the page's
79
+ * origin (see `endpoint`). Hand back what the peer answered, unread.
80
+ *
81
+ * A retrying wrapper may re-send a request that got NO response; it must
82
+ * never replay one whose response ended. A response that dies mid-body may
83
+ * have executed (mutations are not idempotent), and reconnecting a live
84
+ * source is the runtime's job — a replay would race it.
85
+ *
86
+ * The wrapper replaces delivery for the requests the runtime chooses to
87
+ * send; the call-to-request mapping itself is not contractual.
88
+ */
89
+ fetch?: ServerFunctionsSend | null;
90
+ /**
91
+ * Runs before every server-function fetch. Return (or mutate and return)
92
+ * the RequestInit the transport will use; `context.meta` is the
93
+ * reference's declaration metadata (e.g. method). For session-dynamic
94
+ * cross-cutting concerns — bearer tokens, tracing headers:
95
+ *
96
+ * ```ts
97
+ * configureServerFunctionsClient({
98
+ * prepareRequest(init) {
99
+ * return {
100
+ * ...init,
101
+ * headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
102
+ * };
103
+ * }
104
+ * });
105
+ * ```
106
+ *
107
+ * Return synchronously when you can: hydration adopts a server-rendered
108
+ * read only if its request is sent in the same tick, so an async hook
109
+ * makes every hydrated read fetch again from the browser.
110
+ */
111
+ prepareRequest?: PrepareRequestHook;
112
+ /**
113
+ * Response-side integration seam — the client mirror of the handler's
114
+ * `transformResult`. `handle(response, ctx)` sees every response before
115
+ * the transport decodes it; returning anything but undefined resolves the
116
+ * call with that value. `capture(info)` runs synchronously at the call
117
+ * site (before any await) and its return arrives as `ctx.context`, so
118
+ * ambient per-call state (e.g. a reactive owner) survives to response
119
+ * time. See `createServerComponentHandler` in frame-transport for the
120
+ * canonical implementation.
121
+ */
122
+ responseHandler?: {
123
+ capture?(info: {
124
+ id: string;
125
+ meta: unknown;
126
+ }): unknown;
127
+ /**
128
+ * `ctx.retry` makes the same call again — the reference, arguments,
129
+ * declared shape and per-call options as dispatched (a `GET`-declared
130
+ * read stays a GET; a caller-supplied `signal` still owns the wire) —
131
+ * for a handler re-asking on its own account (a frames boundary's
132
+ * `reset`, frames-rulings 3.3). Observe tier only: `ctx.startedAt` is
133
+ * when the request was sent (`performance.now()`), so a handler can
134
+ * stamp what it hands out with the request's start
135
+ * (`OBSERVE.attribution.markFlight`).
136
+ */
137
+ handle(response: Response, ctx: {
138
+ id: string;
139
+ meta: unknown;
140
+ args: unknown[];
141
+ context: unknown;
142
+ retry(): Promise<unknown>;
143
+ startedAt?: number;
144
+ }): unknown;
145
+ /**
146
+ * Answer a call before any request is made (t = 0 local answers — see
147
+ * `createServerComponentHandler`). `info.retry` is the call as it would
148
+ * go to the wire, for a handler that answers now and re-asks later.
149
+ */
150
+ intercept?(info: {
151
+ id: string;
152
+ meta: unknown;
153
+ args: unknown[];
154
+ retry(): Promise<unknown>;
155
+ }): unknown;
156
+ /**
157
+ * What a `live` (re)connect of the call resumes from, when the handler
158
+ * shows it: `position` becomes the request's `Last-Event-ID`, `headers`
159
+ * ride beside it (a frames handler's have-list). Asked per connect;
160
+ * `undefined` when the handler holds nothing for the call.
161
+ */
162
+ resume?(info: {
163
+ id: string;
164
+ meta: unknown;
165
+ args: unknown[];
166
+ }): {
167
+ position?: string;
168
+ headers?: Record<string, string>;
169
+ } | undefined;
170
+ /**
171
+ * A `live()` call was made — fired at the call, before its first fetch,
172
+ * so a handler that serves live calls through code it loads on demand
173
+ * (the frames client's live wire tier) can start the load against the
174
+ * request's own latency. Per call, not per connect.
175
+ */
176
+ onLive?(): void;
177
+ };
178
+ /**
179
+ * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
180
+ * always go as plain JSON (no codec in the bundle); anything else throws
181
+ * unless this is set. Installed by `enableRichArguments()` from the
182
+ * rich-args entry — set directly only for custom wire encodings. A
183
+ * `FormData` answer is sent as an upload: the codec output in its `args`
184
+ * field and each file in a `file<index>` part.
185
+ */
186
+ serializeArgs?(args: unknown[]): string | FormData | Promise<string | FormData>;
146
187
  }
147
-
148
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
149
-
150
- /**
151
- * Observes cloned requests and responses without handling them. Subscribe
152
- * from devtools; do not use this to replace `prepareRequest` /
153
- * `responseHandler`. The server entry exports a no-op of the same name so
154
- * isomorphic `@solidjs/web/server-functions` imports resolve.
155
- */
156
- export function observeServerFunctionCalls(
157
- observer: (call: ServerFunctionCall) => void
158
- ): () => void;
159
-
160
- /**
161
- * Declares a server function callable over HTTP GET: calls to the returned
162
- * reference go out as GET requests with the arguments codec-encoded in the
163
- * query string — cacheable by HTTP infrastructure. Cache headers flow
164
- * through the handler's header forwarding
165
- * (`respond(data, { headers: { "cache-control": "max-age=60" } })`).
166
- *
167
- * The declaration rides the metadata channel
168
- * (`getServerFunctionMetadata(fn)?.method === "GET"`) for routers and
169
- * integrations to detect, and the server honors it: GET-declared functions
170
- * accept GET requests in addition to the default POST transport (declaring
171
- * GET grants, it does not revoke); functions that never declared GET answer
172
- * GET requests with 405. Server-side the wrapper is identity-flavored — SSR
173
- * calls stay in-process.
174
- *
175
- * Wrap the reference at its declaration; the compiler round-trips the call
176
- * in both builds:
177
- *
178
- * ```ts
179
- * export const getUser = GET(async (id: string) => {
180
- * "use server";
181
- * return db.users.find(id);
182
- * });
183
- * ```
184
- */
185
- export function GET<A extends readonly any[], R>(
186
- fn: (...args: A) => R
187
- ): ServerFunction<A, Awaited<R>>;
188
-
189
188
  /** Wire-state transitions a live call's iterable can report. */
190
189
  export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
191
-
192
190
  /**
193
191
  * A live call's answer: the source's iterable, plus an optional `onstatus`
194
192
  * side channel for the wire facts the reconnect loop erases from the value
@@ -198,9 +196,68 @@ export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
198
196
  * end was a definite rejection (4xx) failing fast instead of retrying.
199
197
  */
200
198
  export type LiveSource<R> = R & {
201
- onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
199
+ onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
202
200
  };
203
-
201
+ /**
202
+ * Identity of the currently executing server function call — see the
203
+ * server entry. Named here so isomorphic code can import the type from
204
+ * either entry.
205
+ */
206
+ export interface ServerFunctionInvocation {
207
+ id: string;
208
+ }
209
+ /**
210
+ * The url a `GET()` reference's own call requests — the address to preload
211
+ * (`<link rel="preload" as="fetch">`), prefetch, warm in a service worker, or
212
+ * fetch by hand — built the way the transport builds it, so a fetch of it IS
213
+ * the call and matches the reference's later call in every cache that keys
214
+ * on the url. Arguments ride the query as they do on the wire (`?args=`,
215
+ * JSON), and must be JSON-safe here: the codec's encoding is asynchronous,
216
+ * and a url rendered as a value cannot wait for it. Resolved against the
217
+ * configured endpoint. The answer at this url is the transport's (codec
218
+ * shape) — read one by hand with `decodeResponse`.
219
+ *
220
+ * Defined for declared reads only. A reference on the default transport
221
+ * POSTs, and a POST is not described by its url; this throws with a pointer
222
+ * (declare `GET(fn)`, or start the call with `invoke(fn, { priority: "low"
223
+ * }, ...args)`). Also throws when the url would be long enough for the call
224
+ * to fall back to POST — a url you hold is always one the transport would
225
+ * request.
226
+ *
227
+ * ```tsx
228
+ * const getUser = GET(async (id: string) => { "use server"; ... });
229
+ * <link rel="preload" as="fetch" crossorigin href={serverFunctionUrl(getUser, id)} />
230
+ * ```
231
+ *
232
+ * A `live(fn)` reference's call connects at the live address, so that
233
+ * is the url returned for one (`<endpoint>/live/<id>[?args=...]`): a
234
+ * standing event stream of the answer — fetch it by hand (`curl -N`) to
235
+ * watch it; do not preload or prefetch it, which would open a stream
236
+ * nothing reads. Warm a live address by calling the reference (readers of
237
+ * one call share one connection).
238
+ *
239
+ * The form-post address is a different url — `fn.url`, or
240
+ * `serverFunctionActionUrl` for one with bound arguments. The server entry
241
+ * exports the same function so isomorphic imports resolve.
242
+ */
243
+ export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
244
+ export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
245
+ export declare function parseServerFunctionActionUrl(url: string): string | null;
246
+ export declare function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
247
+ export declare function createServerReference(id: string, name?: string, base?: string): ServerFunction;
248
+ export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
249
+ export interface LiveServerFunction<A extends readonly any[] = any[], R = any> {
250
+ (...args: A): LiveSource<R>;
251
+ /** The build-stable function id (stable across the client and server builds). */
252
+ readonly id: string;
253
+ /** URL invoking this function directly over HTTP. */
254
+ readonly url: string;
255
+ }
256
+ /**
257
+ * Declares a live server function whose answer is the same for every
258
+ * viewer: on the client exactly `live(fn)` — the sharing is the server's.
259
+ */
260
+ export declare function broadcast<A extends readonly any[], R>(fn: (...args: A) => R): LiveServerFunction<A, Awaited<R>>;
204
261
  /**
205
262
  * Declares a value-shaped live source: a server function returning an async
206
263
  * iterable whose yields are successive VALUES of one logical query, with the
@@ -211,52 +268,9 @@ export type LiveSource<R> = R & {
211
268
  * first-connect failures reject like a normal call, and `break` aborts the
212
269
  * in-flight request. Live calls are reads and never opt into single-flight
213
270
  * enveloping. Wire state, if wanted, rides the returned iterable's
214
- * `onstatus` hook. Compose with `GET` inside-out: `live(GET(fn))`.
215
- */
216
- export function live<A extends readonly any[], R>(
217
- fn: (...args: A) => R
218
- ): ServerFunction<A, LiveSource<Awaited<R>>>;
219
-
220
- /**
221
- * Compiler ABI — emitted by compiled `"use server"` client output where a
222
- * server function was referenced; produces the fetch-backed callable for
223
- * the function's build-stable id. Development builds pass the function's
224
- * source name as the trailing argument (dev-only metadata seeded on the
225
- * metadata channel; never emitted in production). Not meant for
226
- * hand-written code.
227
- *
228
- * The optional `base` targets calls at that url verbatim instead of the
229
- * configured endpoint — for integrations reconstructing a callable from a
230
- * server-rendered action url (e.g. a router intercepting a form submit whose
231
- * `action="/_server?id=...&args=..."` came off the wire): bound arguments
232
- * stay in the query string, where the server reads them for natural-encoding
233
- * bodies (FormData, urlencoded).
234
- * @internal
235
- */
236
- export function createServerReference(id: string, name?: string, base?: string): ServerFunction;
237
-
238
- /**
239
- * Compiler ABI — only ever referenced by server-mode compiler output;
240
- * throws so a misconfigured build (server transform feeding a client
241
- * bundle) fails loudly instead of with a missing-export error. Not meant
242
- * for hand-written code.
243
- * @internal
244
- */
245
- export function registerServerReference(): never;
246
-
247
- /**
248
- * Identity of the currently executing server function call — see the
249
- * server entry. Named here so isomorphic code can import the type from
250
- * either entry.
251
- */
252
- export interface ServerFunctionInvocation {
253
- id: string;
254
- }
255
-
256
- /**
257
- * Client no-op mirror of the server entry's accessor: there is never a
258
- * server function call in flight on the client, so this always returns
259
- * undefined. Present so `"use server"` modules that import it stay
260
- * import-stable in client builds before dead-code elimination.
271
+ * `onstatus` hook. Implies `GET` (a live source is a read); an explicit
272
+ * `live(GET(fn))` is equivalent.
261
273
  */
262
- export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
274
+ export declare function live<A extends readonly any[], R>(fn: (...args: A) => R): LiveServerFunction<A, Awaited<R>>;
275
+ export declare function registerServerReference(): never;
276
+ export declare function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
@@ -1,3 +1,4 @@
1
+ export declare function setFlashSecret(secret: any): void;
1
2
  /**
2
3
  * The outcome of a call made without the client runtime, as it rides the
3
4
  * flash cookie: what was submitted, where, and what came back. `result` and
@@ -5,34 +6,31 @@
5
6
  * returned one fills `result` — mirroring the split a scripted call sees.
6
7
  */
7
8
  export interface FlashSubmission {
8
- /** The arguments the call was made with (files are dropped). */
9
- input: any[];
10
- /** The call's url: pathname + search of the server function request. */
11
- url: string;
12
- /** The returned value, when the call returned. */
13
- result?: any;
14
- /** The thrown value, when the call threw. */
15
- error?: any;
9
+ /** The arguments the call was made with (files are dropped). */
10
+ input: any[];
11
+ /**
12
+ * The call's url: the UNBOUND function base — the server function
13
+ * request's pathname (`<endpoint>/<id>`), without the `?args=` query a
14
+ * `.with()`-bound form's action carries (or any other query decoration).
15
+ * Matches what the scripted road records as a submission's url, so
16
+ * integrations can match flash and scripted submissions with the same
17
+ * `s.url === fn.base` test; bound arguments arrive in `input` instead,
18
+ * prepended exactly like a scripted call's.
19
+ */
20
+ url: string;
21
+ /** The returned value, when the call returned. */
22
+ result?: any;
23
+ /** The thrown value, when the call threw. */
24
+ error?: any;
25
+ /**
26
+ * Set when the outcome was too large for the cookie's 4 KB ceiling and
27
+ * was degraded to fit (#3137): the input echo is dropped, and `result` /
28
+ * `error` may carry a bounded prefix — or the bare outcome flag `true` —
29
+ * rather than the full value. The submission still says what happened
30
+ * and where; integrations should render it as "succeeded (result too
31
+ * large to display)" rather than replaying the value.
32
+ */
33
+ truncated?: boolean;
16
34
  }
17
-
18
- /**
19
- * Encodes the outcome of a no-JS call as a `Set-Cookie` value, for the
20
- * handler to send with its redirect. `url` identifies which submission the
21
- * outcome belongs to; pass `thrown` when the call threw rather than
22
- * returned.
23
- *
24
- * The payload is JSON inside the cookie: `FormData` and `URLSearchParams`
25
- * arguments are captured as entry pairs and revived on decode, and `File`
26
- * entries are dropped (they cannot ride a cookie). Keep in mind the 4 KB
27
- * cookie budget — outcomes larger than that will not survive the round
28
- * trip.
29
- */
30
- export function encodeFlashCookie(url: string, result: any, input: any[], thrown?: boolean): string;
31
-
32
- /**
33
- * Decodes the flash cookie out of a request's `Cookie` header, for the
34
- * render that follows the redirect. Returns undefined when the cookie is
35
- * absent or unreadable — a malformed cookie never takes down the render,
36
- * and `clearFlashCookie` should be appended regardless.
37
- */
38
- export function decodeFlashCookie(cookieHeader: string | null): FlashSubmission | undefined;
35
+ export declare function encodeFlashCookie(url: string, result: any, input: any[], thrown?: boolean): Promise<string | null>;
36
+ export declare function decodeFlashCookie(cookieHeader: string | null): Promise<FlashSubmission | undefined>;