checkpoint

Author: jonathantneal

.vscode/settings.json

@@ -7,5 +7,8 @@
 	"editor.insertSpaces": false,
 	"editor.tabSize": 4,
 	"json.schemaDownload.enable": true,
-	"js/ts.tsdk.path": "node_modules/typescript/lib"
+	"js/ts.tsdk.path": "node_modules/typescript/lib",
+	"[typescript]": {
+		"editor.defaultFormatter": "vscode.typescript-language-features"
+	}
 }

biome.jsonc

@@ -21,6 +21,7 @@
 			"recommended": true,
 			"complexity": {
 				"noCommaOperator": "off",
+				"noStaticOnlyClass": "off",
 				"noThisInStatic": "off"
 			},
 			"style": {

src/compiler/compiler.ts

@@ -117,3 +117,5 @@ const host = new CompilerHost({
 	include: ["src/test/example/*.resolver.json"],
 	exclude: ["node_modules"],
 });
+
+void host;

src/loader/index.ts

@@ -2,18 +2,41 @@ import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 
 import type { Format } from "../types/format.js";
-import type { Resolver } from "../types/resolver.js";
 import type { Set } from "../types/resolver/set.js";
-
-import { getAtPath, parsePointer } from "./pointer.js";
+import type { Resolver } from "../types/resolver.js";
 import { mergeFormats } from "./merge.js";
+import { getAtPath, parsePointer } from "./pointer.js";
 
 // ─── Public Types ─────────────────────────────────────────────────────────────
 
+/**
+ * The I/O interface consumed by {@link LoaderHost}. Swap this out to run in
+ * any environment — browser, Deno, test sandbox, etc.
+ *
+ * @example Browser virtual filesystem
+ * const browserSys: LoaderSys = {
+ *   readFile: (url) => fileMap.get(url.href) ?? (() => { throw new Error(`Not found: ${url}`) })(),
+ *   currentDirectory: () => new URL("./", location.href),
+ * }
+ */
+export interface LoaderSys {
+	/** Reads the contents of the file at `url` and returns it as a UTF-8 string. */
+	readFile(url: URL): string;
+
+	/** Returns the base URL used when no explicit base is provided to {@link LoaderHost.load}. */
+	currentDirectory(): URL;
+}
+
+/** Default {@link LoaderSys} for Node.js — reads files with `readFileSync`. */
+export const nodeSys: LoaderSys = {
+	readFile: (url) => readFileSync(url, "utf8"),
+	currentDirectory: () => pathToFileURL(`${process.cwd()}/`),
+};
+
 export interface LoadOptions {
 	/**
 	 * Base URL (or absolute path) used to resolve relative file references inside
-	 * a resolver document. Defaults to `file://{process.cwd()}/` when omitted.
+	 * a resolver document. Defaults to {@link LoaderSys.currentDirectory} when omitted.
 	 */
 	base?: URL | string;
 }
@@ -32,17 +55,25 @@ export interface LoadResult {
  * A stateful DTCG loader that caches every JSON file it reads.
  * Reuse a single `LoaderHost` instance across multiple `load()` calls to share
  * the cache and avoid re-reading the same files.
+ *
+ * Pass a custom {@link LoaderSys} to run outside of Node.js.
  */
 export class LoaderHost {
+	readonly sys: LoaderSys;
+
 	/** Parsed JSON values, keyed by URL href. */
 	#cache = new Map<string, unknown>();
 
+	constructor(sys: LoaderSys = nodeSys) {
+		this.sys = sys;
+	}
+
 	/** Reads and JSON-parses a file at `url`, caching the result by href. */
 	readJSON<T>(url: URL): T {
 		const { href } = url;
 
 		if (!this.#cache.has(href)) {
-			this.#cache.set(href, JSON.parse(readFileSync(url, "utf8")));
+			this.#cache.set(href, JSON.parse(this.sys.readFile(url)));
 		}
 
 		return this.#cache.get(href) as T;
@@ -60,7 +91,7 @@ export class LoaderHost {
 	 * merged into the final token tree.
 	 */
 	load(input: string | URL | Resolver, options?: LoadOptions): LoadResult {
-		const defaultBase = pathToFileURL(`${process.cwd()}/`);
+		const defaultBase = this.sys.currentDirectory();
 		let resolver: Resolver;
 		let resolverBase: URL;
 
@@ -109,7 +140,7 @@ export class LoaderHost {
  * For repeated loads, prefer {@link LoaderHost} to share the internal file cache.
  */
 export const load = (input: string | URL | Resolver, options?: LoadOptions): LoadResult =>
-	new LoaderHost().load(input, options);
+	new LoaderHost(nodeSys).load(input, options);
 
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 

src/loader/merge.ts

@@ -1,47 +1,96 @@
-import type { Format } from "../types/format.js"
+import type { Format } from "../types/format.js";
 
 /**
- * Deep-merges an ordered iterable of DTCG {@link Format} objects into a single
- * combined token tree. Sources are applied left-to-right; later entries override
- * earlier ones at leaf (non-object) positions, while nested groups are recursively
- * merged so siblings from different sources are preserved.
+ * Lazily merges an ordered array of DTCG {@link Format} objects into a single
+ * combined token tree via a {@link Proxy}. Sources are applied left-to-right;
+ * later entries override earlier ones at leaf (non-object) positions, while
+ * nested groups are recursively merged so siblings from different sources are
+ * preserved. No allocation occurs until a property is actually accessed.
  *
  * @example
  * mergeFormats([
  *   { color: { red: { $type: "color", $value: "…" } } },
  *   { color: { blue: { $type: "color", $value: "…" } } },
  * ])
- * // → { color: { red: { … }, blue: { … } } }
+ * // → proxy that lazily produces { color: { red: { … }, blue: { … } } }
  */
-export const mergeFormats = (formats: Iterable<Format>): Format => {
-	const merged: Record<string, unknown> = {}
+export const mergeFormats = (formats: Format[]): Format => {
+	const handler: ProxyHandler<object> = {
+		get(_target, key) {
+			if (typeof key !== "string") return undefined;
 
-	for (const format of formats) {
-		deepMergeInto(merged, format as Record<string, unknown>)
-	}
+			const subFormats: Format[] = [];
+			let leafValue: unknown;
+			let hasLeaf = false;
 
-	return merged as Format
-}
+			for (const format of formats) {
+				const val = (format as Record<string, unknown>)[key];
+				if (val === undefined) continue;
 
-// ─── Internal ─────────────────────────────────────────────────────────────────
+				if (isPlainObject(val)) {
+					subFormats.push(val as Format);
+				} else {
+					// A later leaf (primitive or array) wins; discard accumulated sub-objects.
+					subFormats.length = 0;
+					leafValue = val;
+					hasLeaf = true;
+				}
+			}
+
+			if (subFormats.length > 0) return mergeFormats(subFormats);
+			if (hasLeaf) return leafValue;
+			return undefined;
+		},
+
+		has(_target, key) {
+			if (typeof key !== "string") return false;
+			return formats.some((f) => key in (f as object));
+		},
+
+		ownKeys(_target) {
+			const keys = new Set<string>();
+			for (const format of formats) {
+				for (const key in format) keys.add(key);
+			}
+			return [...keys];
+		},
+
+		getOwnPropertyDescriptor(_target, key) {
+			if (typeof key !== "string") return undefined;
+			const exists = formats.some((f) => Object.hasOwn(f as object, key));
+			if (!exists) return undefined;
+			return { configurable: true, enumerable: true, writable: false, value: undefined };
+		},
+	};
+
+	// Each call gets a fresh subclass so its prototype slot is independent.
+	const MergedFormat = class extends NullProxy {};
+	return MergedFormat.from(handler) as unknown as Format;
+};
+
+// ─── NullProxy ────────────────────────────────────────────────────────────────
 
 /**
- * Recursively merges `source` into `target` in-place.
- * Plain objects are merged deeply; all other values (arrays, primitives) replace.
+ * A base class whose instances have no default own properties and whose
+ * prototype chain routes all property access through a caller-supplied
+ * {@link ProxyHandler}. Callers should subclass and call `.from(handler)` on
+ * the subclass so each merged view gets an isolated prototype slot.
  */
-const deepMergeInto = (
-	target: Record<string, unknown>,
-	source: Record<string, unknown>,
-): void => {
-	for (const [key, value] of Object.entries(source)) {
-		if (isPlainObject(value) && isPlainObject(target[key])) {
-			deepMergeInto(target[key] as Record<string, unknown>, value)
-		} else {
-			target[key] = value
-		}
+
+class NullProxy {
+	static {
+		// @ts-expect-error to fully nullify the prototype
+		delete NullProxy.prototype.constructor;
+	}
+
+	static from(handler: ProxyHandler<object>): NullProxy {
+		const proxy = new Proxy(Object.create(null) as object, handler);
+		Object.setPrototypeOf(this.prototype as object, proxy);
+		return Reflect.construct(this, []) as NullProxy;
 	}
 }
 
-const isPlainObject = (value: unknown): value is Record<string, unknown> =>
-	value !== null && typeof value === "object" && !Array.isArray(value)
+// ─── Internal ─────────────────────────────────────────────────────────────────
 
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+	value !== null && typeof value === "object" && !Array.isArray(value);

src/loader/pointer.ts

@@ -6,16 +6,14 @@
  * @example parsePointer("#")           // []
  */
 export const parsePointer = (pointer: string): string[] => {
-	if (pointer === "#") return []
+	if (pointer === "#") return [];
 
 	if (!pointer.startsWith("#/")) {
-		throw new Error(
-			`Expected a local JSON Pointer (e.g. "#/sets/core"), got: ${JSON.stringify(pointer)}`,
-		)
+		throw new Error(`Expected a local JSON Pointer (e.g. "#/sets/core"), got: ${JSON.stringify(pointer)}`);
 	}
 
-	return pointer.slice(2).split("/").map(decodeSegment)
-}
+	return pointer.slice(2).split("/").map(decodeSegment);
+};
 
 /**
  * Traverses a document by an array of path segments, returning the value at
@@ -24,28 +22,26 @@ export const parsePointer = (pointer: string): string[] => {
  * @example getAtPath(doc, ["sets", "core"]) // doc.sets.core
  */
 export const getAtPath = (root: unknown, path: readonly string[]): unknown => {
-	let node: unknown = root
+	let node: unknown = root;
 
 	for (const key of path) {
 		if (Array.isArray(node)) {
-			const index = Number(key)
-			node = Number.isInteger(index) ? node[index] : undefined
+			const index = Number(key);
+			node = Number.isInteger(index) ? node[index] : undefined;
 		} else if (isObject(node)) {
-			node = node[key]
+			node = node[key];
 		} else {
-			return undefined
+			return undefined;
 		}
 	}
 
-	return node
-}
+	return node;
+};
 
 // ─── Internal ─────────────────────────────────────────────────────────────────
 
 /** Decodes a single RFC 6901 pointer segment (`~1` → `/`, `~0` → `~`). */
-const decodeSegment = (segment: string): string =>
-	segment.replaceAll("~1", "/").replaceAll("~0", "~")
+const decodeSegment = (segment: string): string => segment.replaceAll("~1", "/").replaceAll("~0", "~");
 
 const isObject = (value: unknown): value is Record<string, unknown> =>
-	value !== null && typeof value === "object" && !Array.isArray(value)
-
+	value !== null && typeof value === "object" && !Array.isArray(value);

src/tree/index.ts

@@ -1,5 +1,5 @@
-import type { Format } from "../types/format.js";
 import type { TokenType, TokenValue } from "../types/format/tokenType.js";
+import type { Format } from "../types/format.js";
 
 const nodeInspect = Symbol.for("nodejs.util.inspect.custom");
 
@@ -22,9 +22,8 @@ export class TokenLeaf {
 		this.value = value;
 	}
 
-	[nodeInspect](_depth: number, options: object) {
-		const { inspect } = require("node:util");
-		return `TokenLeaf ${inspect({ type: this.type, value: this.value }, options)}`;
+	[nodeInspect]() {
+		return Object.assign(new (class TokenLeaf {})(), { type: this.type, value: this.value });
 	}
 }
 
@@ -53,9 +52,8 @@ export class TokenGroup {
 		return this.#children.entries();
 	}
 
-	[nodeInspect](_depth: number, options: object) {
-		const { inspect } = require("node:util");
-		return `TokenGroup ${inspect(Object.fromEntries(this.#children), options)}`;
+	[nodeInspect]() {
+		return Object.assign(new (class TokenGroup {})(), Object.fromEntries(this.#children));
 	}
 }
 
@@ -82,7 +80,8 @@ const buildGroup = (raw: RawObject, parentType: string | undefined): TokenGroup
 	const ownType = typeof raw.$type === "string" ? raw.$type : parentType;
 	const children = new Map<string, TokenNode>();
 
-	for (const [key, val] of Object.entries(raw)) {
+	for (const key in raw) {
+		const val = raw[key];
 		if (key.startsWith("$") || !isObject(val)) continue;
 
 		children.set(