@solidjs/web 2.0.0-rc.0 → 2.0.0-rc.10

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 (108) hide show
  1. package/README.md +1 -1
  2. package/dist/server.dev.js +4472 -0
  3. package/dist/server.js +1363 -224
  4. package/dist/{server.cjs → server.observe.js} +1563 -424
  5. package/dist/{dev.cjs → web.dev.js} +708 -365
  6. package/dist/web.js +460 -144
  7. package/dist/{dev.js → web.observe.js} +511 -213
  8. package/frames/dist/client.dev.js +464 -72
  9. package/frames/dist/client.js +364 -71
  10. package/frames/dist/{client.dev.cjs → client.observe.js} +487 -134
  11. package/frames/dist/server.dev.js +1713 -0
  12. package/frames/dist/server.js +553 -2495
  13. package/frames/dist/server.observe.js +1713 -0
  14. package/frames/package.json +2 -25
  15. package/package.json +214 -254
  16. package/performance-tracks/dist/performance-tracks.dev.js +678 -0
  17. package/performance-tracks/dist/performance-tracks.js +6 -0
  18. package/performance-tracks/dist/performance-tracks.observe.js +666 -0
  19. package/performance-tracks/package.json +7 -0
  20. package/performance-tracks/types/index.d.ts +67 -0
  21. package/serialization/decode/package.json +2 -15
  22. package/serialization/dist/decode.js +101 -12
  23. package/serialization/dist/serialization.js +112 -20
  24. package/serialization/package.json +2 -15
  25. package/serialization/types/index.d.ts +76 -157
  26. package/serialization/types/serializer-decode.d.ts +149 -112
  27. package/serialization/types/serializer.d.ts +101 -0
  28. package/server-functions/dist/client.dev.js +1364 -0
  29. package/server-functions/dist/client.js +745 -85
  30. package/server-functions/dist/client.observe.js +1343 -0
  31. package/server-functions/dist/server.dev.js +2203 -175
  32. package/server-functions/dist/server.js +2111 -176
  33. package/server-functions/dist/server.observe.js +3043 -0
  34. package/server-functions/package.json +2 -35
  35. package/server-functions/rich-args/package.json +2 -15
  36. package/storage/package.json +2 -15
  37. package/types/client.d.ts +193 -288
  38. package/types/constants.d.ts +20 -0
  39. package/types/cookies.d.ts +32 -84
  40. package/types/diagnostics.d.ts +56 -0
  41. package/types/frames/client.d.ts +1 -1
  42. package/types/frames/frame-client.d.ts +323 -259
  43. package/types/frames/frame-container-plugin.d.ts +72 -0
  44. package/types/frames/frame-sink.d.ts +101 -158
  45. package/types/frames/frame-transport.d.ts +192 -190
  46. package/types/frames/serializer-decode.d.ts +219 -0
  47. package/types/frames/serializer.d.ts +76 -157
  48. package/types/frames/server.d.ts +1 -1
  49. package/types/head.d.ts +19 -0
  50. package/types/index.d.ts +62 -76
  51. package/types/index.server.d.ts +174 -0
  52. package/types/jsx.d.ts +33 -26
  53. package/types/observe.d.ts +358 -0
  54. package/types/reconcile.d.ts +1 -0
  55. package/types/render.d.ts +9 -0
  56. package/types/response.d.ts +75 -150
  57. package/types/serializer-decode.d.ts +149 -112
  58. package/types/serializer.d.ts +76 -157
  59. package/types/server-functions/client.d.ts +202 -174
  60. package/types/server-functions/flash.d.ts +28 -30
  61. package/types/server-functions/registry.d.ts +102 -0
  62. package/types/server-functions/rich-args.d.ts +1 -10
  63. package/types/server-functions/server.d.ts +518 -454
  64. package/types/server-functions/shared.d.ts +366 -425
  65. package/types/server-mock.d.ts +110 -13
  66. package/types/server-observe.d.ts +77 -0
  67. package/types/server.d.ts +425 -425
  68. package/types/trace.d.ts +127 -0
  69. package/LICENSE +0 -21
  70. package/dist/web.cjs +0 -2007
  71. package/frames/dist/client.cjs +0 -1916
  72. package/frames/dist/server.cjs +0 -3667
  73. package/serialization/dist/decode.cjs +0 -110
  74. package/serialization/dist/serialization.cjs +0 -232
  75. package/serialization/types-cjs/index.d.cts +0 -182
  76. package/serialization/types-cjs/package.json +0 -3
  77. package/serialization/types-cjs/serializer-decode.d.cts +0 -182
  78. package/server-functions/dist/client.cjs +0 -646
  79. package/server-functions/dist/rich-args.cjs +0 -11
  80. package/server-functions/dist/server.cjs +0 -1077
  81. package/server-functions/dist/server.dev.cjs +0 -1077
  82. package/storage/dist/storage.cjs +0 -12
  83. package/storage/types-cjs/index.d.cts +0 -28
  84. package/storage/types-cjs/package.json +0 -3
  85. package/types/core.d.ts +0 -6
  86. package/types-cjs/client.d.cts +0 -337
  87. package/types-cjs/cookies.d.cts +0 -93
  88. package/types-cjs/core.d.cts +0 -6
  89. package/types-cjs/frames/client.d.cts +0 -36
  90. package/types-cjs/frames/frame-client.d.cts +0 -338
  91. package/types-cjs/frames/frame-sink.d.cts +0 -194
  92. package/types-cjs/frames/frame-transport.d.cts +0 -222
  93. package/types-cjs/frames/serializer.d.cts +0 -182
  94. package/types-cjs/frames/server.d.cts +0 -52
  95. package/types-cjs/index.d.cts +0 -230
  96. package/types-cjs/jsx-properties.d.cts +0 -93
  97. package/types-cjs/jsx.d.cts +0 -4150
  98. package/types-cjs/package.json +0 -3
  99. package/types-cjs/response.d.cts +0 -174
  100. package/types-cjs/serializer-decode.d.cts +0 -182
  101. package/types-cjs/serializer.d.cts +0 -182
  102. package/types-cjs/server-functions/client.d.cts +0 -201
  103. package/types-cjs/server-functions/flash.d.cts +0 -38
  104. package/types-cjs/server-functions/rich-args.d.cts +0 -10
  105. package/types-cjs/server-functions/server.d.cts +0 -588
  106. package/types-cjs/server-functions/shared.d.cts +0 -523
  107. package/types-cjs/server-mock.d.cts +0 -277
  108. package/types-cjs/server.d.cts +0 -523
