@barqjs/start 0.0.0-stage → 0.2.0-next.0
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.
- package/LICENSE +21 -0
- package/README.md +791 -2
- package/dist/client-BHyIiYxt.js +1527 -0
- package/dist/client-BHyIiYxt.js.map +1 -0
- package/dist/client-DHCV7yvQ.d.ts +440 -0
- package/dist/client-DHCV7yvQ.d.ts.map +1 -0
- package/dist/client.d.ts +3 -0
- package/dist/client.js +4 -0
- package/dist/env-qA8EyOr1.d.ts +49 -0
- package/dist/env-qA8EyOr1.d.ts.map +1 -0
- package/dist/env.d.ts +2 -0
- package/dist/env.js +44 -0
- package/dist/env.js.map +1 -0
- package/dist/index-Bm_-MTj6.d.ts +915 -0
- package/dist/index-Bm_-MTj6.d.ts.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +6 -0
- package/dist/middleware-BdVlE8qm.d.ts +576 -0
- package/dist/middleware-BdVlE8qm.d.ts.map +1 -0
- package/dist/middleware.d.ts +2 -0
- package/dist/middleware.js +282 -0
- package/dist/middleware.js.map +1 -0
- package/dist/prerender.d.ts +98 -0
- package/dist/prerender.d.ts.map +1 -0
- package/dist/prerender.js +289 -0
- package/dist/prerender.js.map +1 -0
- package/dist/protocol.d.ts +58 -0
- package/dist/protocol.d.ts.map +1 -0
- package/dist/protocol.js +26 -0
- package/dist/protocol.js.map +1 -0
- package/dist/serve.d.ts +135 -0
- package/dist/serve.d.ts.map +1 -0
- package/dist/serve.js +223 -0
- package/dist/serve.js.map +1 -0
- package/dist/server-BV3xKmLa.js +1148 -0
- package/dist/server-BV3xKmLa.js.map +1 -0
- package/dist/server.d.ts +142 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +1 -0
- package/dist/src-ChnB_xug.js +1140 -0
- package/dist/src-ChnB_xug.js.map +1 -0
- package/dist/static-fn-DgjNArBe.js +123 -0
- package/dist/static-fn-DgjNArBe.js.map +1 -0
- package/package.json +106 -4
- package/src/client.ts +672 -0
- package/src/context.ts +666 -0
- package/src/cookies.ts +229 -0
- package/src/env.ts +86 -0
- package/src/fn-error.ts +97 -0
- package/src/frames-client.ts +1216 -0
- package/src/frames-server.ts +464 -0
- package/src/frames.ts +285 -0
- package/src/index.ts +714 -0
- package/src/live-client.ts +50 -0
- package/src/live-server.ts +182 -0
- package/src/middleware.ts +994 -0
- package/src/prerender.ts +477 -0
- package/src/protocol.ts +61 -0
- package/src/rate-limit.ts +202 -0
- package/src/serve.ts +153 -0
- package/src/server.ts +990 -0
- package/src/session.ts +449 -0
- package/src/start-instance.ts +147 -0
- package/src/static-fn.ts +181 -0
- package/src/static.ts +302 -0
- package/src/stubs.ts +32 -0
- package/src/timing.ts +29 -0
- package/src/wire-types.ts +139 -0
package/src/frames.ts
ADDED
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Frames: a region of server-rendered markup the browser can ask for again and
|
|
3
|
+
* apply in place, Solid 2.0's partial rendering.
|
|
4
|
+
*
|
|
5
|
+
* A frame is what a server function returns when its handler returns a
|
|
6
|
+
* component. The component runs on the server only; what crosses is its
|
|
7
|
+
* markup. The props it is rendered with are SLOTS, positions it marks and the
|
|
8
|
+
* browser fills: `props.children`, and a call such as
|
|
9
|
+
* `props.comment({ cid })`, whose arguments cross as data and whose own
|
|
10
|
+
* children cross as a nested region of server markup.
|
|
11
|
+
*
|
|
12
|
+
* This module is the wire both halves agree on, and nothing else.
|
|
13
|
+
*
|
|
14
|
+
* THE WIRE. A frame is its markup:
|
|
15
|
+
*
|
|
16
|
+
* ```html
|
|
17
|
+
* <barq-frame data-frame="<address>"><script type="application/barq-frame">
|
|
18
|
+
* { "v": 1, "slots": [...], "head": [...] }
|
|
19
|
+
* </script> ...region... <!--s:0--> ...a slot's content... <!--/s:0--> ...</barq-frame>
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* The page carries it inline where a route rendered it, and a server-function
|
|
23
|
+
* response carries the same bytes as its body under `x-barq-rpc: frame`. The
|
|
24
|
+
* payload holds what the browser needs to fill the slots and nothing the
|
|
25
|
+
* markup already says, so no piece of content arrives twice.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
import type { Child, Incoming, JSXElement } from "@barqjs/core";
|
|
29
|
+
import type { HeadTag } from "@barqjs/web";
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* A slot on a server component's props: a call the browser answers with its
|
|
33
|
+
* own content. What the call is given crosses as data, and its `children` as a
|
|
34
|
+
* region of server markup. `$key` names the occurrence, so its content follows
|
|
35
|
+
* it across updates rather than its position.
|
|
36
|
+
*/
|
|
37
|
+
export type Slot<P extends object = {}> = (
|
|
38
|
+
props: Incoming<P & { readonly $key?: string | number; readonly children?: Child }>,
|
|
39
|
+
) => JSXElement;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* A slot the server component reads as data: called once per data context,
|
|
43
|
+
* `const like = props.like({ cid })`, and each property placed whole at a
|
|
44
|
+
* position of the server's own markup, an attribute, a class name or style
|
|
45
|
+
* property in object form, a handler, a ref or a text child. The page's fill
|
|
46
|
+
* takes the call's arguments and returns the object those positions read; the
|
|
47
|
+
* server never has its values to compute with.
|
|
48
|
+
*/
|
|
49
|
+
export type BindingSlot<
|
|
50
|
+
A extends object = {},
|
|
51
|
+
B extends object = Record<string, unknown>,
|
|
52
|
+
> = keyof A extends never
|
|
53
|
+
? (args?: { readonly $key?: string | number }) => Readonly<B>
|
|
54
|
+
: (args: A & { readonly $key?: string | number }) => Readonly<B>;
|
|
55
|
+
|
|
56
|
+
/** The brand on a frame, on either side, carrying where it lives. */
|
|
57
|
+
export const FRAME: unique symbol = Symbol.for("barq.frame") as never;
|
|
58
|
+
|
|
59
|
+
/** How a frame is named across the wire: its server function and its address. */
|
|
60
|
+
export interface FrameRef {
|
|
61
|
+
readonly id: string;
|
|
62
|
+
readonly address: string;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Whether a value is a frame: a server function's component result, on either side. */
|
|
66
|
+
export function isFrame(value: unknown): boolean {
|
|
67
|
+
return (
|
|
68
|
+
typeof value === "function" &&
|
|
69
|
+
(value as unknown as Record<symbol, unknown>)[FRAME] !== undefined
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* How a server function's component result becomes a frame, installed by
|
|
75
|
+
* `@barqjs/start/server`: on the global, because a server bundle and the host
|
|
76
|
+
* serving it each carry a copy of this module, and the copy that defines a
|
|
77
|
+
* server function is not always the one that imported the server half.
|
|
78
|
+
*/
|
|
79
|
+
const MAKE = Symbol.for("barq.frames.make");
|
|
80
|
+
|
|
81
|
+
type MakeFrame = (id: string, data: unknown, component: (props: never) => unknown) => unknown;
|
|
82
|
+
|
|
83
|
+
export function installFrames(make: MakeFrame): void {
|
|
84
|
+
(globalThis as { [MAKE]?: MakeFrame })[MAKE] = make;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** The handler's result, a frame when it is a component and the server half is here. */
|
|
88
|
+
export function asFrame(id: string, data: unknown, result: unknown): unknown {
|
|
89
|
+
const make = (globalThis as { [MAKE]?: MakeFrame })[MAKE];
|
|
90
|
+
if (make === undefined || typeof result !== "function" || isFrame(result)) return result;
|
|
91
|
+
return make(id, data, result as (props: never) => unknown);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The element a frame's markup stands in. `display: contents`, so it takes no box. */
|
|
95
|
+
export const FRAME_TAG = "barq-frame";
|
|
96
|
+
|
|
97
|
+
/** The element a nested region of server markup stands in, inside a slot's content. */
|
|
98
|
+
export const REGION_TAG = "barq-region";
|
|
99
|
+
|
|
100
|
+
/** The `type` of the script that carries a frame's payload. Not JavaScript, so never run. */
|
|
101
|
+
export const PAYLOAD_TYPE = "application/barq-frame";
|
|
102
|
+
|
|
103
|
+
/** The `x-barq-rpc` value a frame response carries. */
|
|
104
|
+
export const RPC_FRAME = "frame";
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* The `x-barq-rpc` value of a mutation's answer that carries the regions it
|
|
108
|
+
* changed beside its value: single flight, one round trip for both.
|
|
109
|
+
*/
|
|
110
|
+
export const RPC_FLIGHT = "flight";
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* The request header a page sends with a mutation: the frames it has mounted,
|
|
114
|
+
* as `[{ id, args }]`, so the answer can carry the ones the mutation changed.
|
|
115
|
+
* Bounded, as a header is: a page with more mounted frames names the first ones.
|
|
116
|
+
*/
|
|
117
|
+
export const FRAMES_HEADER = "x-barq-frames";
|
|
118
|
+
export const FRAMES_BUDGET = 32;
|
|
119
|
+
|
|
120
|
+
/** The `type` of the script a single-flight answer carries its value in. */
|
|
121
|
+
export const FLIGHT_TYPE = "application/barq-flight";
|
|
122
|
+
|
|
123
|
+
/** Dispatched on `document` once a frame update has been applied to the page. */
|
|
124
|
+
export const FRAME_APPLIED_EVENT = "barq:frame-applied";
|
|
125
|
+
|
|
126
|
+
/** The wire format's version: a browser reading a newer one fetches the page whole. */
|
|
127
|
+
export const FRAME_VERSION = 1;
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* One slot the server component marked: where it stands, by the index in its
|
|
131
|
+
* markers, and what the browser needs to fill it.
|
|
132
|
+
*/
|
|
133
|
+
export interface SlotRecord {
|
|
134
|
+
/** The index in the slot's markers, `<!--s:N-->` and `<!--/s:N-->`. */
|
|
135
|
+
readonly at: number;
|
|
136
|
+
/** The prop the component read: `children`, or the name it called. */
|
|
137
|
+
readonly name: string;
|
|
138
|
+
/**
|
|
139
|
+
* The occurrence's identity across updates: `$key` when the call named one,
|
|
140
|
+
* and its name and position among the calls of that name otherwise.
|
|
141
|
+
*/
|
|
142
|
+
readonly key: string;
|
|
143
|
+
/** The call's arguments, wire-encoded, its `children` aside. */
|
|
144
|
+
readonly args?: unknown;
|
|
145
|
+
/**
|
|
146
|
+
* The call's `children`, as server markup: the nested region. Absent when
|
|
147
|
+
* the page already carries it, inside the slot's content.
|
|
148
|
+
*/
|
|
149
|
+
readonly region?: string;
|
|
150
|
+
/** Whether the call passed `children` at all. */
|
|
151
|
+
readonly hasRegion?: boolean;
|
|
152
|
+
/**
|
|
153
|
+
* The call was read as data, a binding slot: it has no range, and its
|
|
154
|
+
* properties fill the positions marked with its index.
|
|
155
|
+
*/
|
|
156
|
+
readonly bind?: boolean;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** What a frame's script carries. */
|
|
160
|
+
export interface FramePayload {
|
|
161
|
+
readonly v: number;
|
|
162
|
+
/**
|
|
163
|
+
* What the call was given, wire-encoded: what the page sends to ask for the
|
|
164
|
+
* region again, live or after a mutation. It is the call's own input, which
|
|
165
|
+
* the page could have sent itself.
|
|
166
|
+
*/
|
|
167
|
+
readonly args?: unknown;
|
|
168
|
+
/** Called through `live`: the page connects and keeps the region current. */
|
|
169
|
+
readonly live?: boolean;
|
|
170
|
+
readonly slots: readonly SlotRecord[];
|
|
171
|
+
/** What the region declared for the head, and the assets it needs. */
|
|
172
|
+
readonly head: readonly HeadTag[];
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
export function slotOpen(at: number): string {
|
|
176
|
+
return `s:${at}`;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
export function slotClose(at: number): string {
|
|
180
|
+
return `/s:${at}`;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** The marker index a comment's data names, or `-1` when it is not a slot's opening marker. */
|
|
184
|
+
export function slotIndex(data: string): number {
|
|
185
|
+
return data.startsWith("s:") ? Number(data.slice(2)) : -1;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** The marker index a comment's data names, or `-1` when it is not a slot's closing marker. */
|
|
189
|
+
export function slotEnd(data: string): number {
|
|
190
|
+
return data.startsWith("/s:") ? Number(data.slice(3)) : -1;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* A string of 32-bit FNV-1a, in base 36: short enough to be an attribute,
|
|
195
|
+
* stable across processes, which a frame's address has to be.
|
|
196
|
+
*/
|
|
197
|
+
function digest(text: string): string {
|
|
198
|
+
let hash = 0x811c9dc5;
|
|
199
|
+
for (let at = 0; at < text.length; at++) {
|
|
200
|
+
hash ^= text.charCodeAt(at);
|
|
201
|
+
hash = Math.imul(hash, 0x01000193);
|
|
202
|
+
}
|
|
203
|
+
return (hash >>> 0).toString(36);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* Where a frame lives: the server function and what it was called with. One
|
|
208
|
+
* address is one region, so asking for it again updates that region rather
|
|
209
|
+
* than mounting a second one, and an answer for other arguments is another.
|
|
210
|
+
*/
|
|
211
|
+
export function frameAddress(id: string, wireArgs: unknown): string {
|
|
212
|
+
return `${id}#${digest(JSON.stringify(wireArgs ?? null))}`;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** The payload as the text of its script: `<` escaped, so no string in it can end the element. */
|
|
216
|
+
export function payloadText(payload: FramePayload): string {
|
|
217
|
+
return JSON.stringify(payload).replaceAll("<", "\\u003c");
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** The opening of a frame's markup, the payload's script included. */
|
|
221
|
+
export function frameOpen(address: string, payload: FramePayload): string {
|
|
222
|
+
const attribute = address
|
|
223
|
+
.replaceAll("&", "&")
|
|
224
|
+
.replaceAll('"', """)
|
|
225
|
+
.replaceAll("<", "<");
|
|
226
|
+
return (
|
|
227
|
+
`<${FRAME_TAG} data-frame="${attribute}" style="display:contents">` +
|
|
228
|
+
`<script type="${PAYLOAD_TYPE}">${payloadText(payload)}</script>`
|
|
229
|
+
);
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
export const FRAME_CLOSE = `</${FRAME_TAG}>`;
|
|
233
|
+
|
|
234
|
+
export function regionMarkup(key: string, html: string): string {
|
|
235
|
+
const attribute = key.replaceAll("&", "&").replaceAll('"', """).replaceAll("<", "<");
|
|
236
|
+
return `<${REGION_TAG} data-region="${attribute}" style="display:contents">${html}</${REGION_TAG}>`;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* A binding slot's markers, as `@barqjs/server` writes them: an attribute
|
|
241
|
+
* `_b-<position>` on each element it fills, valued `<at>:<key>[=<member>]`
|
|
242
|
+
* entries separated by commas, and a text child between `<!--_b:<at>:<key>-->`
|
|
243
|
+
* and `<!--/_b-->`. The position is the attribute's name, `on-<event>` or
|
|
244
|
+
* `ref`; a member is a class name or style property in object form, or
|
|
245
|
+
* `capture` on a handler.
|
|
246
|
+
*/
|
|
247
|
+
export const BIND_ATTRIBUTE = "_b-";
|
|
248
|
+
export const BIND_EVENT = "on-";
|
|
249
|
+
export const BIND_TEXT = "_b:";
|
|
250
|
+
export const BIND_TEXT_END = "/_b";
|
|
251
|
+
|
|
252
|
+
export interface BindEntry {
|
|
253
|
+
readonly at: number;
|
|
254
|
+
readonly key: string;
|
|
255
|
+
readonly member?: string;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
function bindEntry(text: string): BindEntry | null {
|
|
259
|
+
const colon = text.indexOf(":");
|
|
260
|
+
if (colon < 1) return null;
|
|
261
|
+
const at = Number(text.slice(0, colon));
|
|
262
|
+
if (!Number.isInteger(at)) return null;
|
|
263
|
+
const equals = text.indexOf("=", colon);
|
|
264
|
+
const key = decodeURIComponent(
|
|
265
|
+
equals === -1 ? text.slice(colon + 1) : text.slice(colon + 1, equals),
|
|
266
|
+
);
|
|
267
|
+
return equals === -1
|
|
268
|
+
? { at, key }
|
|
269
|
+
: { at, key, member: decodeURIComponent(text.slice(equals + 1)) };
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/** The entries of a marker attribute's value. */
|
|
273
|
+
export function bindEntries(value: string): BindEntry[] {
|
|
274
|
+
const out: BindEntry[] = [];
|
|
275
|
+
for (const text of value.split(",")) {
|
|
276
|
+
const entry = bindEntry(text);
|
|
277
|
+
if (entry !== null) out.push(entry);
|
|
278
|
+
}
|
|
279
|
+
return out;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/** The entry a text position's opening comment names, or `null` when it is not one. */
|
|
283
|
+
export function bindTextEntry(data: string): BindEntry | null {
|
|
284
|
+
return data.startsWith(BIND_TEXT) ? bindEntry(data.slice(BIND_TEXT.length)) : null;
|
|
285
|
+
}
|