@sigil-dev/grimoire 0.9.12 → 0.9.13

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/index.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  // server loads call depends() to register invalidation keys
2
2
  export { depends } from "./src/client/deps";
3
+ export type { Deferred } from "./src/client/deferred";
4
+ export { deferred, onDeferred } from "./src/client/deferred";
3
5
  export { Head } from "./src/rendering/head";
4
6
  // registerSSRPlugin is server-only — import from "@sigil-dev/grimoire/bun"
5
7
  export type { RouteFile, RouteTree } from "./src/routing/scanner";
@@ -34,5 +36,6 @@ export type {
34
36
  WorkerEnv,
35
37
  WorkerMode,
36
38
  WsRouteHandler,
39
+ WorkerContext,
37
40
  } from "./src/types";
38
- export { defineConfig } from "./src/types";
41
+ export { defineConfig, workerContext } from "./src/types";
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "module": "index.ts",
5
5
  "type": "module",
6
6
  "private": false,
7
- "version": "0.9.12",
7
+ "version": "0.9.13",
8
8
  "exports": {
9
9
  ".": "./index.ts",
10
10
  "./server": "./server.ts",
@@ -23,8 +23,8 @@
23
23
  "test": "bun test"
24
24
  },
25
25
  "dependencies": {
26
- "@sigil-dev/compiler": "0.9.12",
27
- "@sigil-dev/runtime": "0.9.12",
26
+ "@sigil-dev/compiler": "0.9.13",
27
+ "@sigil-dev/runtime": "0.9.13",
28
28
  "vite": "^8.0.16"
29
29
  },
