@sigil-dev/grimoire 0.7.6 → 0.8.0

package/src/types.ts

@@ -1,269 +1,270 @@
-import type { ServerWebSocket } from "bun";
-import type { RouteFile, RouteTree } from "./routing/scanner";
-
-/// <reference types="bun-types">
-declare global {
-	namespace App {
-		// augment in your own project via src/app.d.ts
-		interface Locals {}
-		interface Error {
-			message: string;
-			status?: number;
-		}
-		interface PageData {}
-		interface Platform {}
-	}
-}
-
-export interface Route {
-	path: string; // /blog/:slug
-	params: Record<string, string>;
-	filePath: string; // absolute path to +page.tsx
-	loadPath?: string; // absolute path to +page.ts
-	serverPath?: string; // absolute path to +server.ts
-	layoutPath?: string; // absolute path to +layout.tsx
-}
-
-export interface RouteInfo {
-	path: string; // /blog/:slug
-	filePath: string; // absolute path
-	type: string; // page, layout etc
-}
-
-export interface LoadContext {
-	request: Request;
-	params: Record<string, string>;
-	url: URL;
-	locals: Record<string, unknown>; // set by plugins/hooks
-}
-
-export interface TypedLoadContext<
-	P extends Record<string, string> = Record<string, string>,
-> {
-	request: Request;
-	params: P;
-	url: URL;
-	locals: App.Locals;
-}
-
-export interface RenderContext {
-	route: RouteInfo;
-	request: Request;
-	params: Record<string, string>;
-	data: unknown; // return value of load()
-}
-
-export interface BuildResult {
-	success: boolean;
-	outputs: string[];
-	errors: string[];
-}
-export type Server = { port: number; hostname: string; stop(): void };
-
-export interface GrimoirePlugin {
-	name: string;
-
-	// server lifecycle
-	onStart?(server: Server): void | Promise<void>;
-	onStop?(reason: "shutdown" | "restart"): void | Promise<void>;
-
-	// request pipeline
-	onRequest?(
-		req: Request,
-		next: () => Promise<Response>,
-	): Response | Promise<Response>;
-
-	// route lifecycle
-	onRouteLoad?(route: Route, context: LoadContext): void | Promise<void>;
-	/**
-	 * Called after the page HTML is fully rendered.
-	 * NOTE: When any plugin implements this hook, the streaming response is
-	 * buffered into a single string. Streaming is preserved for routes where
-	 * no plugin uses this hook. To avoid buffering, use onRequest to intercept
-	 * at the Response level.
-	 */
-	onRouteRender?(
-		html: string,
-		context: RenderContext,
-	): string | Promise<string>;
-
-	// build
-	onBuildStart?(): void | Promise<void>;
-	onBuildEnd?(result: BuildResult): void | Promise<void>;
-
-	// config
-	config?: (config: GrimoireConfig) => GrimoireConfig | undefined;
-
-	// process lifecycle
-
-	/**
-	 * Runs AFTER Sigil/Babel compilation. Receives compiled JS, not source TSX.
-	 * Suitable for string-level transforms (import rewriting, comment injection, etc.).
-	 * Return null/undefined to pass through unchanged.
-	 */
-	transform?(
-		code: string,
-		id: string,
-	): string | null | undefined | Promise<string | null | undefined>;
-
-	/**
-	 * Fires once after all workers are spawned and ready.
-	 * Use for coordinator-level setup (e.g. opening a shared store).
-	 */
-	onCoordinatorStart?(ctx: CoordinatorContext): void | Promise<void>;
-
-	/**
-	 * Fires for each worker before Bun.spawn is called.
-	 * Return WorkerEnv to inject env vars or set the worker name.
-	 * ALL plugins are called and results are merged.
-	 */
-	// biome-ignore lint/suspicious/noConfusingVoidType: doesn't have to return a thing.
-	onWorkerSpawn?(
-		worker: WorkerDescriptor,
-	): WorkerEnv | void | Promise<WorkerEnv | void>;
-
-	/**
-	 * Fires when a worker process is up and accepting requests.
-	 */
-	onWorkerReady?(worker: WorkerDescriptor): void | Promise<void>;
-
-	/**
-	 * Fires when a worker process exits.
-	 * reason "crash" = unexpected exit, "intentional" = coordinator stopped it.
-	 * Use for cleanup or respawn logic (see plugin-scale).
-	 */
-	onWorkerDeath?(
-		worker: WorkerDescriptor,
-		reason: "crash" | "intentional",
-	): void | Promise<void>;
-
-	// ── Locals boundary ────────────────────────────────────────
-
-	/**
-	 * Called by coordinator before forwarding a request to a worker.
-	 * Return a serialized string representation of locals.
-	 * First plugin to return non-null wins. Default: signed JSON header.
-	 */
-	serializeLocals?(locals: App.Locals): string | Promise<string>;
-
-	/**
-	 * Called by worker on receiving a forwarded request.
-	 * Return the deserialized locals object.
-	 * First plugin to return non-null wins. Default: verify + JSON.parse.
-	 */
-	deserializeLocals?(raw: string): App.Locals | Promise<App.Locals>;
-
-	// ── Routing policy ─────────────────────────────────────────
-
-	/**
-	 * Called by coordinator to decide which worker handles a request.
-	 * First plugin to return non-null wins.
-	 * Default: ws routes → consistent hash, everything else → round robin.
-	 * routes is the full RouteTree so plugins can make route-aware decisions.
-	 */
-	routeRequest?(
-		req: Request,
-		workers: WorkerDescriptor[],
-		routes: RouteTree,
-	): WorkerDescriptor | Promise<WorkerDescriptor>;
-}
-
-export interface GrimoireConfig {
-	port?: number;
-	host?: string;
-	plugins?: GrimoirePlugin[];
-	routes?: string; // glob, default 'src/routes/**';
-	dev?: boolean;
-	vitePort?: number;
-	alias?: Record<string, string>; // e.g. { "$lib": "src/lib" } — resolved relative to cwd
-	cspNonce?: string; // CSP nonce for <script>/<style> tags
-	bundleStrategy?: "split" | "single"; // 'split' (default) or 'single' bundle
-	_skipBuild?: boolean;
-}
-
-export function defineConfig(config: GrimoireConfig): GrimoireConfig {
-	return config;
-}
-
-/** Generic load type for +page.server.ts. For per-route typed params import PageServerLoad from './$types'. */
-export type PageServerLoad<
-	P extends Record<string, string> = Record<string, string>,
-> = (
-	ctx: TypedLoadContext<P>,
-) => Record<string, unknown> | Promise<Record<string, unknown>>;
-
-/** Generic load type for +layout.server.ts. For per-route typed params import LayoutServerLoad from './$types'. */
-export type LayoutServerLoad<
-	P extends Record<string, string> = Record<string, string>,
-> = (
-	ctx: TypedLoadContext<P>,
-) => Record<string, unknown> | Promise<Record<string, unknown>>;
-
-/** Generic handler type for +server.ts API routes. For per-route typed params import RequestHandler from './$types'. */
-export type RequestHandler<
-	P extends Record<string, string> = Record<string, string>,
-> = (ctx: TypedLoadContext<P>) => Response | Promise<Response>;
-
-/**
- * Shape of the `websocket` export in a +server.ts file.
- * T is the resolved ws.data shape (params + upgrade() return value).
- * For per-route typing import WebSocketHandler from './$types'.
- */
-export interface WsRouteHandler<T = Record<string, unknown>> {
-	open?(ws: ServerWebSocket<T>): void | Promise<void>;
-	message?(ws: ServerWebSocket<T>, data: string | Buffer): void | Promise<void>;
-	close?(
-		ws: ServerWebSocket<T>,
-		code: number,
-		reason?: string,
-	): void | Promise<void>;
-	drain?(ws: ServerWebSocket<T>): void | Promise<void>;
-}
-
-// ***BIG ONE***
-
-/**
- * Built-in worker modes understood by the coordinator.
- * Plugins may define custom modes via WorkerMode.
- */
-export type BuiltinWorkerMode = "api" | "frontend" | "ws" | "full";
-
-/**
- * Open union — (string & {}) preserves autocomplete for built-in
- * values while allowing plugin-defined modes like "db" or "queue".
- */
-export type WorkerMode = BuiltinWorkerMode | (string & {});
-
-/**
- * Describes a single worker process managed by the coordinator.
- * Coordinator derives behavior from routes, not mode string —
- * mode is informational and for plugin use only.
- */
-export interface WorkerDescriptor {
-	mode: WorkerMode;
-	index: number; // index within this mode (api-0, api-1...)
-	globalIndex: number; // index across all workers
-	internalUrl: string; // coordinator → worker base URL
-	name?: string; // set by namepool or onWorkerSpawn
-	routes: RouteFile[]; // route slice assigned by coordinator
-	pid?: number; // set after Bun.spawn
-}
-
-/**
- * Return value of onWorkerSpawn. All plugins are called and results
- * are merged — env from all plugins is combined, last name wins.
- */
-export interface WorkerEnv {
-	env?: Record<string, string>;
-	name?: string;
-}
-
-/**
- * Passed to onCoordinatorStart once the coordinator is fully initialized.
- */
-export interface CoordinatorContext {
-	workers: WorkerDescriptor[];
-	port: number;
-	secret: string; // ephemeral signing secret, generated per-run
-	routes: RouteTree;
-}
+import type { ServerWebSocket } from "bun";
+import type { RouteFile, RouteTree } from "./routing/scanner";
+
+/// <reference types="bun-types">
+declare global {
+	namespace App {
+		// augment in your own project via src/app.d.ts
+		interface Locals {}
+		interface Error {
+			message: string;
+			status?: number;
+		}
+		interface PageData {}
+		interface Platform {}
+	}
+}
+
+export interface Route {
+	path: string; // /blog/:slug
+	params: Record<string, string>;
+	filePath: string; // absolute path to +page.tsx
+	loadPath?: string; // absolute path to +page.ts
+	serverPath?: string; // absolute path to +server.ts
+	layoutPath?: string; // absolute path to +layout.tsx
+}
+
+export interface RouteInfo {
+	path: string; // /blog/:slug
+	filePath: string; // absolute path
+	type: string; // page, layout etc
+}
+
+export interface LoadContext {
+	request: Request;
+	params: Record<string, string>;
+	url: URL;
+	locals: Record<string, unknown>; // set by plugins/hooks
+}
+
+export interface TypedLoadContext<
+	P extends Record<string, string> = Record<string, string>,
+> {
+	request: Request;
+	params: P;
+	url: URL;
+	locals: App.Locals;
+}
+
+export interface RenderContext {
+	route: RouteInfo;
+	request: Request;
+	params: Record<string, string>;
+	data: unknown; // return value of load()
+}
+
+export interface BuildResult {
+	success: boolean;
+	outputs: string[];
+	errors: string[];
+}
+export type Server = { port: number; hostname: string; stop(): void };
+
+export interface GrimoirePlugin {
+	name: string;
+
+	// server lifecycle
+	onStart?(server: Server): void | Promise<void>;
+	onStop?(reason: "shutdown" | "restart"): void | Promise<void>;
+
+	// request pipeline
+	onRequest?(
+		req: Request,
+		next: () => Promise<Response>,
+	): Response | Promise<Response>;
+
+	// route lifecycle
+	onRouteLoad?(route: Route, context: LoadContext): void | Promise<void>;
+	/**
+	 * Called after the page HTML is fully rendered.
+	 * NOTE: When any plugin implements this hook, the streaming response is
+	 * buffered into a single string. Streaming is preserved for routes where
+	 * no plugin uses this hook. To avoid buffering, use onRequest to intercept
+	 * at the Response level.
+	 */
+	onRouteRender?(
+		html: string,
+		context: RenderContext,
+	): string | Promise<string>;
+
+	// build
+	onBuildStart?(): void | Promise<void>;
+	onBuildEnd?(result: BuildResult): void | Promise<void>;
+
+	// config
+	config?: (config: GrimoireConfig) => GrimoireConfig | undefined;
+
+	// process lifecycle
+
+	/**
+	 * Runs AFTER Sigil/Babel compilation. Receives compiled JS, not source TSX.
+	 * Suitable for string-level transforms (import rewriting, comment injection, etc.).
+	 * Return null/undefined to pass through unchanged.
+	 */
+	transform?(
+		code: string,
+		id: string,
+	): string | null | undefined | Promise<string | null | undefined>;
+
+	/**
+	 * Fires once after all workers are spawned and ready.
+	 * Use for coordinator-level setup (e.g. opening a shared store).
+	 */
+	onCoordinatorStart?(ctx: CoordinatorContext): void | Promise<void>;
+
+	/**
+	 * Fires for each worker before Bun.spawn is called.
+	 * Return WorkerEnv to inject env vars or set the worker name.
+	 * ALL plugins are called and results are merged.
+	 */
+	onWorkerSpawn?(
+		worker: WorkerDescriptor,
+		// biome-ignore lint/suspicious/noConfusingVoidType: doesn't have to return a thing.
+	): WorkerEnv | void | Promise<WorkerEnv | void>;
+
+	/**
+	 * Fires when a worker process is up and accepting requests.
+	 */
+	onWorkerReady?(worker: WorkerDescriptor): void | Promise<void>;
+
+	/**
+	 * Fires when a worker process exits.
+	 * reason "crash" = unexpected exit, "intentional" = coordinator stopped it.
+	 * Use for cleanup or respawn logic (see plugin-scale).
+	 */
+	onWorkerDeath?(
+		worker: WorkerDescriptor,
+		reason: "crash" | "intentional",
+	): void | Promise<void>;
+
+	// ── Locals boundary ────────────────────────────────────────
+
+	/**
+	 * Called by coordinator before forwarding a request to a worker.
+	 * Return a serialized string representation of locals.
+	 * First plugin to return non-null wins. Default: signed JSON header.
+	 */
+	serializeLocals?(locals: App.Locals): string | Promise<string>;
+
+	/**
+	 * Called by worker on receiving a forwarded request.
+	 * Return the deserialized locals object.
+	 * First plugin to return non-null wins. Default: verify + JSON.parse.
+	 */
+	deserializeLocals?(raw: string): App.Locals | Promise<App.Locals>;
+
+	// ── Routing policy ─────────────────────────────────────────
+
+	/**
+	 * Called by coordinator to decide which worker handles a request.
+	 * First plugin to return non-null wins.
+	 * Default: ws routes → consistent hash, everything else → round robin.
+	 * routes is the full RouteTree so plugins can make route-aware decisions.
+	 */
+	routeRequest?(
+		req: Request,
+		workers: WorkerDescriptor[],
+		routes: RouteTree,
+	): WorkerDescriptor | Promise<WorkerDescriptor>;
+}
+
+export interface GrimoireConfig {
+	port?: number;
+	host?: string;
+	plugins?: GrimoirePlugin[];
+	routes?: string; // glob, default 'src/routes/**';
+	dev?: boolean;
+	devEditor?: boolean;
+	vitePort?: number;
+	alias?: Record<string, string>; // e.g. { "$lib": "src/lib" } — resolved relative to cwd
+	cspNonce?: string; // CSP nonce for <script>/<style> tags
+	bundleStrategy?: "split" | "single"; // 'split' (default) or 'single' bundle
+	_skipBuild?: boolean;
+}
+
+export function defineConfig(config: GrimoireConfig): GrimoireConfig {
+	return config;
+}
+
+/** Generic load type for +page.server.ts. For per-route typed params import PageServerLoad from './$types'. */
+export type PageServerLoad<
+	P extends Record<string, string> = Record<string, string>,
+> = (
+	ctx: TypedLoadContext<P>,
+) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Generic load type for +layout.server.ts. For per-route typed params import LayoutServerLoad from './$types'. */
+export type LayoutServerLoad<
+	P extends Record<string, string> = Record<string, string>,
+> = (
+	ctx: TypedLoadContext<P>,
+) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Generic handler type for +server.ts API routes. For per-route typed params import RequestHandler from './$types'. */
+export type RequestHandler<
+	P extends Record<string, string> = Record<string, string>,
+> = (ctx: TypedLoadContext<P>) => Response | Promise<Response>;
+
+/**
+ * Shape of the `websocket` export in a +server.ts file.
+ * T is the resolved ws.data shape (params + upgrade() return value).
+ * For per-route typing import WebSocketHandler from './$types'.
+ */
+export interface WsRouteHandler<T = Record<string, unknown>> {
+	open?(ws: ServerWebSocket<T>): void | Promise<void>;
+	message?(ws: ServerWebSocket<T>, data: string | Buffer): void | Promise<void>;
+	close?(
+		ws: ServerWebSocket<T>,
+		code: number,
+		reason?: string,
+	): void | Promise<void>;
+	drain?(ws: ServerWebSocket<T>): void | Promise<void>;
+}
+
+// ***BIG ONE***
+
+/**
+ * Built-in worker modes understood by the coordinator.
+ * Plugins may define custom modes via WorkerMode.
+ */
+export type BuiltinWorkerMode = "api" | "frontend" | "ws" | "full";
+
+/**
+ * Open union — (string & {}) preserves autocomplete for built-in
+ * values while allowing plugin-defined modes like "db" or "queue".
+ */
+export type WorkerMode = BuiltinWorkerMode | (string & {});
+
+/**
+ * Describes a single worker process managed by the coordinator.
+ * Coordinator derives behavior from routes, not mode string —
+ * mode is informational and for plugin use only.
+ */
+export interface WorkerDescriptor {
+	mode: WorkerMode;
+	index: number; // index within this mode (api-0, api-1...)
+	globalIndex: number; // index across all workers
+	internalUrl: string; // coordinator → worker base URL
+	name?: string; // set by namepool or onWorkerSpawn
+	routes: RouteFile[]; // route slice assigned by coordinator
+	pid?: number; // set after Bun.spawn
+}
+
+/**
+ * Return value of onWorkerSpawn. All plugins are called and results
+ * are merged — env from all plugins is combined, last name wins.
+ */
+export interface WorkerEnv {
+	env?: Record<string, string>;
+	name?: string;
+}
+
+/**
+ * Passed to onCoordinatorStart once the coordinator is fully initialized.
+ */
+export interface CoordinatorContext {
+	workers: WorkerDescriptor[];
+	port: number;
+	secret: string; // ephemeral signing secret, generated per-run
+	routes: RouteTree;
+}