@@ -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,148 +22,208 @@ 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>;
62
26
  /** Options for `configureServerFunctionsClient`. */
63
27
  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>;
28
+ /**
29
+ * Mount path the server's HTTP handler answers on. Must match the server
30
+ * configuration — the id travels as the segment after it, and SSR'd
31
+ * reference `url`s (e.g. form actions) and client fetches both derive
32
+ * from it. Prefix it when the app serves from a base path
33
+ * (e.g. `` `${BASE_URL}_server` ``).
34
+ *
35
+ * An absolute URL (`"https://api.example.com/_server"`) targets a handler
36
+ * on another origin — for a client-only build served from elsewhere: a
37
+ * static site, a browser extension, a WebView (`capacitor://localhost`)
38
+ * whose local server owns every path on its own hostname. The call is
39
+ * then cross-origin, and the server admits it only when its
40
+ * `configureServerFunctionsServer({ csrf: { origin } })` allowlist names
41
+ * the page's origin; it answers with the CORS headers the browser needs
42
+ * (`Access-Control-Allow-Origin`, the preflight, the protocol's headers
43
+ * exposed). Authenticate such a client with a bearer token through
44
+ * `prepareRequest` rather than cookies; cookies travel cross-site only
45
+ * with a `credentials: "include"` init, `SameSite=None; Secure` on the
46
+ * cookie, and `csrf.allowCredentials` on the server.
47
+ * @default "/_server"
48
+ */
49
+ endpoint?: string;
50
+ /**
51
+ * Codec options (extra plugins etc.) for encoding arguments and decoding
52
+ * results — must match the server's. Stored in the shared layer, so
53
+ * `decodeResponse` sees them too.
54
+ */
55
+ codec?: JSONCodecOptions;
56
+ /**
57
+ * Sends every server-function request — retries, telemetry, a test
58
+ * double, or an app's own route. Always called as `(address, init)`, the
59
+ * address relative to the document as the global one receives it, so
60
+ * `parseServerFunctionActionUrl` reads the id back out for telemetry. `null`
61
+ * restores the global.
62
+ *
63
+ * ```ts
64
+ * configureServerFunctionsClient({
65
+ * fetch: (address, init) => fetch(rewrite(address), init)
66
+ * });
67
+ * ```
68
+ *
69
+ * Forward `init` — the call's `signal` rides on it, and dropping it voids
70
+ * both the caller's abort and the teardown a live source's `break`
71
+ * performs. Keep the call on the configured `endpoint`'s origin: a send
72
+ * to any other is stamped `Sec-Fetch-Site: cross-site`, and the handler
73
+ * admits it only when its `csrf.origin` allowlist names the page's
74
+ * origin (see `endpoint`). Hand back what the peer answered, unread.
75
+ *
76
+ * A retrying wrapper may re-send a request that got NO response; it must
77
+ * never replay one whose response ended. A response that dies mid-body may
78
+ * have executed (mutations are not idempotent), and reconnecting a live
79
+ * source is the runtime's job — a replay would race it.
80
+ *
81
+ * The wrapper replaces delivery for the requests the runtime chooses to
82
+ * send; the call-to-request mapping itself is not contractual.
83
+ */
84
+ fetch?: ((address: string, init: RequestInit) => Response | Promise<Response>) | null;
85
+ /**
86
+ * Runs before every server-function fetch. Return (or mutate and return)
87
+ * the RequestInit the transport will use; `context.meta` is the
88
+ * reference's declaration metadata (e.g. method). For session-dynamic
89
+ * cross-cutting concerns — bearer tokens, tracing headers:
90
+ *
91
+ * ```ts
92
+ * configureServerFunctionsClient({
93
+ * prepareRequest(init) {
94
+ * return {
95
+ * ...init,
96
+ * headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
97
+ * };
98
+ * }
99
+ * });
100
+ * ```
101
+ */
102
+ prepareRequest?: PrepareRequestHook;
103
+ /**
104
+ * Response-side integration seam — the client mirror of the handler's
105
+ * `transformResult`. `handle(response, ctx)` sees every response before
106
+ * the transport decodes it; returning anything but undefined resolves the
107
+ * call with that value. `capture(info)` runs synchronously at the call
108
+ * site (before any await) and its return arrives as `ctx.context`, so
109
+ * ambient per-call state (e.g. a reactive owner) survives to response
110
+ * time. See `createServerComponentHandler` in frame-transport for the
111
+ * canonical implementation.
112
+ */
113
+ responseHandler?: {
114
+ capture?(info: {
115
+ id: string;
116
+ meta: unknown;
117
+ }): unknown;
118
+ handle(response: Response, ctx: {
119
+ id: string;
120
+ meta: unknown;
121
+ args: unknown[];
122
+ context: unknown;
123
+ }): unknown;
124
+ /**
125
+ * What a `live` (re)connect of the call resumes from, when the handler
126
+ * shows it: `position` becomes the request's `Last-Event-ID`, `headers`
127
+ * ride beside it (a frames handler's have-list). Asked per connect;
128
+ * `undefined` when the handler holds nothing for the call.
129
+ */
130
+ resume?(info: {
131
+ id: string;
132
+ meta: unknown;
133
+ args: unknown[];
134
+ }): {
135
+ position?: string;
136
+ headers?: Record<string, string>;
137
+ } | undefined;
138
+ };
139
+ /**
140
+ * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
141
+ * always go as plain JSON (no codec in the bundle); anything else throws
142
+ * unless this is set. Installed by `enableRichArguments()` from the
143
+ * rich-args entry — set directly only for custom wire encodings.
144
+ */
145
+ serializeArgs?(args: unknown[]): string | Promise<string>;
120
146
  }
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
-
147
+ /** Wire-state transitions a live call's iterable can report. */
148
+ export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
130
149
  /**
131
- * Declares a server function callable over HTTP GET: calls to the returned
132
- * reference go out as GET requests with the arguments codec-encoded in the
133
- * query string — cacheable by HTTP infrastructure. Cache headers flow
134
- * through the handler's header forwarding
135
- * (`respond(data, { headers: { "cache-control": "max-age=60" } })`).
136
- *
137
- * The declaration rides the metadata channel
138
- * (`getServerFunctionMetadata(fn)?.method === "GET"`) for routers and
139
- * integrations to detect, and the server honors it: GET-declared functions
140
- * accept GET requests in addition to the default POST transport (declaring
141
- * GET grants, it does not revoke); functions that never declared GET answer
142
- * GET requests with 405. Server-side the wrapper is identity-flavored — SSR
143
- * calls stay in-process.
144
- *
145
- * Wrap the reference at its declaration; the compiler round-trips the call
146
- * in both builds:
147
- *
148
- * ```ts
149
- * export const getUser = GET(async (id: string) => {
150
- * "use server";
151
- * return db.users.find(id);
152
- * });
153
- * ```
154
- */
155
- export function GET<A extends readonly any[], R>(
156
- fn: (...args: A) => R
157
- ): ServerFunction<A, Awaited<R>>;
158
-
159
- /**
160
- * Compiler ABI — emitted by compiled `"use server"` client output where a
161
- * server function was referenced; produces the fetch-backed callable for
162
- * the function's build-stable id. Development builds pass the function's
163
- * source name as the trailing argument (dev-only metadata seeded on the
164
- * metadata channel; never emitted in production). Not meant for
165
- * hand-written code.
166
- *
167
- * The optional `base` targets calls at that url verbatim instead of the
168
- * configured endpoint — for integrations reconstructing a callable from a
169
- * server-rendered action url (e.g. a router intercepting a form submit whose
170
- * `action="/_server?id=...&args=..."` came off the wire): bound arguments
171
- * stay in the query string, where the server reads them for natural-encoding
172
- * bodies (FormData, urlencoded).
173
- * @internal
150
+ * A live call's answer: the source's iterable, plus an optional `onstatus`
151
+ * side channel for the wire facts the reconnect loop erases from the value
152
+ * stream — `"connected"` on each successful (re)connect, `"reconnecting"`
153
+ * (with the error) on each transient post-connect death, `"closed"` when
154
+ * the source completes or the consumer ends it — with the error when the
155
+ * end was a definite rejection (4xx) failing fast instead of retrying.
174
156
  */
