@c9up/aurora 0.1.38 → 0.1.40

package/src/render.ts

@@ -31,6 +31,42 @@ import {
 
 export type Disposer = () => void;
 
+/**
+ * The `onMount` hooks collected while a tree is built, and whether they have
+ * already been run.
+ *
+ * A bare array was not enough. The root flushes it once, after the fragment is
+ * in the document; a reactive slot that swapped its content LATER kept
+ * appending to that same array, and nothing flushed it again — the component's
+ * setup ran, its `onMount` never did, and the hooks piled up for the life of
+ * the page. The flag is what lets a later update tell "collect these, the root
+ * will run them" from "the root is done, run mine myself".
+ */
+interface MountQueue {
+	hooks: Array<EffectCallback>;
+	flushed: boolean;
+}
+
+/**
+ * Run hooks, sending any teardown to `cleanups`.
+ *
+ * Failures are swallowed per hook: one component's bad `onMount` must not stop
+ * its siblings from mounting.
+ */
+function runMountHooks(
+	hooks: Array<EffectCallback>,
+	cleanups: Disposer[],
+): void {
+	for (const hook of hooks) {
+		try {
+			const teardown = hook();
+			if (typeof teardown === "function") cleanups.push(teardown);
+		} catch {
+			/* swallow — one bad onMount should not block sibling components */
+		}
+	}
+}
+
 /**
  * Mount a TemplateResult into `container`. Returns a `Disposer` that
  * stops every reactive effect and removes the mounted nodes. Calling it
@@ -42,22 +78,19 @@ export function render(
 ): Disposer {
 	const cleanups: Disposer[] = [];
 	const mountedNodes: ChildNode[] = [];
-	const mountHooks: Array<EffectCallback> = [];
+	const queue: MountQueue = { hooks: [], flushed: false };
 
-	const fragment = mount(result, cleanups, mountedNodes, mountHooks);
+	const fragment = mount(result, cleanups, mountedNodes, queue);
 	container.appendChild(fragment);
 
 	// `onMount` hooks fire after the fragment is live in the document so
 	// callbacks that measure / focus / observe see a real DOM. A returned
 	// cleanup function joins the unmount queue.
-	for (const hook of mountHooks) {
-		try {
-			const teardown = hook();
-			if (typeof teardown === "function") cleanups.push(teardown);
-		} catch {
-			/* swallow — one bad onMount should not block sibling components */
-		}
-	}
+	runMountHooks(queue.hooks, cleanups);
+	queue.hooks = [];
+	// From here on the root never flushes again, so a slot that mounts
+	// something later has to run its own hooks.
+	queue.flushed = true;
 
 	let disposed = false;
 	return () => {
@@ -92,7 +125,7 @@ export function mount(
 	result: TemplateResult,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): DocumentFragment {
 	const tpl = getTemplate(result.strings);
 	const fragment = tpl.element.content.cloneNode(true) as DocumentFragment;
@@ -100,7 +133,7 @@ export function mount(
 	// Forward any component()-attached lifecycle from this result.
 	const lifecycle = readComponentLifecycle(result);
 	if (lifecycle) {
-		for (const hook of lifecycle.mountHooks) mountHooks.push(hook);
+		for (const hook of lifecycle.mountHooks) queue.hooks.push(hook);
 		for (const c of lifecycle.cleanups) cleanups.push(c);
 	}
 
@@ -148,7 +181,7 @@ export function mount(
 		if (slot.kind === "attr" && slot.staticParts !== undefined) {
 			collectMultiAttr(slot, node as Element, result.values[i], multiGroups);
 		} else {
-			applySlot(slot, node, result.values[i], cleanups, mounted, mountHooks);
+			applySlot(slot, node, result.values[i], cleanups, mounted, queue);
 		}
 	}
 
@@ -185,18 +218,11 @@ function applySlot(
 	value: unknown,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): void {
 	switch (slot.kind) {
 		case "text":
-			applyTextSlot(
-				slot,
-				node as Comment,
-				value,
-				cleanups,
-				mounted,
-				mountHooks,
-			);
+			applyTextSlot(slot, node as Comment, value, cleanups, mounted, queue);
 			return;
 		case "attr":
 			applyAttrSlot(slot, node as Element, value, cleanups);
@@ -225,7 +251,7 @@ function applyTextSlot(
 	value: unknown,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): void {
 	let currentNodes: ChildNode[] = [];
 	// Per-render disposers for whatever the slot currently shows. A
@@ -246,18 +272,36 @@ function applyTextSlot(
 		disposeLocal();
 		for (const n of currentNodes) n.remove();
 		currentNodes = [];
-		const nodes = renderValueIntoNodes(
-			newValue,
-			localCleanups,
-			mounted,
-			mountHooks,
-		);
+		// This render's hooks are collected apart from the shared queue,
+		// whichever phase we are in, because their TEARDOWNS belong to this
+		// slot: the next swap must dispose what it replaces. Left on the root's
+		// list, a component mounted per row kept its subscription until the
+		// whole page unmounted.
+		//
+		// `flushed` is inherited so a deeper slot built during this render
+		// still knows whether the root has a flush coming.
+		const own: MountQueue = { hooks: [], flushed: queue.flushed };
+		const nodes = renderValueIntoNodes(newValue, localCleanups, mounted, own);
 		const parent = anchor.parentNode;
 		if (!parent) return;
 		for (const n of nodes) {
 			parent.insertBefore(n, anchor);
 			currentNodes.push(n);
 		}
+		if (queue.flushed) {
+			// After insertion, exactly as at the root: an `onMount` that
+			// measures, focuses or observes has to see a live node.
+			runMountHooks(own.hooks, localCleanups);
+			return;
+		}
+		// Still building the initial tree: the nodes are in a detached
+		// fragment, so defer to the root's flush. One wrapper carries them, and
+		// it returns nothing — the real teardowns go to `localCleanups`, not to
+		// the root.
+		const pending = own.hooks;
+		queue.hooks.push(() => {
+			runMountHooks(pending.splice(0), localCleanups);
+		});
 	}
 
 	if (isSignal(value) || typeof value === "function") {
@@ -282,18 +326,18 @@ function renderValueIntoNodes(
 	value: unknown,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): ChildNode[] {
 	if (value === null || value === undefined || value === false) return [];
 	if (Array.isArray(value)) {
 		const out: ChildNode[] = [];
 		for (const item of value) {
-			out.push(...renderValueIntoNodes(item, cleanups, mounted, mountHooks));
+			out.push(...renderValueIntoNodes(item, cleanups, mounted, queue));
 		}
 		return out;
 	}
 	if (isTemplateResult(value)) {
-		const frag = mount(value, cleanups, mounted, mountHooks);
+		const frag = mount(value, cleanups, mounted, queue);
 		return Array.from(frag.childNodes);
 	}
 	if (value instanceof Node) {

package/src/server/renderPage.ts

@@ -25,6 +25,7 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 import { setCookieStoreReader } from "../browser.js";
+import { AuroraError } from "../errors.js";
 import type { Pages } from "../Pages.js";
 import { renderToString } from "../ssr.js";
 import { setRouteManifestReader } from "../url.js";
@@ -331,7 +332,10 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 
 function normalizeRootTag(tag: string): string {
 	if (/^[a-z][a-z0-9-]*$/i.test(tag)) return tag.toLowerCase();
-	throw new Error(`[aurora] illegal root tag: ${JSON.stringify(tag)}`);
+	throw new AuroraError(
+		"E_AURORA_ILLEGAL_ROOT_TAG",
+		`[aurora] illegal root tag: ${JSON.stringify(tag)}`,
+	);
 }
 
 function rootAttrs(id: string, className: string | undefined): string {

package/src/server/serveAssets.ts

@@ -10,6 +10,7 @@
  * `AssetsHttpContext` (Ream, AdonisJS, anything duck-typed) works.
  */
 
+import { createHash } from "node:crypto";
 import { readFile, realpath } from "node:fs/promises";
 import { dirname, extname, join, resolve as resolvePath, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -28,6 +29,27 @@ export function packageAssetDir(specifier: string): string {
 	return dirname(fileURLToPath(import.meta.resolve(specifier)));
 }
 
+/**
+ * Does `If-None-Match` cover this entity? (RFC 9110 §13.1.2)
+ *
+ * A strict `===` answered 200 for three shapes a real client sends: `*`, a
+ * comma-separated list of tags, and the weak form `W/"…"` — so a browser
+ * holding the exact bytes re-downloaded them anyway, which is most of what the
+ * validator exists to prevent. Written here rather than imported because aurora
+ * does not depend on ream; the same function lives in `ream/src/http/etag.ts`.
+ */
+function matchesIfNoneMatch(header: string | undefined, tag: string): boolean {
+	if (header === undefined || header === "" || tag === "") return false;
+	// `*` means "any current representation", so a stored copy always matches.
+	if (header.trim() === "*") return true;
+	const bare = (value: string): string =>
+		value.startsWith("W/") ? value.slice(2) : value;
+	const current = bare(tag);
+	return header
+		.split(",")
+		.some((candidate) => bare(candidate.trim()) === current);
+}
+
 const CONTENT_TYPES: Record<string, string> = {
 	".js": "text/javascript; charset=utf-8",
 	".mjs": "text/javascript; charset=utf-8",
@@ -44,6 +66,12 @@ export interface AssetsRequest {
 	 * convention.
 	 */
 	param(name: string): unknown;
+	/**
+	 * Read a request header. OPTIONAL, so a host that only implements
+	 * `param()` keeps working: without it there is no conditional request and
+	 * every response is a full 200, which is what happened before.
+	 */
+	header?(name: string): string | undefined;
 }
 export interface AssetsResponse {
 	status(code: number): AssetsResponse;
@@ -65,6 +93,10 @@ export interface ServeAssetsOptions {
 	 * `Cache-Control` value to emit. Defaults to a dev-friendly
 	 * 60-second TTL. Production deployments should hash the asset
 	 * name and switch to `public, max-age=31536000, immutable`.
+	 *
+	 * Note that a TTL alone tells the browser not to ASK for 60 seconds. Pair
+	 * it with `no-cache` while developing — the ETag below then makes the
+	 * revalidation nearly free.
 	 */
 	cacheControl?: string;
 }
@@ -144,10 +176,26 @@ export function serveAssets(
 			return;
 		}
 
+		// A validator, so a cached copy can be CHECKED rather than only trusted
+		// for a fixed time. Without one an edited module was served stale for
+		// the whole TTL with no way for the browser to ask whether it changed —
+		// in development that is a source file, and the answer is usually yes.
+		//
+		// Hashed from the bytes actually being sent rather than from mtime and
+		// size: a checkout, a rebuild or a touched file all move the metadata
+		// without changing the content, and each would needlessly re-download.
+		const etag = `"${createHash("sha1").update(body).digest("base64url")}"`;
 		const type =
 			CONTENT_TYPES[extname(canonicalAbsolute)] ?? "application/octet-stream";
 		ctx.response.header("content-type", type);
 		ctx.response.header("cache-control", cacheControl);
+		ctx.response.header("etag", etag);
+		if (matchesIfNoneMatch(ctx.request.header?.("if-none-match"), etag)) {
+			// 304 carries no body, and must not: the browser reuses the copy it
+			// already has.
+			ctx.response.status(304).send("");
+			return;
+		}
 		ctx.response.send(body);
 	};
 }

package/src/server.ts

@@ -12,11 +12,18 @@
 import "./augmentations.js";
 
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
+export { AuroraError, type AuroraErrorCode } from "./errors.js";
 export {
 	type AuroraRequestRenderer,
 	auroraContext,
 } from "./middleware.js";
-export { type PageFactory, Pages, type PagesConfig } from "./Pages.js";
+export {
+	type PageFactory,
+	Pages,
+	type PagesConfig,
+	/** @internal classification seam, asserted by the tests */
+	pageImportError,
+} from "./Pages.js";
 export {
 	type RenderHttpContext,
 	type RenderPageOptions,

package/src/services/main.ts

@@ -11,6 +11,7 @@
  */
 
 import type { AuroraManager } from "../AuroraManager.js";
+import { AuroraError } from "../errors.js";
 
 let instance: AuroraManager | undefined;
 
@@ -48,7 +49,8 @@ const aurora: AuroraManager = new Proxy({} as AuroraManager, {
 			return undefined;
 		}
 		if (!instance) {
-			throw new Error(
+			throw new AuroraError(
+				"E_AURORA_NOT_BOOTED",
 				"[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +
 					"or `setAurora(myManager)` was called. Wire one of them first.",
 			);

package/src/url.ts

@@ -17,6 +17,8 @@
  * side. Node-free — part of aurora's client runtime.
  */
 
+import { AuroraError } from "./errors.js";
+
 let manifest: Record<string, string> = {};
 
 type RouteManifestReader = () => Record<string, string> | undefined;
@@ -65,7 +67,8 @@ export function urlFor(
 	const pattern = routes[name];
 	if (pattern === undefined) {
 		const known = Object.keys(routes);
-		throw new Error(
+		throw new AuroraError(
+			"E_AURORA_UNKNOWN_ROUTE",
 			`[aurora] urlFor: unknown route '${name}'. ${
 				known.length > 0
 					? `Known: ${known.join(", ")}`
@@ -91,7 +94,8 @@ export function urlFor(
 
 	const missing = url.match(/:[A-Za-z_][\w]*/g);
 	if (missing && missing.length > 0) {
-		throw new Error(
+		throw new AuroraError(
+			"E_AURORA_MISSING_ROUTE_PARAMS",
 			`[aurora] urlFor: route '${name}' is missing params ${missing.join(", ")}`,
 		);
 	}