@sigil-dev/grimoire 0.9.20 → 0.9.22
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/README.md +83 -83
- package/index.ts +50 -48
- package/package.json +16 -5
- package/public/__grimoire__/grimoire-client.js +12 -0
- package/public/__grimoire__/runtime.js +1241 -0
- package/server.ts +22 -20
- package/src/adapters/bun.ts +17 -0
- package/src/adapters/static.ts +41 -0
- package/src/adapters/types.ts +36 -0
- package/src/base.ts +91 -0
- package/src/client/csrf.ts +47 -47
- package/src/client/deferred.ts +179 -179
- package/src/client/enhance.ts +160 -160
- package/src/client/router.ts +870 -833
- package/src/dev/compile-module.ts +211 -211
- package/src/dev/loader.ts +141 -141
- package/src/dev/resolve.ts +70 -70
- package/src/dev/runtime-bundle.ts +51 -51
- package/src/env/modules.ts +62 -62
- package/src/env/required.ts +42 -0
- package/src/env/typegen.ts +61 -61
- package/src/headers.ts +105 -114
- package/src/logger/transports.ts +117 -117
- package/src/rendering/head.ts +49 -49
- package/src/rendering/hydrate.ts +161 -161
- package/src/rendering/images.ts +43 -43
- package/src/rendering/index.ts +755 -745
- package/src/rendering/preload.ts +101 -95
- package/src/rendering/ssrPlugin.ts +108 -108
- package/src/rendering/timing.ts +40 -40
- package/src/routing/router.ts +186 -186
- package/src/routing/scanner.ts +225 -196
- package/src/routing/transform-routes.ts +102 -102
- package/src/server/after-response.ts +206 -194
- package/src/server/asset-cache.ts +57 -55
- package/src/server/build.ts +262 -249
- package/src/server/cached.ts +114 -114
- package/src/server/client-address.ts +82 -82
- package/src/server/client-dir.ts +57 -57
- package/src/server/client-entry.ts +44 -0
- package/src/server/cookie-utils.ts +80 -80
- package/src/server/coordinator.ts +476 -471
- package/src/server/hooks.ts +122 -122
- package/src/server/index.ts +1138 -1022
- package/src/server/plugins.ts +172 -172
- package/src/server/prerender.ts +444 -0
- package/src/server/reserved.ts +17 -0
- package/src/server/resolver.ts +98 -98
- package/src/server/rewrite.ts +28 -0
- package/src/server/warm.ts +91 -91
- package/src/server/with-headers.ts +27 -0
- package/src/server/worker.ts +74 -72
- package/src/testing/dom.ts +73 -0
- package/src/testing/index.ts +169 -0
- package/src/testing/server.ts +162 -0
- package/src/typegen/index.ts +450 -450
- package/src/types.ts +501 -432
- package/test/after-response.test.ts +132 -113
- package/test/asset-cache-policy.test.ts +96 -96
- package/test/base.test.ts +134 -0
- package/test/cached.test.ts +126 -126
- package/test/client-address.test.ts +78 -78
- package/test/client-csrf.test.ts +61 -61
- package/test/client-dir.test.ts +101 -69
- package/test/client-router.test.ts +789 -734
- package/test/coordinator.test.ts +96 -94
- package/test/deferred.test.ts +256 -256
- package/test/dev-loader.test.ts +30 -30
- package/test/env.test.ts +168 -168
- package/test/force-production.test.ts +44 -0
- package/test/images.test.ts +49 -49
- package/test/locals-header.test.ts +61 -0
- package/test/middleware.test.ts +243 -243
- package/test/parser-plugins.test.ts +92 -92
- package/test/plugin-handle.test.ts +62 -62
- package/test/plugin-services-context.test.ts +97 -97
- package/test/preload.test.ts +48 -48
- package/test/prerender.test.ts +353 -0
- package/test/rendering.test.ts +798 -798
- package/test/required-env.test.ts +32 -0
- package/test/rewrite-html.test.ts +90 -0
- package/test/scanning.test.ts +349 -314
- package/test/server.test.ts +640 -619
- package/test/services.test.ts +90 -90
- package/test/streaming.test.ts +378 -378
- package/test/testing-helpers.test.ts +166 -0
- package/test/typegen.test.ts +805 -799
- package/test/warm.test.ts +96 -96
- package/test/worker-context.test.ts +59 -59
- package/test/workspace-files.test.ts +149 -146
- package/test/workspace-versions.test.ts +131 -131
- package/.grimoire/_routes.ts +0 -4
- package/public/__grimoire__/client.js +0 -55
- package/public/__grimoire__/hydrate.js +0 -63
package/src/client/deferred.ts
CHANGED
|
@@ -1,179 +1,179 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Reading a value that is still in flight.
|
|
3
|
-
*
|
|
4
|
-
* A top-level promise in load data streams in later. The server sends the
|
|
5
|
-
* page immediately, so the component renders with that value `undefined` and
|
|
6
|
-
* the visitor reads the rest of the page while the slow part is still on its
|
|
7
|
-
* way. When it settles, the server sends a small patch script that writes the
|
|
8
|
-
* value into the state and dispatches `grimoire:deferred`.
|
|
9
|
-
*
|
|
10
|
-
* Until now each app wired that event up by hand — the same fifteen lines,
|
|
11
|
-
* copied, with the details easy to get wrong. `deferred()` is those lines.
|
|
12
|
-
*
|
|
13
|
-
* ```tsx
|
|
14
|
-
* const reviews = deferred<Review[]>(props.data.reviews, []);
|
|
15
|
-
*
|
|
16
|
-
* return reviews.done
|
|
17
|
-
* ? <ul>{reviews.value.map((r) => <li key={r.id}>{r.text}</li>)}</ul>
|
|
18
|
-
* : <p>Loading reviews…</p>;
|
|
19
|
-
* ```
|
|
20
|
-
*
|
|
21
|
-
* The one thing this cannot do is beat hydration. The page's state script
|
|
22
|
-
* holds the values, and hydration waits for the whole response, so a value
|
|
23
|
-
* that arrives after the document does will not re-render the tree on its
|
|
24
|
-
* own. The listener is what closes that gap — it fires for late arrivals and
|
|
25
|
-
* updates the signal, so a component that re-renders (on a click, a
|
|
26
|
-
* navigation, a transition) sees the value. For a value that has to appear
|
|
27
|
-
* the instant it lands without any other interaction, the [Suspense
|
|
28
|
-
* boundary](https://react.dev/reference/react/Suspense) already in your tree
|
|
29
|
-
* is the mechanism — the value goes in as ordinary data and Suspense
|
|
30
|
-
* handles the timing.
|
|
31
|
-
*/
|
|
32
|
-
|
|
33
|
-
/**
|
|
34
|
-
* The hydration state the server embeds, as this module sees it.
|
|
35
|
-
*
|
|
36
|
-
* Declared locally because the same shape is declared in @sigil-dev/types
|
|
37
|
-
* for applications, and grimoire does not depend on that package — a
|
|
38
|
-
* framework package should not reach for the app's type package to describe
|
|
39
|
-
* its own runtime. The two must agree, and `deferred.test.ts` drives the
|
|
40
|
-
* server's real patch script, so a change to one that the other does not
|
|
41
|
-
* follow fails a test.
|
|
42
|
-
*/
|
|
43
|
-
interface GrimoireStateMirror {
|
|
44
|
-
pattern?: string;
|
|
45
|
-
data?: Record<string, unknown>;
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
/** The window this module reads. A local alias, not a global augmentation. */
|
|
49
|
-
interface GrimoireWindow {
|
|
50
|
-
__grimoire_state__?: GrimoireStateMirror | HTMLElement;
|
|
51
|
-
}
|
|
52
|
-
|
|
53
|
-
const state = (): GrimoireStateMirror | HTMLElement | undefined =>
|
|
54
|
-
(globalThis as unknown as { window?: GrimoireWindow }).window
|
|
55
|
-
?.__grimoire_state__;
|
|
56
|
-
|
|
57
|
-
/** The value a component sees while it is still in flight. */
|
|
58
|
-
export interface Deferred<T> {
|
|
59
|
-
/** The value, or `fallback` while it is still loading. */
|
|
60
|
-
readonly value: T;
|
|
61
|
-
/** `true` once the real value has arrived. */
|
|
62
|
-
readonly done: boolean;
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
/** The current value of a streamed property, or `undefined` if still in flight. */
|
|
66
|
-
function readDeferredValue<T>(key?: string): T | undefined {
|
|
67
|
-
const held = state();
|
|
68
|
-
// The element carries the authoritative copy but has nodeType; the plain
|
|
69
|
-
// mirror does not. Reading the wrong one silently loses the value, so
|
|
70
|
-
// this guard is the difference between working and not.
|
|
71
|
-
if (!held) return undefined;
|
|
72
|
-
const data = held instanceof HTMLElement ? undefined : held.data;
|
|
73
|
-
if (!data) return undefined;
|
|
74
|
-
if (key !== undefined) {
|
|
75
|
-
const one = data[key];
|
|
76
|
-
return one === undefined || one === null ? undefined : (one as T);
|
|
77
|
-
}
|
|
78
|
-
for (const one of Object.values(data)) {
|
|
79
|
-
if (one !== undefined && one !== null) return one as T;
|
|
80
|
-
}
|
|
81
|
-
return undefined;
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
/**
|
|
85
|
-
* Wrap a possibly-streamed load value.
|
|
86
|
-
*
|
|
87
|
-
* @param incoming The prop from `data`. `undefined` means still loading; any
|
|
88
|
-
* other value is already resolved, which is the normal case on a
|
|
89
|
-
* client-side navigation and on the server.
|
|
90
|
-
* @param fallback What to render while loading.
|
|
91
|
-
* @param key The property name this value streams under. Required when a
|
|
92
|
-
* page has more than one deferred value, because the patch event only says
|
|
93
|
-
* *that* something settled — reading the first non-empty entry in the state
|
|
94
|
-
* would hand one component another's data. With a single deferred value on
|
|
95
|
-
* the page it can be left out, and any settled value is taken.
|
|
96
|
-
*/
|
|
97
|
-
export function deferred<T>(
|
|
98
|
-
incoming: T | undefined,
|
|
99
|
-
fallback: T,
|
|
100
|
-
key?: string,
|
|
101
|
-
): Deferred<T> {
|
|
102
|
-
let value = incoming ?? fallback;
|
|
103
|
-
let done = incoming !== undefined;
|
|
104
|
-
|
|
105
|
-
// Only in a browser: the server has no window, and a value still in
|
|
106
|
-
// flight is genuinely `undefined` here.
|
|
107
|
-
if (typeof window !== "undefined" && !done) {
|
|
108
|
-
// The patch may have landed between this component's first render and
|
|
109
|
-
// the event wiring, which is a real window when a value resolves in
|
|
110
|
-
// ~1ms. Reading on the way in is what closes it.
|
|
111
|
-
const early = readDeferredValue<T>(key);
|
|
112
|
-
if (early !== undefined) {
|
|
113
|
-
value = early;
|
|
114
|
-
done = true;
|
|
115
|
-
} else {
|
|
116
|
-
window.addEventListener("grimoire:deferred", (event) => {
|
|
117
|
-
// With a key, the event names it — so an unrelated value
|
|
118
|
-
// settling does not mark this one done.
|
|
119
|
-
if (key !== undefined) {
|
|
120
|
-
const detail = (event as CustomEvent<{ key?: string }>).detail;
|
|
121
|
-
if (detail?.key !== undefined && detail.key !== key) return;
|
|
122
|
-
}
|
|
123
|
-
const held = readDeferredValue<T>(key);
|
|
124
|
-
if (held === undefined) return;
|
|
125
|
-
value = held;
|
|
126
|
-
done = true;
|
|
127
|
-
});
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
return {
|
|
132
|
-
get value() {
|
|
133
|
-
return value;
|
|
134
|
-
},
|
|
135
|
-
get done() {
|
|
136
|
-
return done;
|
|
137
|
-
},
|
|
138
|
-
};
|
|
139
|
-
}
|
|
140
|
-
|
|
141
|
-
/**
|
|
142
|
-
* Drive a `$state` from a streamed value.
|
|
143
|
-
*
|
|
144
|
-
* `deferred()` returns a snapshot, which is right for a component that
|
|
145
|
-
* re-renders on its own. This is for a value that is rendered somewhere
|
|
146
|
-
* else, or held in shared state — the pattern where a module-level
|
|
147
|
-
* `$state` is assigned from the event:
|
|
148
|
-
*
|
|
149
|
-
* ```ts
|
|
150
|
-
* let omenText = $state("(the ink is still drying…)");
|
|
151
|
-
* onDeferred((value) => { omenText = value; }, "omen");
|
|
152
|
-
* ```
|
|
153
|
-
*
|
|
154
|
-
* The callback runs once immediately if the value has already landed, so
|
|
155
|
-
* there is no window where it is missed.
|
|
156
|
-
*/
|
|
157
|
-
export function onDeferred<T>(
|
|
158
|
-
apply: (value: T) => void,
|
|
159
|
-
key?: string,
|
|
160
|
-
): void {
|
|
161
|
-
if (typeof window === "undefined") return;
|
|
162
|
-
|
|
163
|
-
// Fires once, immediately, if the value has already landed — the same
|
|
164
|
-
// early-arrival read deferred() does, so there is no window where a
|
|
165
|
-
// value that settled first is missed.
|
|
166
|
-
const current = readDeferredValue<T>(key);
|
|
167
|
-
if (current !== undefined) {
|
|
168
|
-
apply(current);
|
|
169
|
-
return;
|
|
170
|
-
}
|
|
171
|
-
window.addEventListener("grimoire:deferred", (event) => {
|
|
172
|
-
if (key !== undefined) {
|
|
173
|
-
const detail = (event as CustomEvent<{ key?: string }>).detail;
|
|
174
|
-
if (detail?.key !== undefined && detail.key !== key) return;
|
|
175
|
-
}
|
|
176
|
-
const held = readDeferredValue<T>(key);
|
|
177
|
-
if (held !== undefined) apply(held);
|
|
178
|
-
});
|
|
179
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* Reading a value that is still in flight.
|
|
3
|
+
*
|
|
4
|
+
* A top-level promise in load data streams in later. The server sends the
|
|
5
|
+
* page immediately, so the component renders with that value `undefined` and
|
|
6
|
+
* the visitor reads the rest of the page while the slow part is still on its
|
|
7
|
+
* way. When it settles, the server sends a small patch script that writes the
|
|
8
|
+
* value into the state and dispatches `grimoire:deferred`.
|
|
9
|
+
*
|
|
10
|
+
* Until now each app wired that event up by hand — the same fifteen lines,
|
|
11
|
+
* copied, with the details easy to get wrong. `deferred()` is those lines.
|
|
12
|
+
*
|
|
13
|
+
* ```tsx
|
|
14
|
+
* const reviews = deferred<Review[]>(props.data.reviews, []);
|
|
15
|
+
*
|
|
16
|
+
* return reviews.done
|
|
17
|
+
* ? <ul>{reviews.value.map((r) => <li key={r.id}>{r.text}</li>)}</ul>
|
|
18
|
+
* : <p>Loading reviews…</p>;
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* The one thing this cannot do is beat hydration. The page's state script
|
|
22
|
+
* holds the values, and hydration waits for the whole response, so a value
|
|
23
|
+
* that arrives after the document does will not re-render the tree on its
|
|
24
|
+
* own. The listener is what closes that gap — it fires for late arrivals and
|
|
25
|
+
* updates the signal, so a component that re-renders (on a click, a
|
|
26
|
+
* navigation, a transition) sees the value. For a value that has to appear
|
|
27
|
+
* the instant it lands without any other interaction, the [Suspense
|
|
28
|
+
* boundary](https://react.dev/reference/react/Suspense) already in your tree
|
|
29
|
+
* is the mechanism — the value goes in as ordinary data and Suspense
|
|
30
|
+
* handles the timing.
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The hydration state the server embeds, as this module sees it.
|
|
35
|
+
*
|
|
36
|
+
* Declared locally because the same shape is declared in @sigil-dev/types
|
|
37
|
+
* for applications, and grimoire does not depend on that package — a
|
|
38
|
+
* framework package should not reach for the app's type package to describe
|
|
39
|
+
* its own runtime. The two must agree, and `deferred.test.ts` drives the
|
|
40
|
+
* server's real patch script, so a change to one that the other does not
|
|
41
|
+
* follow fails a test.
|
|
42
|
+
*/
|
|
43
|
+
interface GrimoireStateMirror {
|
|
44
|
+
pattern?: string;
|
|
45
|
+
data?: Record<string, unknown>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The window this module reads. A local alias, not a global augmentation. */
|
|
49
|
+
interface GrimoireWindow {
|
|
50
|
+
__grimoire_state__?: GrimoireStateMirror | HTMLElement;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const state = (): GrimoireStateMirror | HTMLElement | undefined =>
|
|
54
|
+
(globalThis as unknown as { window?: GrimoireWindow }).window
|
|
55
|
+
?.__grimoire_state__;
|
|
56
|
+
|
|
57
|
+
/** The value a component sees while it is still in flight. */
|
|
58
|
+
export interface Deferred<T> {
|
|
59
|
+
/** The value, or `fallback` while it is still loading. */
|
|
60
|
+
readonly value: T;
|
|
61
|
+
/** `true` once the real value has arrived. */
|
|
62
|
+
readonly done: boolean;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The current value of a streamed property, or `undefined` if still in flight. */
|
|
66
|
+
function readDeferredValue<T>(key?: string): T | undefined {
|
|
67
|
+
const held = state();
|
|
68
|
+
// The element carries the authoritative copy but has nodeType; the plain
|
|
69
|
+
// mirror does not. Reading the wrong one silently loses the value, so
|
|
70
|
+
// this guard is the difference between working and not.
|
|
71
|
+
if (!held) return undefined;
|
|
72
|
+
const data = held instanceof HTMLElement ? undefined : held.data;
|
|
73
|
+
if (!data) return undefined;
|
|
74
|
+
if (key !== undefined) {
|
|
75
|
+
const one = data[key];
|
|
76
|
+
return one === undefined || one === null ? undefined : (one as T);
|
|
77
|
+
}
|
|
78
|
+
for (const one of Object.values(data)) {
|
|
79
|
+
if (one !== undefined && one !== null) return one as T;
|
|
80
|
+
}
|
|
81
|
+
return undefined;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Wrap a possibly-streamed load value.
|
|
86
|
+
*
|
|
87
|
+
* @param incoming The prop from `data`. `undefined` means still loading; any
|
|
88
|
+
* other value is already resolved, which is the normal case on a
|
|
89
|
+
* client-side navigation and on the server.
|
|
90
|
+
* @param fallback What to render while loading.
|
|
91
|
+
* @param key The property name this value streams under. Required when a
|
|
92
|
+
* page has more than one deferred value, because the patch event only says
|
|
93
|
+
* *that* something settled — reading the first non-empty entry in the state
|
|
94
|
+
* would hand one component another's data. With a single deferred value on
|
|
95
|
+
* the page it can be left out, and any settled value is taken.
|
|
96
|
+
*/
|
|
97
|
+
export function deferred<T>(
|
|
98
|
+
incoming: T | undefined,
|
|
99
|
+
fallback: T,
|
|
100
|
+
key?: string,
|
|
101
|
+
): Deferred<T> {
|
|
102
|
+
let value = incoming ?? fallback;
|
|
103
|
+
let done = incoming !== undefined;
|
|
104
|
+
|
|
105
|
+
// Only in a browser: the server has no window, and a value still in
|
|
106
|
+
// flight is genuinely `undefined` here.
|
|
107
|
+
if (typeof window !== "undefined" && !done) {
|
|
108
|
+
// The patch may have landed between this component's first render and
|
|
109
|
+
// the event wiring, which is a real window when a value resolves in
|
|
110
|
+
// ~1ms. Reading on the way in is what closes it.
|
|
111
|
+
const early = readDeferredValue<T>(key);
|
|
112
|
+
if (early !== undefined) {
|
|
113
|
+
value = early;
|
|
114
|
+
done = true;
|
|
115
|
+
} else {
|
|
116
|
+
window.addEventListener("grimoire:deferred", (event) => {
|
|
117
|
+
// With a key, the event names it — so an unrelated value
|
|
118
|
+
// settling does not mark this one done.
|
|
119
|
+
if (key !== undefined) {
|
|
120
|
+
const detail = (event as CustomEvent<{ key?: string }>).detail;
|
|
121
|
+
if (detail?.key !== undefined && detail.key !== key) return;
|
|
122
|
+
}
|
|
123
|
+
const held = readDeferredValue<T>(key);
|
|
124
|
+
if (held === undefined) return;
|
|
125
|
+
value = held;
|
|
126
|
+
done = true;
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
return {
|
|
132
|
+
get value() {
|
|
133
|
+
return value;
|
|
134
|
+
},
|
|
135
|
+
get done() {
|
|
136
|
+
return done;
|
|
137
|
+
},
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* Drive a `$state` from a streamed value.
|
|
143
|
+
*
|
|
144
|
+
* `deferred()` returns a snapshot, which is right for a component that
|
|
145
|
+
* re-renders on its own. This is for a value that is rendered somewhere
|
|
146
|
+
* else, or held in shared state — the pattern where a module-level
|
|
147
|
+
* `$state` is assigned from the event:
|
|
148
|
+
*
|
|
149
|
+
* ```ts
|
|
150
|
+
* let omenText = $state("(the ink is still drying…)");
|
|
151
|
+
* onDeferred((value) => { omenText = value; }, "omen");
|
|
152
|
+
* ```
|
|
153
|
+
*
|
|
154
|
+
* The callback runs once immediately if the value has already landed, so
|
|
155
|
+
* there is no window where it is missed.
|
|
156
|
+
*/
|
|
157
|
+
export function onDeferred<T>(
|
|
158
|
+
apply: (value: T) => void,
|
|
159
|
+
key?: string,
|
|
160
|
+
): void {
|
|
161
|
+
if (typeof window === "undefined") return;
|
|
162
|
+
|
|
163
|
+
// Fires once, immediately, if the value has already landed — the same
|
|
164
|
+
// early-arrival read deferred() does, so there is no window where a
|
|
165
|
+
// value that settled first is missed.
|
|
166
|
+
const current = readDeferredValue<T>(key);
|
|
167
|
+
if (current !== undefined) {
|
|
168
|
+
apply(current);
|
|
169
|
+
return;
|
|
170
|
+
}
|
|
171
|
+
window.addEventListener("grimoire:deferred", (event) => {
|
|
172
|
+
if (key !== undefined) {
|
|
173
|
+
const detail = (event as CustomEvent<{ key?: string }>).detail;
|
|
174
|
+
if (detail?.key !== undefined && detail.key !== key) return;
|
|
175
|
+
}
|
|
176
|
+
const held = readDeferredValue<T>(key);
|
|
177
|
+
if (held !== undefined) apply(held);
|
|
178
|
+
});
|
|
179
|
+
}
|