30
30
  "peerDependencies": {
@@ -0,0 +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
+ }
@@ -8,6 +8,7 @@ import {
8
8
  import { log } from "../logger/instance";
9
9
  import { rewriteAliases } from "../server/resolver";
10
10
  import type { GrimoirePlugin } from "../types";
11
+ import type { ParserPlugin } from "@babel/core";
11
12
 
12
13
  const logger = log.scope("scope");
13
14
  let registered = false;
@@ -67,7 +68,21 @@ export function registerSSRPlugin(
67
68
  configFile: false,
68
69
  babelrc: false,
69
70
  parserOpts: {
70
- plugins: ["typescript", "jsx"],
71
+ // The jsx plugin goes on .tsx files only.
72
+ //
73
+ // With it enabled everywhere, Babel parses `<R>(x: R) => x`
74
+ // as the opening of a JSX element and fails with
75
+ // "Unexpected token `>`". So a generic arrow function in a
76
+ // plain .ts file — completely ordinary TypeScript — could
77
+ // not be compiled. Found while writing the Drizzle adapter
78
+ // recipe, where `transaction: <R>(db, fn) => ...` is the
79
+ // form that removes an `as any`.
80
+ //
81
+ // A .tsx file is genuinely ambiguous (`<R>(x) => x` is
82
+ // JSX there), so .tsx keeps both and users write `<R,>`.
83
+ plugins: path.endsWith(".tsx")
84
+ ? (["typescript", "jsx"] as ParserPlugin[])
85
+ : (["typescript"] as ParserPlugin[]),
71
86
  },
72
87
  plugins: [[sigilPlugin, { mode: "ssr", hash }]],
73
88
  filename: path,
@@ -202,6 +202,16 @@ export async function startCoordinator(options: CoordinatorOptions) {
202
202
  let globalIndex = 0;
203
203
  let nextPort = port + 1;
204
204
 
205
+ // Total workers across every mode, known before the first spawn. A
206
+ // plugin that creates a per-worker resource needs the whole picture to
207
+ // divide a global budget (a connection pool of N across W workers is
208
+ // N/W each) — and the index alone cannot tell it how many siblings
209
+ // exist. Without this, `max: 20` silently means 20 *per worker*.
210
+ const workerCount = Object.values(scale).reduce<number>(
211
+ (sum, n) => sum + (n ?? 0),
212
+ 0,
213
+ );
214
+
205
215
  for (const [mode, count = 0] of Object.entries(scale)) {
206
216
  for (let i = 0; i < count; i++) {
207
217
  const workerPort = nextPort++;
@@ -227,6 +237,9 @@ export async function startCoordinator(options: CoordinatorOptions) {
227
237
  ...publicEnvVars,
228
238
  GRIMOIRE_MODE: mode,
229
239
  GRIMOIRE_WORKER_INDEX: String(i),
240
+ // The sibling count, so a per-worker resource can divide a global
241
+ // budget instead of taking the whole of it.
242
+ GRIMOIRE_WORKER_COUNT: String(workerCount),
230
243
  GRIMOIRE_WORKER_PORT: String(workerPort),
231
244
  GRIMOIRE_INTERNAL_SECRET: secret,
232
245
  GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
@@ -293,13 +306,17 @@ export async function startCoordinator(options: CoordinatorOptions) {
293
306
  const serialized =
294
307
  (await runSerializeLocals(plugins, locals)) ??
295
308
  defaultSerialize(locals, secret);
296
- // the client's own x-grimoire-* headers are dropped: spread next to
297
- // ours under a different case, both reached the worker joined by a
298
- // comma, and the secret check refused the request
309
+ // Only the two headers the coordinator writes itself are dropped from
310
+ // the client's: spread next to ours under a different case, both
311
+ // reached the worker joined by a comma, and the secret check refused
312
+ // the request. The rest of x-grimoire-* is the client talking to the
313
+ // worker: x-grimoire-navigate asks for a page's data as JSON and
314
+ // x-grimoire-form marks an enhanced submit. Dropping them made every
315
+ // client-side navigation come back as a full HTML page, so the router
316
+ // reloaded the document on each click.
299
317
  const forwardHeaders = new Headers();
300
318
  for (const [k, v] of req.headers) {
301
- if (!k.toLowerCase().startsWith("x-grimoire-"))
302
- forwardHeaders.set(k, v);
319
+ if (!INTERNAL_HEADERS.has(k.toLowerCase())) forwardHeaders.set(k, v);
303
320
  }
304
321
  forwardHeaders.set("X-Grimoire-Locals", serialized);
305
322
  forwardHeaders.set("X-Grimoire-Internal", secret);
@@ -394,6 +411,9 @@ interface WsProxyData {
394
411
  upstream?: WebSocket;
395
412
  }
396
413
 
414
+ /** Headers the coordinator sets itself; a client's copy is never forwarded. */
415
+ const INTERNAL_HEADERS = new Set(["x-grimoire-locals", "x-grimoire-internal"]);
416
+
397
417
  /** Headers for the coordinator's own socket to the worker. */
398
418
  function upstreamWsHeaders(
399
419
  req: Request,
@@ -405,7 +425,7 @@ function upstreamWsHeaders(
405
425
  // the WebSocket client writes its own handshake headers
406
426
  if (
407
427
  key.startsWith("sec-websocket-") ||
408
- key.startsWith("x-grimoire-") ||
428
+ INTERNAL_HEADERS.has(key) ||
409
429
  key === "upgrade" ||
410
430
  key === "connection" ||
411
431
  key === "host"
@@ -30,7 +30,12 @@ import type {
30
30
  RequestEvent,
31
31
  ResolveFunction,
32
32
  } from "./hooks";
33
- import { runDeserializeLocals, runHook, runRequestHooks } from "./plugins";
33
+ import {
34
+ collectServices,
35
+ runDeserializeLocals,
36
+ runHook,
37
+ runRequestHooks,
38
+ } from "./plugins";
34
39
  import { projectAliases, resolverPlugin } from "./resolver";
35
40
 
36
41
  const logger = log.scope("server");
@@ -311,6 +316,15 @@ export async function createServer(config: GrimoireConfig = {}) {
311
316
  handleFetch: hooksHandleFetch,
312
317
  } = await loadHooks(process.cwd());
313
318
 
319
+ // Resolved once at startup, not per request: services() may open a pool,
320
+ // and the object is immutable for the process lifetime, so building it
321
+ // inside handleRequest would open a connection per visitor.
322
+ //
323
+ // Before init(), so hooks.server.ts can use what plugins opened — a
324
+ // database for a warm-up query or a migration check is the usual case,
325
+ // and running init first meant it could only fail.
326
+ const services = await collectServices(plugins);
327
+
314
328
  // Run init hook if present
315
329
  await hooksInit?.();
316
330
 
@@ -331,6 +345,12 @@ export async function createServer(config: GrimoireConfig = {}) {
331
345
  const locals: App.Locals = rawLocals
332
346
  ? ((await runDeserializeLocals(plugins, rawLocals)) ?? {})
333
347
  : {};
348
+ // Plugin services sit under the request's own locals: what the app
349
+ // set (a session, a user) always wins over what a plugin declared,
350
+ // so a plugin cannot clobber auth by defining a common key.
351
+ for (const [key, value] of Object.entries(services)) {
352
+ if (!(key in locals)) locals[key] = value;
353
+ }
334
354
  const url = new URL(req.url);
335
355
 
336
356
  if (dev && url.pathname === "/__grimoire__/hmr") {
@@ -39,6 +39,41 @@ export async function runHook<K extends FireAndForgetHook>(
39
39
  }
40
40
  }
41
41
 
42
+ /**
43
+ * Collect `services()` from every plugin, merged in plugin order.
44
+ *
45
+ * Called once at startup and cached by the caller: the result is shared by
46
+ * every request. `services` is a fire-and-forget hook, so it is kept out of
47
+ * HookArgs on purpose — its return value is used, unlike every other entry
48
+ * in that map.
49
+ *
50
+ * Each plugin is handed what the plugins before it already published, so a
51
+ * plugin can build on a resource another one owns. The SQL plugin opening the
52
+ * connection and a jobs plugin writing rows through it is the case that
53
+ * matters: without this, every consumer opens a second pool and the worker
54
+ * budget is split again by whoever registered first.
55
+ *
56
+ * The context is a snapshot, so a plugin registered before the one it needs
57
+ * sees nothing and reports that. It does not see its own contribution, and
58
+ * it cannot write into the result — a plugin that wants to publish does so by
59
+ * returning, which is what keeps the merge order predictable.
60
+ */
61
+ export async function collectServices(
62
+ plugins: GrimoirePlugin[],
63
+ ): Promise<Record<string, unknown>> {
64
+ const collected: Record<string, unknown> = {};
65
+ for (const plugin of plugins) {
66
+ if (!plugin.services) continue;
67
+ const provided = await plugin.services({ services: { ...collected } });
68
+ if (!provided) continue;
69
+ for (const [key, value] of Object.entries(provided)) {
70
+ if (value === undefined) continue;
71
+ collected[key] = value;
72
+ }
73
+ }
74
+ return collected;
75
+ }
76
+
42
77
  export async function runRequestHooks(
43
78
  plugins: GrimoirePlugin[],
44
79
  req: Request,
package/src/types.ts CHANGED
@@ -82,18 +82,92 @@ export interface PluginContext {
82
82
  logger: ScopedLogger;
83
83
  }
84
84
 
85
+ /**
86
+ * Which worker this process is, and how many there are.
87
+ *
88
+ * A plugin that creates one resource per worker — a connection pool, an
89
+ * embedded database handle — needs both numbers to divide a global budget
90
+ * correctly. `maxConnections: 20` across 4 workers is 5 each; a plugin that
91
+ * only knows its own index has no way to work that out and quietly opens 80.
92
+ *
93
+ * The coordinator sets both as env vars at spawn, so this resolves in a
94
+ * worker process. Running without a coordinator (`sigil dev`, or a single
95
+ * process) is one worker of one, which is the honest answer rather than a
96
+ * guess.
97
+ */
98
+ export interface WorkerContext {
99
+ /** 0-based within this mode. 0 when there is no coordinator. */
100
+ workerId: number;
101
+ /** Total workers across all modes. At least 1. */
102
+ workers: number;
103
+ /** Whether the server is in development mode. */
104
+ dev: boolean;
105
+ }
106
+
107
+ export function workerContext(env: Record<string, string | undefined> = process.env): WorkerContext {
108
+ const parsed = Number(env.GRIMOIRE_WORKER_INDEX);
109
+ const count = Number(env.GRIMOIRE_WORKER_COUNT);
110
+ return {
111
+ // A NaN here means no coordinator set them, which is one worker.
112
+ workerId: Number.isFinite(parsed) && parsed > 0 ? parsed - 1 : 0,
113
+ // Never 0: a budget divided by zero is Infinity, and a pool of
114
+ // Infinity is a crash at the first connection.
115
+ workers: Number.isFinite(count) && count > 0 ? count : 1,
116
+ dev: env.GRIMOIRE_MODE === "development",
117
+ };
118
+ }
119
+
85
120
  export interface BuildResult {
86
121
  success: boolean;
87
122
  outputs: string[];
88
123
  errors: string[];
89
124
  }
90
125
 
126
+ export interface ServicesContext {
127
+ /**
128
+ * What the plugins before this one published, keyed the same way it will
129
+ * appear on `locals`. A snapshot: mutating it changes nothing.
130
+ */
131
+ services: Record<string, unknown>;
132
+ }
133
+
91
134
  export interface GrimoirePlugin {
92
135
  name: string;
93
136
 
94
137
  // plugin lifecycle
95
138
  onPluginsResolved?(ctx: PluginContext): void | Promise<void>;
96
139
 
140
+ /**
141
+ * Expose values on `locals` for the whole app to use.
142
+ *
143
+ * Returns an object merged into the per-request `locals` before any
144
+ * route, load, action or +server.ts handler runs, so a route reaches it
145
+ * as `locals.<key>` with nothing imported and nothing exported from
146
+ * sigil.config.ts.
147
+ *
148
+ * The merge is shallow and runs in plugin order, so a later plugin
149
+ * overriding an earlier plugin's key wins — same rule as every other
150
+ * merge in the pipeline. It is collected once, at startup, and the same
151
+ * values are merged into every request, so a request-scoped value here
152
+ * is a mistake.
153
+ *
154
+ * This is the place to open a connection pool. It runs only where
155
+ * requests are served — `sigil dev` and each `sigil start` worker, not
156
+ * the coordinator or `sigil build`, which do run `config()` — and before
157
+ * hooks.server.ts `init()`, so `init` can use what it opened.
158
+ *
159
+ * `ctx.services` is what the plugins before this one published, so a
160
+ * plugin can build on a resource another plugin owns instead of opening
161
+ * a second one. Register the SQL plugin first and a consumer reads
162
+ * `ctx.services.db` — the same client, not a parallel pool.
163
+ *
164
+ * It is a snapshot taken before this plugin runs, so a plugin registered
165
+ * before the one it needs sees nothing. Plugins that must not depend on
166
+ * ordering should fail loudly when the key is absent rather than quietly
167
+ * open their own fallback.
168
+ */
169
+ services?(ctx: ServicesContext): Record<string, unknown> | Promise<Record<string, unknown>>;
170
+
97
171
  // server lifecycle
98
172
  // we dont care about what the impl puts as websocket data therefore unknown.
99
173
  onStart?(server: Server<unknown>): void | Promise<void>;
@@ -22,6 +22,8 @@ describe("coordinator", () => {
22
22
  ' message(ws, data) { ws.send("echo:" + data); },',
23
23
  "};",
24
24
  "export function GET({ request }) {",
25
+ ' if (new URL(request.url).searchParams.has("nav"))',
26
+ ' return new Response(request.headers.get("x-grimoire-navigate") ?? "none");',
25
27
  ' return new Response(request.headers.get("cookie") ?? "no cookie");',
26
28
  "}",
27
29
  ].join("\n"),
@@ -55,6 +57,13 @@ describe("coordinator", () => {
55
57
  expect(res.status).toBe(200);
56
58
  });
57
59
 
60
+ test("client-side navigation reaches the worker with its header", async () => {
61
+ const res = await fetch(`http://127.0.0.1:${port}/echo?nav`, {
62
+ headers: { "x-grimoire-navigate": "1" },
63
+ });
64
+ expect(await res.text()).toBe("1");
65
+ });
66
+
58
67
  test("relays WebSockets, including a message sent right on open", async () => {
59
68
  const ws = new WebSocket(`ws://127.0.0.1:${port}/echo`);
60
69
  const got: string[] = [];