175
- export function createServerReference(id: string, name?: string, base?: string): ServerFunction;
176
-
177
- /**
178
- * Compiler ABI — only ever referenced by server-mode compiler output;
179
- * throws so a misconfigured build (server transform feeding a client
180
- * bundle) fails loudly instead of with a missing-export error. Not meant
181
- * for hand-written code.
182
- * @internal
183
- */
184
- export function registerServerReference(): never;
185
-
157
+ export type LiveSource<R> = R & {
158
+ onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
159
+ };
186
160
  /**
187
161
  * Identity of the currently executing server function call — see the
188
162
  * server entry. Named here so isomorphic code can import the type from
189
163
  * either entry.
190
164
  */
191
165
  export interface ServerFunctionInvocation {
192
- id: string;
166
+ id: string;
167
+ }
168
+ /**
169
+ * The url a `GET()` reference's own call requests — the address to preload
170
+ * (`<link rel="preload" as="fetch">`), prefetch, warm in a service worker, or
171
+ * fetch by hand — built the way the transport builds it, so a fetch of it IS
172
+ * the call and matches the reference's later call in every cache that keys
173
+ * on the url. Arguments ride the query as they do on the wire (`?args=`,
174
+ * JSON), and must be JSON-safe here: the codec's encoding is asynchronous,
175
+ * and a url rendered as a value cannot wait for it. Resolved against the
176
+ * configured endpoint. The answer at this url is the transport's (codec
177
+ * shape) — read one by hand with `decodeResponse`.
178
+ *
179
+ * Defined for declared reads only. A reference on the default transport
180
+ * POSTs, and a POST is not described by its url; this throws with a pointer
181
+ * (declare `GET(fn)`, or start the call with `invoke(fn, { priority: "low"
182
+ * }, ...args)`). Also throws when the url would be long enough for the call
183
+ * to fall back to POST — a url you hold is always one the transport would
184
+ * request.
185
+ *
186
+ * ```tsx
187
+ * const getUser = GET(async (id: string) => { "use server"; ... });
188
+ * <link rel="preload" as="fetch" crossorigin href={serverFunctionUrl(getUser, id)} />
189
+ * ```
190
+ *
191
+ * A `live(GET(fn))` reference's call connects at the live address, so that
192
+ * is the url returned for one (`<endpoint>/live/<id>[?args=...]`): a
193
+ * standing event stream of the answer — fetch it by hand (`curl -N`) to
194
+ * watch it; do not preload or prefetch it, which would open a stream
195
+ * nothing reads. Warm a live address by calling the reference (readers of
196
+ * one call share one connection).
197
+ *
198
+ * The form-post address is a different url — `fn.url`, or
199
+ * `serverFunctionActionUrl` for one with bound arguments. The server entry
200
+ * exports the same function so isomorphic imports resolve.
201
+ */
202
+ export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
203
+ export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
204
+ export declare function parseServerFunctionActionUrl(url: string): string | null;
205
+ export declare function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
206
+ export declare function createServerReference(id: string, name?: string, base?: string): ServerFunction;
207
+ export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
208
+ export interface LiveServerFunction<A extends readonly any[] = any[], R = any> {
209
+ (...args: A): LiveSource<R>;
210
+ /** The build-stable function id (stable across the client and server builds). */
211
+ readonly id: string;
212
+ /** URL invoking this function directly over HTTP. */
213
+ readonly url: string;
193
214
  }
