checkpoint

Author: jonathantneal

package.json

@@ -15,14 +15,22 @@
 	},
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
-	"files": ["dist"],
+	"files": [
+		"dist"
+	],
 	"repository": "https://github.com/jsxtools/dtcg-tools",
 	"bugs": "https://github.com/jsxtools/dtcg-tools/issues",
 	"publishConfig": {
 		"access": "public"
 	},
 	"sideEffects": false,
-	"keywords": ["design-tokens", "dtcg", "typescript", "types", "schema"],
+	"keywords": [
+		"design-tokens",
+		"dtcg",
+		"typescript",
+		"types",
+		"schema"
+	],
 	"scripts": {
 		"build": "tsc",
 		"clean": "rm -rf dist coverage *.tsbuildinfo",

src/loader/index.ts

@@ -1,6 +1,3 @@
-import { readFileSync } from "node:fs";
-import { pathToFileURL } from "node:url";
-
 import type { Format } from "../types/format.js";
 import type { Set } from "../types/resolver/set.js";
 import type { Resolver } from "../types/resolver.js";
@@ -10,33 +7,30 @@ import { getAtPath, parsePointer } from "./pointer.js";
 // ─── Public Types ─────────────────────────────────────────────────────────────
 
 /**
- * The I/O interface consumed by {@link LoaderHost}. Swap this out to run in
+ * The I/O interface consumed by {@link LoaderHost}. Implement this to run in
  * any environment — browser, Deno, test sandbox, etc.
  *
+ * The Node.js implementation (`nodeSys`) lives in `./node.ts` to keep this
+ * module free of Node-only imports and safe to bundle for the browser.
+ *
  * @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}. */
+	/** 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 {@link LoaderSys.currentDirectory} when omitted.
+	 * Base URL (or string path/URL) used to resolve relative `$ref` paths inside
+	 * the resolver document. Defaults to {@link LoaderSys.currentDirectory} when omitted.
 	 */
 	base?: URL | string;
 }
