@c9up/inker 0.1.3

package/src/InkerRenderError.ts

@@ -0,0 +1,49 @@
+export type InkerErrorCode =
+	| "E_INKER_TEMPLATE_NOT_FOUND"
+	| "E_INKER_PARSE_ERROR"
+	| "E_INKER_UNKNOWN_IDENTIFIER"
+	| "E_INKER_INVALID_PATH"
+	| "E_INKER_UNCLOSED_INTERPOLATION"
+	| "E_INKER_UNCLOSED_BLOCK_TAG"
+	| "E_INKER_UNKNOWN_DIRECTIVE"
+	| "E_INKER_INVALID_LAYOUT_POSITION"
+	| "E_INKER_DUPLICATE_LAYOUT"
+	| "E_INKER_NESTED_LAYOUT_UNSUPPORTED"
+	| "E_INKER_LAYOUT_IN_PARTIAL"
+	| "E_INKER_CIRCULAR_INCLUDE"
+	| "E_INKER_MISSING_SLOT"
+	| "E_INKER_UNKNOWN_SLOT"
+	| "E_INKER_DISK_REQUIRED"
+	| "E_INKER_UNCLOSED_BLOCK"
+	| "E_INKER_UNMATCHED_BLOCK_END"
+	| "E_INKER_MISMATCHED_BLOCK_END"
+	| "E_INKER_INVALID_EXPRESSION"
+	| "E_INKER_INVALID_ITERABLE"
+	| "E_INKER_UNKNOWN_HELPER"
+	| "E_INKER_HELPER_THROW"
+	| "E_INKER_NAPI_REQUIRED";
+
+export interface InkerErrorContext {
+	readonly templatePath?: string;
+	readonly templateName?: string;
+	readonly line?: number;
+	readonly column?: number;
+	readonly expression?: string;
+}
+
+export class InkerRenderError extends Error {
+	readonly code: InkerErrorCode;
+	readonly context: Readonly<InkerErrorContext>;
+
+	constructor(
+		code: InkerErrorCode,
+		message: string,
+		context?: InkerErrorContext,
+		options?: { cause?: unknown },
+	) {
+		super(message, options);
+		this.name = "InkerRenderError";
+		this.code = code;
+		this.context = Object.freeze({ ...(context ?? {}) });
+	}
+}

package/src/InkerRenderer.ts

@@ -0,0 +1,55 @@
+import type { AsyncLocalStorage } from "node:async_hooks";
+import type { Templates } from "./Templates.js";
+
+/**
+ * Duck-typed contract for the per-request context Inker reads inside its
+ * canonical helper bodies. Keeping the interface local (instead of importing
+ * `@c9up/ream`'s HttpContext) preserves Inker's leaf-invariant: the
+ * InkerRenderer file lives in the LEAF half of the package and must compile
+ * without `@c9up/ream` installed. Ream's HttpContext structurally satisfies
+ * this shape — verified by the integration test's compile step.
+ */
+export interface InkerHttpContext {
+	readonly request: object;
+	readonly response: {
+		type(value: string): unknown;
+		send(body: string): unknown;
+	};
+	readonly store: Map<string, unknown>;
+	readonly locale: string;
+}
+
+export class InkerRenderer {
+	readonly #templates: Templates;
+	readonly #als: AsyncLocalStorage<InkerHttpContext>;
+
+	constructor(templates: Templates, als: AsyncLocalStorage<InkerHttpContext>) {
+		this.#templates = templates;
+		this.#als = als;
+	}
+
+	async render(
+		ctx: InkerHttpContext,
+		name: string,
+		data: Readonly<Record<string, unknown>>,
+	): Promise<void> {
+		const html = await this.#als.run(ctx, () =>
+			this.#templates.render(name, data),
+		);
+		ctx.response.type("text/html; charset=utf-8");
+		ctx.response.send(html);
+	}
+
+	async renderToString(
+		ctx: InkerHttpContext,
+		name: string,
+		data: Readonly<Record<string, unknown>>,
+	): Promise<string> {
+		return this.#als.run(ctx, () => this.#templates.render(name, data));
+	}
+
+	/** @internal Test seam — access the underlying Templates for cache control. */
+	get _templates(): Templates {
+		return this.#templates;
+	}
+}

package/src/SafeString.ts

@@ -0,0 +1,27 @@
+import { InkerRenderError } from "./InkerRenderError.js";
+
+/**
+ * Marker class for already-escaped strings. Helpers that return
+ * trusted HTML (e.g. `csrfField()` returning `<input type="hidden" …>`)
+ * should return `new SafeString(html)` so the renderer emits the value
+ * raw instead of double-escaping.
+ *
+ * Returning a `SafeString` constructed from user input is a cross-site
+ * scripting bug. Restrict `SafeString` to author-controlled HTML
+ * (constants, library output where escaping is already handled).
+ */
+export class SafeString {
+	readonly value: string;
+	constructor(value: string) {
+		if (typeof value !== "string") {
+			// Throws `InkerRenderError` (not native `TypeError`) so callers
+			// handling the typed error contract uniformly catch SafeString
+			// construction failures alongside every other Inker failure mode.
+			throw new InkerRenderError(
+				"E_INKER_INVALID_EXPRESSION",
+				`SafeString requires a string; got ${typeof value}`,
+			);
+		}
+		this.value = value;
+	}
+}