@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,3 +0,0 @@
1
- {
2
- "type": "commonjs"
3
- }
@@ -1,3 +0,0 @@
1
- export declare function rowProof<T extends Function>(fn: T): T;
2
- export declare const driveList: (parent: Node, listFn: any, marker?: Node, lateClassic?: () => void) => boolean;
3
- export declare const patchDriver: (subject: any, body: any) => void;
@@ -1 +0,0 @@
1
- export default function reconcileArrays(parentNode: Node, a: Node[], b: Node[], marker?: Node | null): void;
@@ -1,4 +0,0 @@
1
- export declare function effect<T>(fn: (prev?: T) => T, effectFn: (value: T, prev?: T) => void, options?: {
2
- scope?: boolean;
3
- }): void;
4
- export declare function memo<T>(fn: () => T): () => T;
@@ -1,81 +0,0 @@
1
- /**
2
- * Envelope pairing HTTP metadata with a value. Produced by `respond()` and
3
- * by server-function `transformResult` implementations (e.g. single-flight
4
- * payloads); the HTTP handler forwards `response`'s headers and
5
- * (non-redirect) status and encodes `value` as the body through the codec,
6
- * while client-only integrations read `value` directly — no reparse.
7
- */
8
- export interface ResponseEnvelope<T = unknown> {
9
- response: Response | undefined;
10
- value: T;
11
- }
12
- export declare const ResponseEnvelope: {
13
- new <T>(response: Response | undefined, value: T): ResponseEnvelope<T>;
14
- };
15
- /** Whether `value` is a `ResponseEnvelope` (robust across module copies). */
16
- export declare function isResponseEnvelope(value: unknown): value is ResponseEnvelope;
17
- export declare const HREF: unique symbol;
18
- export interface Href {
19
- /**
20
- * The brand doubles as a channel: when the slot holds a string it is the
21
- * value's *logical* path — the routable pathname before an integration's
22
- * display rendering (eg. a hash router's `#` prefix). `redirect()` prefers
23
- * it over coercion so Location headers carry routable paths; `toString()`
24
- * remains the display href for the DOM. `true` brands a value whose
25
- * string form is already logical.
26
- */
27
- [HREF]: true | string;
28
- toString(): string;
29
- }
30
- /** Whether `value` is an `Href`-branded URL-bearing value. */
31
- export declare function isHref(value: unknown): value is Href;
32
- export declare const SAFE_ERROR: unique symbol;
33
- /**
34
- * Marks `error` as safe to serialize to the client verbatim, opting it out
35
- * of production error sanitization (see `handleServerFunctionRequest`). Use
36
- * for errors whose message/properties are intentional client-facing content.
37
- * Returns the same value for convenient `throw markSafeError(new Error(...))`.
38
- */
39
- export declare function markSafeError<E>(error: E): E;
40
- /** Whether `value` is branded safe to serialize (robust across module copies). */
41
- export declare function isSafeError(value: unknown): value is Error;
42
- /**
43
- * Response header naming the cache keys a mutation invalidated, comma
44
- * separated. Set by the helpers below and read by the client transport and
45
- * by integrations; core never inspects the keys, so how they are matched
46
- * (prefixes, exact names, namespaces) is the integration's business.
47
- */
48
- export declare const REVALIDATE_HEADER = "X-Revalidate";
49
- /** `ResponseInit` accepted by the response helpers, plus `revalidate`. */
50
- export interface ResponseHelperInit extends ResponseInit {
51
- revalidate?: string | string[];
52
- }
53
- /** @internal */
54
- export declare const RESPONSE_HEADER_VALUE_LIMIT = 4096;
55
- /**
56
- * Response redirecting to `url` (default 302). `revalidate` names the
57
- * cache keys the mutation invalidated.
58
- */
59
- export declare function redirect(url: string | Href, init?: number | ResponseHelperInit): Response;
60
- /**
61
- * Empty response requesting revalidation of the named cache keys (all of
62
- * them when omitted).
63
- */
64
- export declare function reload(init?: ResponseHelperInit): Response;
65
- /**
66
- * Statuses HTTP forbids a body on — the `Response` constructor enforces it
67
- * by throwing on ANY body, `JSON.stringify(undefined)`'s `"undefined"`
68
- * included. Shared with the server-function encoder, which answers void
69
- * results on these statuses with a real null-body response and reports
70
- * value-carrying ones as authoring errors (#3095).
71
- * @internal
72
- */
73
- export declare const NULL_BODY_STATUSES: ReadonlySet<number>;
74
- /**
75
- * A value paired with response metadata (status, headers, `revalidate`) —
76
- * for the things a naked return can't express. Progressive enhancement
77
- * stays invisible: the carried response holds a plain JSON body so
78
- * consumers without the client runtime (no-JS form posts, direct HTTP)
79
- * get real JSON, while integrations read `value` — no reparse.
80
- */
81
- export declare function respond<T>(value: T, init?: ResponseHelperInit): ResponseEnvelope<T>;
@@ -1,172 +0,0 @@
1
- /**
2
- * Seroval's node shape — the intermediate representation `serializeJSON`
3
- * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
4
- * Declared by hand like the plugin types below (same rationale): the
5
- * observable envelope — a numeric type tag, an optional reference id —
6
- * with the rest owned by the codec. Real seroval nodes satisfy it; treat
7
- * it as an opaque token.
8
- *
9
- * Integration-facing; may change (see the entry banner).
10
- */
11
- export interface SerovalNode {
12
- /** Node type tag (seroval-internal enum). */
13
- t: number;
14
- /** Reference id, when the node participates in cross-referencing. */
15
- i?: number | undefined;
16
- [key: string]: unknown;
17
- }
18
- /** Per-plugin bookkeeping seroval hands each plugin callback. */
19
- export interface PluginData {
20
- id: number;
21
- }
22
- /**
23
- * The shape of a plugin's parsed payload: a map of `SerovalNode`s produced
24
- * by the parse contexts, consumed by `serialize`/`deserialize`.
25
- */
26
- export type PluginInfo = {
27
- [key: string]: SerovalNode;
28
- };
29
- /** Parse context for `parse.sync`: turns child values into nodes. */
30
- export interface SyncParsePluginContext {
31
- parse<T>(current: T): SerovalNode;
32
- }
33
- /** Parse context for `parse.async`: like sync, but child parses await. */
34
- export interface AsyncParsePluginContext {
35
- parse<T>(current: T): Promise<SerovalNode>;
36
- }
37
- /**
38
- * Parse context for `parse.stream`: sync parsing plus the streaming
39
- * lifecycle (pending-state tracking, late node emission, cleanup).
40
- */
41
- export interface StreamParsePluginContext {
42
- parse<T>(current: T): SerovalNode;
43
- parseWithError<T>(current: T): SerovalNode | undefined;
44
- isAlive(): boolean;
45
- pushPendingState(): void;
46
- popPendingState(): void;
47
- onParse(node: SerovalNode): void;
48
- onError(error: unknown): void;
49
- addCleanup(callback: () => void): void;
50
- }
51
- /** Serialize context: renders child nodes to JS source. */
52
- export interface SerializePluginContext {
53
- serialize(node: SerovalNode): string;
54
- }
55
- /** Deserialize context: revives child nodes to runtime values. */
56
- export interface DeserializePluginContext {
57
- deserialize<T>(node: SerovalNode): T;
58
- }
59
- /**
60
- * A Seroval plugin usable with the web serializers — teaches the codec how
61
- * to encode/decode a custom value type (`Value` is the value it matches,
62
- * `Info` its parsed payload). Supply matching plugins on both peers of a
63
- * transport. Bare `SerializerPlugin` (both parameters defaulted to `any`)
64
- * is the list-element type every `plugins` option accepts.
65
- *
66
- * Integration-facing; may change (see the entry banner).
67
- */
68
- export interface SerializerPlugin<Value = any, Info extends PluginInfo = any> {
69
- /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
70
- tag: string;
71
- /** Dependency plugins, resolved ahead of this one. */
72
- extends?: SerializerPlugin[];
73
- /** Whether `value` is this plugin's to encode. */
74
- test(value: unknown): boolean;
75
- /** Parsing modes — provide the ones the transports you target use. */
76
- parse: {
77
- sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
78
- async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
79
- stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
80
- };
81
- /** Renders the parsed payload as JS source (script-injection form). */
82
- serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
83
- /** Revives the parsed payload back into the runtime value. */
84
- deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
85
- }
86
- /**
87
- * Options shared by both halves of the JSON codec. All of them must match
88
- * on the serializing and deserializing peer or payloads will not
89
- * round-trip — for server functions, set them once through the
90
- * client/server `codec` config option.
91
- *
92
- * Integration-facing; may change (see the entry banner).
93
- */
94
- export interface JSONCodecOptions {
95
- /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
96
- plugins?: SerializerPlugin[];
97
- /**
98
- * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
99
- * (payloads may come from an untrusted peer). Must match on both peers.
100
- * Outside development, the encoding side additionally strips
101
- * `Error.prototype.stack` on top of any override — serialized stacks leak
102
- * server paths to the client. Decoding stays permissive, so payloads from
103
- * a development peer still round-trip.
104
- */
105
- disabledFeatures?: number;
106
- /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
107
- depthLimit?: number;
108
- /**
109
- * Whether serialized `Error`s carry their `.stack` — server file paths,
110
- * internal function names, the shape of the deployment — to the peer.
111
- * Defaults to `NODE_ENV === "development"`, but that signal describes the
112
- * PROCESS, not the artifact: a production build running with
113
- * `NODE_ENV=development` (a base image, a stray dotenv) ships stacks to
114
- * the wire — including for errors marked safe with `markSafeError`, whose
115
- * stacks traverse application code (#3152). Set `false` to pin production
116
- * disclosure regardless of the ambient variable. Encode-side only; the
117
- * decode side is always permissive, so it need not match peers.
118
- */
119
- serializeErrorStacks?: boolean;
120
- }
121
- /**
122
- * A resident, response-scoped decode table over the keyed JSON codec: apply
123
- * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
124
- * `resolve`. The frames client host wires one per response
125
- * (`applyData: c => table.apply(c)`).
126
- *
127
- * Integration-facing; may change (see the entry banner). This serialization
128
- * entry is the single home of the data table — the frames client consumes
129
- * it internally rather than re-exporting it.
130
- */
131
- export interface JSONDataTable {
132
- apply(chunk: {
133
- key?: string;
134
- node?: unknown;
135
- initial?: boolean;
136
- }): void;
137
- resolve<T = unknown>(ref: {
138
- $ref: string;
139
- }): T;
140
- }
141
- /**
142
- * Baseline plugin set for serializing web-platform values. Shared by the
143
- * hydration serializer and any consumer building its own serializer (e.g.
144
- * server function transports). Plugin objects carry both their serialize
145
- * and deserialize halves, so the set lives on the decode side and the
146
- * encode module composes over it.
147
- */
148
- export declare const DEFAULT_WEB_PLUGINS: any; /**
149
- * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
150
- * first so they can shadow a default for values both would match. Returns a
151
- * fresh array; the defaults are never mutated. Useful when handing a full
152
- * plugin list to another serialization layer.
153
- *
154
- * Integration-facing; may change (see the entry banner).
155
- */
156
- export declare function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
157
- export declare function resolveCodecOptions({ plugins, disabledFeatures, depthLimit, serializeErrorStacks }?: JSONCodecOptions): {
158
- plugins: SerializerPlugin<any, any>[];
159
- disabledFeatures: any;
160
- depthLimit: number;
161
- serializeErrorStacks: boolean;
162
- }; /**
163
- * Creates the decoding counterpart of `serializeJSON`. Cross-references
164
- * between chunks resolve through state shared across calls, so all chunks
165
- * from one stream must go through the same deserializer instance. The first
166
- * chunk's return value is the decoded source value; feeding later chunks
167
- * settles the async values referenced inside it.
168
- *
169
- * Integration-facing; may change (see the entry banner).
170
- */
171
- export declare function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
172
- export declare function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;
@@ -1,101 +0,0 @@
1
- import { Serializer } from "seroval";
2
- import type { JSONCodecOptions, PluginInfo, SerializerPlugin, SerovalNode } from "./serializer-decode.cjs";
3
- export { DEFAULT_WEB_PLUGINS, createJSONDataTable, createJSONDeserializer, resolveSerializerPlugins } from "./serializer-decode.cjs";
4
- export type * from "./serializer-decode.cjs";
5
- /**
6
- * Options for `createSerializer`.
7
- *
8
- * Integration-facing; may change (see the entry banner).
9
- */
10
- export interface WebSerializerOptions {
11
- /** Name of the global object the emitted scripts write resolved values into. */
12
- globalIdentifier: string;
13
- /** Cross-reference scope id, for isolating multiple streams on one page. */
14
- scopeId?: string;
15
- /**
16
- * Seroval feature bitflags to exclude from output. Defaults to disabling
17
- * post-ES2017 features (AggregateError, BigInt typed arrays). Outside
18
- * development, `Error.prototype.stack` is additionally stripped on top of
19
- * any override — serialized stacks leak server paths to the client.
20
- */
21
- disabledFeatures?: number;
22
- /**
23
- * Whether serialized `Error`s carry their `.stack`. Defaults to
24
- * `NODE_ENV === "development"`; set `false` to pin production disclosure
25
- * to the deployment rather than the ambient variable (#3152 — see
26
- * `JSONCodecOptions.serializeErrorStacks`).
27
- */
28
- serializeErrorStacks?: boolean;
29
- /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
30
- plugins?: SerializerPlugin[];
31
- /** Receives each emitted script chunk. */
32
- onData: (result: string) => void;
33
- onError?: (error: unknown) => void;
34
- /** Fires once all async values have settled. */
35
- onDone?: () => void;
36
- }
37
- /**
38
- * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
39
- * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
40
- * @internal
41
- */
42
- export type HydrationSerializerOptions = Omit<WebSerializerOptions, "globalIdentifier" | "disabledFeatures">;
43
- /**
44
- * Options for `serializeJSON`.
45
- *
46
- * Integration-facing; may change (see the entry banner).
47
- */
48
- export interface JSONSerializeOptions extends JSONCodecOptions {
49
- /**
50
- * Receives each serialized node; `initial` is true for the first chunk
51
- * (the source value itself). Async values produce additional chunks as
52
- * they resolve.
53
- */
54
- onParse: (node: SerovalNode, initial: boolean) => void;
55
- onError?: (error: unknown) => void;
56
- /** Fires once all async values have settled. */
57
- onDone?: () => void;
58
- }
59
- /** Options for `createJSONSerializer`. */
60
- export interface JSONSerializerOptions extends JSONCodecOptions {
61
- /**
62
- * Receives each keyed record — `initial` is true for a key's first node
63
- * (the written value itself); async values patch through later records
64
- * under the same key. The decoding peer is `createJSONDataTable`.
65
- */
66
- onData: (record: {
67
- key: string;
68
- node: SerovalNode;
69
- initial: boolean;
70
- }) => void;
71
- onError?: (error: unknown) => void;
72
- /** Fires once `flush()` has been called and every pending value settled. */
73
- onDone?: () => void;
74
- }
75
- export declare const createPlugin: <Value, Info extends PluginInfo>(plugin: SerializerPlugin<Value, Info>) => SerializerPlugin<Value, Info>;
76
- export interface OpaqueReference<V = unknown, R = undefined> {
77
- readonly value: V;
78
- readonly replacement?: R;
79
- }
80
- export declare const OpaqueReference: {
81
- new <V, R = undefined>(value: V, replacement?: R): OpaqueReference<V, R>;
82
- };
83
- /**
84
- * Creates a streaming Seroval serializer preconfigured with the web plugin
85
- * set and the default feature policy. Emits JavaScript chunks (through
86
- * `onData`) that reconstruct the values under `globalIdentifier` when
87
- * evaluated — the script-injection form of serialization renderers build
88
- * on. For a JSON-based wire codec (no eval on the receiving side), use
89
- * `serializeJSON` / `createJSONDeserializer` instead.
90
- *
91
- * Integration-facing; may change (see the entry banner).
92
- */
93
- export declare function createSerializer(options: WebSerializerOptions): Serializer;
94
- export declare function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
95
- export declare function getLocalHeaderScript(id?: string): string;
96
- export declare function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
97
- export declare function createJSONSerializer(options: JSONSerializerOptions): {
98
- write(key: string, value: unknown): void;
99
- flush(): void;
100
- close(): void;
101
- };
@@ -1,184 +0,0 @@
1
- import type { ServerFunction, ServerFunctionMetadata } from "./shared.cjs";
2
- export { ChunkReader, ERROR_HEADER, FLASH_COOKIE, INSTANCE_HEADER, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, createChunk, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, deserializeStream, encodeErrorHeaderValue, frameAddress, getFlightDataConsumer, getFlightDataSourceIds, getServerFunctionMetadata, getServerFunctionsCodec, hasFlashCookie, invoke, isServerFunction, serializeString, subscribeFlightData, withMeta } from "./shared.cjs";
3
- export { REVALIDATE_HEADER } from "../response.cjs";
4
- import { JSONCodecOptions } from "../serializer-decode.cjs";
5
- export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.cjs";
6
- /** The context `prepareRequest` receives alongside the outgoing RequestInit. */
7
- export interface PrepareRequestContext {
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;
15
- }
16
- /**
17
- * Client-side session-dynamic transport hook: runs before every
18
- * server-function fetch. Return (or mutate and return) the RequestInit the
19
- * transport will use — the hook sees the final init, transport headers
20
- * included. The motivating case is dynamic credentials that rotate during
21
- * a session and apply uniformly to every call (OAuth bearer tokens); it is
22
- * the client-side symmetric of the server handler hooks. Single hook, not
23
- * a chain — compose by wrapping functions in userland.
24
- */
25
- export type PrepareRequestHook = (init: RequestInit, context: PrepareRequestContext) => RequestInit | Promise<RequestInit>;
26
- /** Options for `configureServerFunctionsClient`. */
27
- export interface ServerFunctionsClientConfig {
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
- * @default "/_server"
35
- */
36
- endpoint?: string;
37
- /**
38
- * Codec options (extra plugins etc.) for encoding arguments and decoding
39
- * results — must match the server's. Stored in the shared layer, so
40
- * `decodeResponse` sees them too.
41
- */
42
- codec?: JSONCodecOptions;
43
- /**
44
- * Sends every server-function request — retries, telemetry, a test
45
- * double, or an app's own route. Always called as `(address, init)`, the
46
- * address relative to the document as the global one receives it, so
47
- * `parseServerFunctionUrl` reads the id back out for telemetry. `null`
48
- * restores the global.
49
- *
50
- * ```ts
51
- * configureServerFunctionsClient({
52
- * fetch: (address, init) => fetch(rewrite(address), init)
53
- * });
54
- * ```
55
- *
56
- * Forward `init` — the call's `signal` rides on it, and dropping it voids
57
- * both the caller's abort and the teardown a live source's `break`
58
- * performs. Keep the call same-origin, since a cross-origin send is
59
- * stamped `Sec-Fetch-Site: cross-site` and the handler's origin gate
60
- * refuses it, and hand back what the peer answered, unread.
61
- *
62
- * A retrying wrapper may re-send a request that got NO response; it must
63
- * never replay one whose response ended. A response that dies mid-body may
64
- * have executed (mutations are not idempotent), and reconnecting a live
65
- * source is the runtime's job — a replay would race it.
66
- *
67
- * The wrapper replaces delivery for the requests the runtime chooses to
68
- * send; the call-to-request mapping itself is not contractual.
69
- */
70
- fetch?: ((address: string, init: RequestInit) => Response | Promise<Response>) | null;
71
- /**
72
- * Runs before every server-function fetch. Return (or mutate and return)
73
- * the RequestInit the transport will use; `context.meta` is the
74
- * reference's declaration metadata (e.g. method). For session-dynamic
75
- * cross-cutting concerns — bearer tokens, tracing headers:
76
- *
77
- * ```ts
78
- * configureServerFunctionsClient({
79
- * prepareRequest(init) {
80
- * return {
81
- * ...init,
82
- * headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
83
- * };
84
- * }
85
- * });
86
- * ```
87
- */
88
- prepareRequest?: PrepareRequestHook;
89
- /**
90
- * Response-side integration seam — the client mirror of the handler's
91
- * `transformResult`. `handle(response, ctx)` sees every response before
92
- * the transport decodes it; returning anything but undefined resolves the
93
- * call with that value. `capture(info)` runs synchronously at the call
94
- * site (before any await) and its return arrives as `ctx.context`, so
95
- * ambient per-call state (e.g. a reactive owner) survives to response
96
- * time. See `createServerComponentHandler` in frame-transport for the
97
- * canonical implementation.
98
- */
99
- responseHandler?: {
100
- capture?(info: {
101
- id: string;
102
- meta: unknown;
103
- }): unknown;
104
- handle(response: Response, ctx: {
105
- id: string;
106
- meta: unknown;
107
- args: unknown[];
108
- context: unknown;
109
- }): unknown;
110
- };
111
- /**
112
- * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
113
- * always go as plain JSON (no codec in the bundle); anything else throws
114
- * unless this is set. Installed by `enableRichArguments()` from the
115
- * rich-args entry — set directly only for custom wire encodings.
116
- */
117
- serializeArgs?(args: unknown[]): string | Promise<string>;
118
- }
119
- export interface ServerFunctionRequestCall {
120
- type: "request";
121
- id: string;
122
- instance: string;
123
- request: Request;
124
- meta: ServerFunctionMetadata | undefined;
125
- time: number;
126
- }
127
- export interface ServerFunctionResponseCall {
128
- type: "response";
129
- id: string;
130
- instance: string;
131
- response: Response;
132
- meta: ServerFunctionMetadata | undefined;
133
- time: number;
134
- }
135
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
136
- /** Wire-state transitions a live call's iterable can report. */
137
- export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
138
- /**
139
- * A live call's answer: the source's iterable, plus an optional `onstatus`
140
- * side channel for the wire facts the reconnect loop erases from the value
141
- * stream — `"connected"` on each successful (re)connect, `"reconnecting"`
142
- * (with the error) on each transient post-connect death, `"closed"` when
143
- * the source completes or the consumer ends it — with the error when the
144
- * end was a definite rejection (4xx) failing fast instead of retrying.
145
- */
146
- export type LiveSource<R> = R & {
147
- onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
148
- };
149
- /**
150
- * Identity of the currently executing server function call — see the
151
- * server entry. Named here so isomorphic code can import the type from
152
- * either entry.
153
- */
154
- export interface ServerFunctionInvocation {
155
- id: string;
156
- }
157
- export declare function observeServerFunctionCalls(observer: (call: ServerFunctionCall) => void): () => void;
158
- export declare function serverFunctionUrl(id: string, boundArgs?: readonly unknown[]): string;
159
- export declare function parseServerFunctionUrl(url: string): string | null;
160
- export declare function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
161
- export declare function createServerReference(id: string, name?: string, base?: string): ServerFunction;
162
- export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
163
- export interface LiveServerFunction<A extends readonly any[] = any[], R = any> {
164
- (...args: A): LiveSource<R>;
165
- /** The build-stable function id (stable across the client and server builds). */
166
- readonly id: string;
167
- /** URL invoking this function directly over HTTP. */
168
- readonly url: string;
169
- }
170
- /**
171
- * Declares a value-shaped live source: a server function returning an async
172
- * iterable whose yields are successive VALUES of one logical query, with the
173
- * contract that the source re-yields current state on every invocation.
174
- * Calls to the returned reference produce an iterable that survives the
175
- * connection — post-connect deaths re-invoke with exponential backoff
176
- * (reset per healthy value, woken early by connectivity returning),
177
- * first-connect failures reject like a normal call, and `break` aborts the
178
- * in-flight request. Live calls are reads and never opt into single-flight
179
- * enveloping. Wire state, if wanted, rides the returned iterable's
180
- * `onstatus` hook. Compose with `GET` inside-out: `live(GET(fn))`.
181
- */
182
- export declare function live<A extends readonly any[], R>(fn: (...args: A) => R): LiveServerFunction<A, Awaited<R>>;
183
- export declare function registerServerReference(): never;
184
- export declare function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
@@ -1,27 +0,0 @@
1
- /**
2
- * The outcome of a call made without the client runtime, as it rides the
3
- * flash cookie: what was submitted, where, and what came back. `result` and
4
- * `error` are mutually exclusive — a thrown outcome fills `error`, a
5
- * returned one fills `result` — mirroring the split a scripted call sees.
6
- */
7
- 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;
16
- /**
17
- * Set when the outcome was too large for the cookie's 4 KB ceiling and
18
- * was degraded to fit (#3137): the input echo is dropped, and `result` /
19
- * `error` may carry a bounded prefix — or the bare outcome flag `true` —
20
- * rather than the full value. The submission still says what happened
21
- * and where; integrations should render it as "succeeded (result too
22
- * large to display)" rather than replaying the value.
23
- */
24
- truncated?: boolean;
25
- }
26
- export declare function encodeFlashCookie(url: string, result: any, input: any[], thrown?: boolean): string;
27
- export declare function decodeFlashCookie(cookieHeader: string | null): FlashSubmission | undefined;