@@ -45,67 +39,72 @@ export interface LoadResult {
 	/** The fully merged DTCG token tree, combining all resolved sources in order. */
 	tokens: Format;
 
-	/** Resolved URLs of every external token file that was fetched. */
+	/** Resolved URLs of every external token file that was loaded. */
 	sources: URL[];
 }
 
 // ─── LoaderHost ───────────────────────────────────────────────────────────────
 
 /**
- * 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.
+ * A stateful DTCG loader. Provide a {@link LoaderSys} appropriate for your
+ * runtime environment (e.g. `nodeSys` from `./node.ts` for Node.js).
  *
- * Pass a custom {@link LoaderSys} to run outside of Node.js.
+ * Reuse a single instance across multiple `load()` calls to share the internal
+ * file-read cache and avoid parsing the same JSON files more than once.
  */
 export class LoaderHost {
 	readonly sys: LoaderSys;
 
 	/** Parsed JSON values, keyed by URL href. */
 	#cache = new Map<string, unknown>();
 
-	constructor(sys: LoaderSys = nodeSys) {
+	constructor(sys: LoaderSys) {
 		this.sys = sys;
 	}
 
-	/** Reads and JSON-parses a file at `url`, caching the result by href. */
+	/** Reads and JSON-parses the 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(this.sys.readFile(url)));
 		}
-
 		return this.#cache.get(href) as T;
 	}
 
 	/**
-	 * Loads a DTCG resolver and returns the merged token tree plus source metadata.
+	 * Loads a DTCG resolver document and returns the merged token tree plus the
+	 * list of external source files that were fetched.
 	 *
 	 * `input` may be:
-	 * - A file-path string or `URL` pointing to a resolver JSON file.
-	 * - An inline {@link Resolver} object (pair with `options.base` so that
-	 *   relative `$ref` paths inside it can be resolved).
+	 * - A string path or {@link URL} pointing to a resolver JSON file on disk (or network).
+	 * - An inline {@link Resolver} object — pair with `options.base` so that relative
+	 *   `$ref` paths inside it resolve to the right location.
 	 *
-	 * Resolution order items that reference modifiers are skipped; only sets are
-	 * merged into the final token tree.
+	 * Resolution-order items that reference modifiers are skipped; only `set`
+	 * entries contribute to the merged token tree.
 	 */
 	load(input: string | URL | Resolver, options?: LoadOptions): LoadResult {
 		const defaultBase = this.sys.currentDirectory();
 		let resolver: Resolver;
 		let resolverBase: URL;
 
 		if (typeof input === "string" || input instanceof URL) {
-			const resolverURL = new URL(input.toString(), resolveBase(options?.base, defaultBase));
+			// Resolve the path/URL relative to the sys's current directory (or the
+			// caller-supplied base). Using new URL(str, base) handles both absolute
+			// file paths (e.g. "/Users/…") and relative strings correctly on all
+			// platforms without requiring Node's pathToFileURL.
+			const resolverURL = new URL(input.toString(), toBaseURL(options?.base, defaultBase));
 			resolver = this.readJSON<Resolver>(resolverURL);
-			// Derive a directory-level base so relative $refs in the document resolve correctly.
+			// Strip the filename so sibling $refs inside the resolver resolve correctly.
 			resolverBase = new URL(".", resolverURL);
 		} else {
 			resolver = input;
-			resolverBase = resolveBase(options?.base, defaultBase);
+			resolverBase = toBaseURL(options?.base, defaultBase);
 		}
 
-		// ── Assemble formats in resolution order ──────────────────────────────
+		// Walk resolutionOrder, collect Set sources in order.
+		// Modifier entries are intentionally skipped — they are context-dependent
+		// and cannot be statically merged into a single flat token tree.
 		const sources: URL[] = [];
 		const formats: Format[] = [];
 
@@ -127,51 +126,41 @@ export class LoaderHost {
 		return { tokens: mergeFormats(formats), sources };
 	}
 
-	/** Drops all cached reads, forcing subsequent loads to re-read every file. */
+	/** Clears the file cache, forcing the next `load()` call to re-read every file. */
 	clearCache(): void {
 		this.#cache.clear();
 	}
 }
 
-// ─── Convenience export ───────────────────────────────────────────────────────
-
-/**
- * One-shot helper that loads and resolves a DTCG resolver document.
- * For repeated loads, prefer {@link LoaderHost} to share the internal file cache.
- */
-export const load = (input: string | URL | Resolver, options?: LoadOptions): LoadResult =>
-	new LoaderHost(nodeSys).load(input, options);
-
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 
 /**
- * Resolves an item from `resolutionOrder` to a concrete {@link Set}, dereferencing
- * JSON Pointers as needed. Returns `null` for modifiers and unresolvable refs.
+ * Resolves an item from `resolutionOrder` to a concrete {@link Set} by
+ * dereferencing any JSON Pointer. Returns `null` for modifier references and
+ * any `$ref` that does not point to a set.
  */
 const resolveSet = (item: Resolver["resolutionOrder"][number], resolver: Resolver): Set | null => {
 	if ("$ref" in item) {
-		const resolved = getAtPath(resolver, parsePointer(item.$ref));
-		return isSet(resolved) ? resolved : null;
+		const target = getAtPath(resolver, parsePointer(item.$ref));
+		return isSet(target) ? target : null;
 	}
-
 	return item.type === "set" ? item : null;
 };
 
-const isSet = (value: unknown): value is Set =>
-	isPlainObject(value) && Array.isArray((value as { sources?: unknown }).sources);
+const isSet = (v: unknown): v is Set => isObject(v) && Array.isArray((v as { sources?: unknown }).sources);
 
-const isPlainObject = (value: unknown): value is Record<string, unknown> =>
-	value !== null && typeof value === "object" && !Array.isArray(value);
+const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
 
-const resolveBase = (base: URL | string | undefined, fallback: URL): URL => {
+/**
+ * Converts `base` to a {@link URL}, falling back to `fallback` when `base` is
+ * absent. String values are resolved against `fallback` so that both absolute
+ * URLs (`"https://…"`) and absolute file paths (`"/Users/…"`) work correctly
+ * without requiring Node's `pathToFileURL`.
+ */
+const toBaseURL = (base: URL | string | undefined, fallback: URL): URL => {
 	if (base == null) return fallback;
 	if (base instanceof URL) return base;
-
-	try {
-		return new URL(base);
-	} catch {
-		// Treat as a local file-system path.
-		const path = base.endsWith("/") || base.endsWith("\\") ? base : `${base}/`;
-		return pathToFileURL(path);
-	}
+	// new URL(string, fallback) handles absolute paths (e.g. "/Users/…") correctly
+	// when fallback is a file:// URL: the path replaces the fallback's path component.
+	return new URL(base.endsWith("/") ? base : `${base}/`, fallback);
 };