@sigil-dev/grimoire 0.9.21 → 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.
Files changed (94) hide show
  1. package/README.md +83 -83
  2. package/index.ts +50 -48
  3. package/package.json +16 -5
  4. package/public/__grimoire__/grimoire-client.js +12 -0
  5. package/public/__grimoire__/runtime.js +1241 -0
  6. package/server.ts +22 -20
  7. package/src/adapters/bun.ts +17 -0
  8. package/src/adapters/static.ts +41 -0
  9. package/src/adapters/types.ts +36 -0
  10. package/src/base.ts +91 -0
  11. package/src/client/csrf.ts +47 -47
  12. package/src/client/deferred.ts +179 -179
  13. package/src/client/enhance.ts +160 -160
  14. package/src/client/router.ts +870 -833
  15. package/src/dev/compile-module.ts +211 -211
  16. package/src/dev/loader.ts +141 -141
  17. package/src/dev/resolve.ts +70 -70
  18. package/src/dev/runtime-bundle.ts +51 -51
  19. package/src/env/modules.ts +62 -62
  20. package/src/env/required.ts +42 -0
  21. package/src/env/typegen.ts +61 -61
  22. package/src/headers.ts +105 -105
  23. package/src/logger/transports.ts +117 -117
  24. package/src/rendering/head.ts +49 -49
  25. package/src/rendering/hydrate.ts +161 -161
  26. package/src/rendering/images.ts +43 -43
  27. package/src/rendering/index.ts +755 -749
  28. package/src/rendering/preload.ts +101 -101
  29. package/src/rendering/ssrPlugin.ts +108 -108
  30. package/src/rendering/timing.ts +40 -40
  31. package/src/routing/router.ts +186 -186
  32. package/src/routing/scanner.ts +225 -196
  33. package/src/routing/transform-routes.ts +102 -102
  34. package/src/server/after-response.ts +206 -206
  35. package/src/server/asset-cache.ts +57 -57
  36. package/src/server/build.ts +262 -262
  37. package/src/server/cached.ts +114 -114
  38. package/src/server/client-address.ts +82 -82
  39. package/src/server/client-dir.ts +57 -57
  40. package/src/server/client-entry.ts +44 -44
  41. package/src/server/cookie-utils.ts +80 -80
  42. package/src/server/coordinator.ts +476 -471
  43. package/src/server/hooks.ts +122 -122
  44. package/src/server/index.ts +1138 -1018
  45. package/src/server/plugins.ts +172 -172
  46. package/src/server/prerender.ts +444 -0
  47. package/src/server/reserved.ts +17 -0
  48. package/src/server/resolver.ts +98 -98
  49. package/src/server/rewrite.ts +28 -0
  50. package/src/server/warm.ts +91 -91
  51. package/src/server/with-headers.ts +27 -27
  52. package/src/server/worker.ts +74 -72
  53. package/src/testing/dom.ts +73 -0
  54. package/src/testing/index.ts +169 -0
  55. package/src/testing/server.ts +162 -0
  56. package/src/typegen/index.ts +450 -450
  57. package/src/types.ts +501 -432
  58. package/test/after-response.test.ts +132 -132
  59. package/test/asset-cache-policy.test.ts +96 -96
  60. package/test/base.test.ts +134 -0
  61. package/test/cached.test.ts +126 -126
  62. package/test/client-address.test.ts +78 -78
  63. package/test/client-csrf.test.ts +61 -61
  64. package/test/client-dir.test.ts +101 -101
  65. package/test/client-router.test.ts +789 -734
  66. package/test/coordinator.test.ts +96 -94
  67. package/test/deferred.test.ts +256 -256
  68. package/test/dev-loader.test.ts +30 -30
  69. package/test/env.test.ts +168 -168
  70. package/test/force-production.test.ts +44 -0
  71. package/test/images.test.ts +49 -49
  72. package/test/locals-header.test.ts +61 -0
  73. package/test/middleware.test.ts +243 -243
  74. package/test/parser-plugins.test.ts +92 -92
  75. package/test/plugin-handle.test.ts +62 -62
  76. package/test/plugin-services-context.test.ts +97 -97
  77. package/test/preload.test.ts +48 -48
  78. package/test/prerender.test.ts +353 -0
  79. package/test/rendering.test.ts +798 -798
  80. package/test/required-env.test.ts +32 -0
  81. package/test/rewrite-html.test.ts +90 -0
  82. package/test/scanning.test.ts +349 -314
  83. package/test/server.test.ts +640 -619
  84. package/test/services.test.ts +90 -90
  85. package/test/streaming.test.ts +378 -378
  86. package/test/testing-helpers.test.ts +166 -0
  87. package/test/typegen.test.ts +805 -799
  88. package/test/warm.test.ts +96 -96
  89. package/test/worker-context.test.ts +59 -59
  90. package/test/workspace-files.test.ts +149 -146
  91. package/test/workspace-versions.test.ts +131 -131
  92. package/.grimoire/_routes.ts +0 -4
  93. package/public/__grimoire__/client.js +0 -55
  94. package/public/__grimoire__/hydrate.js +0 -63
@@ -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
+ }