package/test/context.test.ts

@@ -1,52 +1,52 @@
-// packages/grimoire/src/context.test.ts
-import { describe, expect, test } from "bun:test";
-import { createContext, getContext, setContext } from "@sigil-dev/runtime";
-import { runWithContext } from "../src/server/context";
-
-const UserKey = createContext<string>();
-const ThemeKey = createContext<string>();
-
-// 1. Basic: does it work at all
-test("getContext returns value set in same context", async () => {
-	await runWithContext(async () => {
-		setContext(UserKey, "cane");
-		expect(getContext(UserKey)).toBe("cane");
-	});
-});
-
-// 2. Isolation: the whole point of AsyncLocalStorage
-test("concurrent requests do not bleed context", async () => {
-	let resolveA!: () => void;
-	let resolveB!: () => void;
-
-	const barrier = {
-		a: new Promise<void>((r) => (resolveA = r)),
-		b: new Promise<void>((r) => (resolveB = r)),
-	};
-
-	const requestA = runWithContext(async () => {
-		setContext(UserKey, "request-A");
-		await barrier.a; // suspend, let B run
-		// if context bleeds, this returns "request-B"
-		return getContext(UserKey);
-	});
-
-	const requestB = runWithContext(async () => {
-		setContext(UserKey, "request-B");
-		resolveA(); // wake A up
-		await barrier.b;
-		return getContext(UserKey);
-	});
-
-	resolveB();
-	const [a, b] = await Promise.all([requestA, requestB]);
-
-	expect(a).toBe("request-A"); // fails if bleed
-	expect(b).toBe("request-B");
-});
-
-// 3. Outside context: should not throw, returns undefined
-test("getContext outside runWithContext returns undefined gracefully", () => {
-	const val = getContext(UserKey);
-	expect(val).toBeUndefined();
-});
+// packages/grimoire/src/context.test.ts
+import { describe, expect, test } from "bun:test";
+import { createContext, getContext, setContext } from "@sigil-dev/runtime";
+import { runWithContext } from "../src/server/context";
+
+const UserKey = createContext<string>();
+const ThemeKey = createContext<string>();
+
+// 1. Basic: does it work at all
+test("getContext returns value set in same context", async () => {
+	await runWithContext(async () => {
+		setContext(UserKey, "cane");
+		expect(getContext(UserKey)).toBe("cane");
+	});
+});
+
+// 2. Isolation: the whole point of AsyncLocalStorage
+test("concurrent requests do not bleed context", async () => {
+	let resolveA!: () => void;
+	let resolveB!: () => void;
+
+	const barrier = {
+		a: new Promise<void>((r) => (resolveA = r)),
+		b: new Promise<void>((r) => (resolveB = r)),
+	};
+
+	const requestA = runWithContext(async () => {
+		setContext(UserKey, "request-A");
+		await barrier.a; // suspend, let B run
+		// if context bleeds, this returns "request-B"
+		return getContext(UserKey);
+	});
+
+	const requestB = runWithContext(async () => {
+		setContext(UserKey, "request-B");
+		resolveA(); // wake A up
+		await barrier.b;
+		return getContext(UserKey);
+	});
+
+	resolveB();
+	const [a, b] = await Promise.all([requestA, requestB]);
+
+	expect(a).toBe("request-A"); // fails if bleed
+	expect(b).toBe("request-B");
+});
+
+// 3. Outside context: should not throw, returns undefined
+test("getContext outside runWithContext returns undefined gracefully", () => {
+	const val = getContext(UserKey);
+	expect(val).toBeUndefined();
+});