194
-
195
215
  /**
196
- * Client no-op mirror of the server entry's accessor: there is never a
197
- * server function call in flight on the client, so this always returns
198
- * undefined. Present so `"use server"` modules that import it stay
199
- * import-stable in client builds before dead-code elimination.
216
+ * Declares a value-shaped live source: a server function returning an async
217
+ * iterable whose yields are successive VALUES of one logical query, with the
218
+ * contract that the source re-yields current state on every invocation.
219
+ * Calls to the returned reference produce an iterable that survives the
220
+ * connection — post-connect deaths re-invoke with exponential backoff
221
+ * (reset per healthy value, woken early by connectivity returning),
222
+ * first-connect failures reject like a normal call, and `break` aborts the
223
+ * in-flight request. Live calls are reads and never opt into single-flight
224
+ * enveloping. Wire state, if wanted, rides the returned iterable's
225
+ * `onstatus` hook. Compose with `GET` inside-out: `live(GET(fn))`.
200
226
  */
201
- export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
227
+ export declare function live<A extends readonly any[], R>(fn: (...args: A) => R): LiveServerFunction<A, Awaited<R>>;
228
+ export declare function registerServerReference(): never;
229
+ 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>;
@@ -0,0 +1,102 @@
1
+ export type { InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, ServerFunctionRPC } from "./shared.js";
2
+ import type { InvokeOptions } from "./shared.js";
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
+ export declare const LIVE_RESUME_FROM: unique symbol;
87
+ export declare const LIVE_LOCAL: unique symbol;
88
+ /**
89
+ * Fills the RPC seam. Called by the transport halves (client fetch RPC,
90
+ * server in-process dispatch) when the first server function reference is
91
+ * created; first write wins — both halves register equivalent surfaces, and
92
+ * a per-build half never coexists with the other build's.
93
+ * @internal
94
+ */
95
+ export declare function provideServerFunctionRPC(rpc: any): void;
96
+ /**
97
+ * The registered RPC surface, or undefined when no server function exists
98
+ * in this build's graph. Integration plumbing (routers): gate every use of
99
+ * the transport/codec behind this read instead of importing it.
100
+ * @internal
101
+ */
102
+ export declare function getServerFunctionRPC(): any;
@@ -1,10 +1 @@
1
- /**
2
- * Opt-in codec encoding for server-function ARGUMENTS. By default the client
3
- * sends argument lists as plain JSON (no serializer in the bundle) and
4
- * throws on values JSON can't carry faithfully. Call once at startup to
5
- * send Dates, Maps, Sets, typed arrays, cyclic structures, etc. through the
6
- * codec — at the cost of the serializer's write half (~5 KB gz on top of
7
- * the decode half responses already need). The handler accepts both
8
- * encodings unconditionally.
9
- */
10
- export function enableRichArguments(): void;
1
+ export declare function enableRichArguments(): void;