env-runner 0.2.2 → 0.3.0

package/dist/_chunks/common-base-runner.mjs

@@ -1,6 +1,16 @@
-import { resolveVirtualModules } from "./virtual-loader.mjs";
+import { encodeVirtualModules, normalizeVirtualModules, resolveVirtualModules, warnVirtualPathCollisions } from "./virtual-loader.mjs";
 import { rm } from "node:fs/promises";
 import { proxyFetch, proxyUpgrade } from "httpxy";
+function hostEnv(extra) {
+	const env = {
+		...process.env,
+		...extra
+	};
+	const stdout = process.stdout;
+	if (!("FORCE_COLOR" in env) && !env.NO_COLOR && stdout?.isTTY) env.FORCE_COLOR = "1";
+	if (!("COLUMNS" in env) && stdout?.columns) env.COLUMNS = String(stdout.columns);
+	return env;
+}
 var BaseEnvRunner = class {
 	closed = false;
 	_name;
@@ -11,7 +21,11 @@ var BaseEnvRunner = class {
 	_address;
 	_messageListeners;
 	_pendingRequests;
+	_closeCause;
 	_virtualResolved;
+	_virtualUpdates = Promise.resolve();
+	#virtualUpdateId = 0;
+	_processData;
 	constructor(opts) {
 		this._name = opts.name;
 		this._workerEntry = opts.workerEntry;
@@ -27,7 +41,7 @@ var BaseEnvRunner = class {
 		return this._address;
 	}
 	async fetch(input, init) {
-		for (let i = 0; i < 5 && !this._address && !this.closed; i++) await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i)));
+		await this._waitForAddress();
 		if (!this._address) return new Response(`${this._runtimeType()} env runner is unavailable`, { status: 503 });
 		return proxyFetch(this._address, this._resolveFetchInput(input), init);
 	}
@@ -49,24 +63,29 @@ var BaseEnvRunner = class {
 	}
 	waitForReady(timeout = 15e3) {
 		if (this.ready) return Promise.resolve();
-		if (this.closed) return Promise.reject(/* @__PURE__ */ new Error("Runner closed before becoming ready"));
+		if (this.closed) return Promise.reject(closedBeforeReadyError(this._closeCause));
 		return new Promise((resolve, reject) => {
 			const timer = setTimeout(() => {
-				this._messageListeners.delete(listener);
+				cleanup();
 				reject(/* @__PURE__ */ new Error("Runner did not become ready in time"));
 			}, timeout);
 			const listener = () => {
 				if (this.ready) {
-					clearTimeout(timer);
-					this._messageListeners.delete(listener);
+					cleanup();
 					resolve();
-				} else if (this.closed) {
-					clearTimeout(timer);
-					this._messageListeners.delete(listener);
-					reject(/* @__PURE__ */ new Error("Runner closed before becoming ready"));
 				}
 			};
+			const onClose = (cause) => {
+				cleanup();
+				reject(closedBeforeReadyError(cause));
+			};
+			const cleanup = () => {
+				clearTimeout(timer);
+				this._messageListeners.delete(listener);
+				this._pendingRequests.delete(onClose);
+			};
 			this._messageListeners.add(listener);
+			this._pendingRequests.add(onClose);
 		});
 	}
 	rpc(name, data, opts) {
@@ -82,27 +101,27 @@ var BaseEnvRunner = class {
 		}).then((msg) => msg.data);
 	}
 	async reloadModule(timeout = 5e3) {
+		await this._virtualUpdates;
 		await this._request({ event: "reload-module" }, {
 			match: (msg) => msg?.event === "module-reloaded",
 			timeout,
 			timeoutError: "Module reload timed out"
 		});
 	}
-	async invalidateModule(specifier, timeout = 5e3) {
-		const source = await this._refreshVirtualSource(specifier);
-		await this._request({
-			event: "invalidate-module",
-			specifier,
-			source
-		}, {
-			match: (msg) => msg?.event === "module-invalidated" && msg.specifier === specifier,
-			timeout,
-			timeoutError: `Module invalidation timed out for "${specifier}"`
-		});
+	updateVirtualModules(changes, timeout = 5e3) {
+		return this._enqueueVirtualUpdate(() => changes, timeout);
+	}
+	invalidateModule(specifier, timeout = 5e3) {
+		return this._enqueueVirtualUpdate(() => {
+			const source = this._virtualSources?.[specifier];
+			if (source === void 0) throw new Error(`Cannot invalidate "${specifier}" (not a registered virtual module)`);
+			return { [specifier]: source };
+		}, timeout);
 	}
 	async close(cause) {
 		if (this.closed) return;
 		this.closed = true;
+		this._closeCause = cause;
 		for (const rejectPending of this._pendingRequests) rejectPending(cause);
 		this._pendingRequests.clear();
 		this._hooks.onClose?.(this, cause);
@@ -118,6 +137,9 @@ var BaseEnvRunner = class {
 		const status = this.closed ? "closed" : this.ready ? "ready" : "pending";
 		return `${this.constructor.name}#${this._name}(${status})`;
 	}
+	async _waitForAddress() {
+		for (let i = 0; i < 5 && !this._address && !this.closed; i++) await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i)));
+	}
 	_resolveFetchInput(input) {
 		if (typeof input === "string" && !URL.canParse(input)) return new URL(input, "http://localhost");
 		return input;
@@ -130,6 +152,36 @@ var BaseEnvRunner = class {
 		if (message?.event === "init-error" && !this.ready && !this.closed) this.close(new Error(String(message.error || "Worker initialization failed")));
 		for (const listener of this._messageListeners) listener(message);
 	}
+	_processEnv() {
+		const data = this._data || {};
+		const virtual = data.virtual;
+		try {
+			this._processData = JSON.stringify(virtual ? {
+				...data,
+				virtual: encodeVirtualModules(virtual)
+			} : data);
+		} catch (error) {
+			throw new TypeError(`Runner data must be JSON-serializable: ${error?.message || error}`, { cause: error });
+		}
+		return hostEnv({ ENV_RUNNER_NAME: this._name });
+	}
+	_handleProcessMessage(message) {
+		if (message?.event !== "request-init-data") {
+			this._handleMessage(message);
+			return;
+		}
+		if (this.closed) return;
+		try {
+			this.sendMessage({
+				event: "init-data",
+				data: this._processData ?? "{}"
+			});
+		} catch (error) {
+			const cause = new Error(`Failed to send runner data to the worker over IPC: ${error?.message || error}`, { cause: error });
+			console.error(`[env-runner] ${cause.message}`);
+			this.close(cause);
+		}
+	}
 	_request(message, opts) {
 		if (this.closed) return Promise.reject(/* @__PURE__ */ new Error("Runner is closed"));
 		return new Promise((resolve, reject) => {
@@ -165,8 +217,17 @@ var BaseEnvRunner = class {
 	}
 	_resolveVirtualData() {
 		const virtual = this._data?.virtual;
-		this._virtualSources = virtual;
-		if (!virtual || !Object.values(virtual).some((v) => typeof v === "function")) return;
+		this._virtualSources = { ...virtual };
+		this._data = { ...this._data };
+		warnVirtualPathCollisions(Object.keys(virtual ?? {}));
+		if (!virtual) return;
+		if (!Object.values(virtual).some((v) => typeof v === "function")) try {
+			this._data.virtual = normalizeVirtualModules(virtual);
+			return;
+		} catch (error) {
+			this._virtualResolved = Promise.reject(error);
+			return this._virtualResolved;
+		}
 		this._virtualResolved = resolveVirtualModules(virtual).then((resolved) => {
 			this._data = {
 				...this._data,
@@ -175,20 +236,50 @@ var BaseEnvRunner = class {
 		});
 		return this._virtualResolved;
 	}
-	async _refreshVirtualSource(specifier) {
-		await this._virtualResolved?.catch(() => {});
-		const original = this._virtualSources?.[specifier];
-		if (typeof original !== "function") return;
-		const source = await original();
-		const resolved = this._data?.virtual;
-		if (resolved) resolved[specifier] = source;
-		return source;
+	_enqueueVirtualUpdate(changes, timeout) {
+		const update = this._virtualUpdates.then(async () => {
+			await this._virtualResolved;
+			if (this.closed) throw new Error("Runner is closed");
+			const entries = Object.entries(changes()).filter(([, source]) => source !== void 0);
+			if (entries.length === 0) return;
+			const sets = Object.fromEntries(entries.filter((entry) => entry[1] !== null));
+			const resolved = await resolveVirtualModules(sets);
+			const sources = this._virtualSources ??= {};
+			const virtual = (this._data ??= {}).virtual ??= {};
+			let added = false;
+			for (const [key, source] of entries) if (source === null) {
+				resolved[key] = null;
+				delete sources[key];
+				delete virtual[key];
+			} else {
+				added ||= !Object.hasOwn(sources, key);
+				sources[key] = source;
+				virtual[key] = resolved[key];
+			}
+			if (added) warnVirtualPathCollisions(Object.keys(virtual));
+			if (!this.ready) await this.waitForReady();
+			await this._applyVirtualUpdates(resolved, timeout);
+		});
+		this._virtualUpdates = update.catch(() => {});
+		return update;
+	}
+	async _applyVirtualUpdates(changes, timeout) {
+		const id = ++this.#virtualUpdateId;
+		await this._request({
+			event: "update-virtual-modules",
+			id,
+			changes: encodeVirtualModules(changes)
+		}, {
+			match: (msg) => msg?.event === "virtual-modules-updated" && msg.id === id,
+			timeout,
+			timeoutError: "Virtual module update timed out"
+		});
 	}
 	_initWithVirtualData(init) {
 		const pending = this._resolveVirtualData();
 		if (pending) pending.then(() => {
 			if (!this.closed) init();
-		}, (error) => this.close(error));
+		}).catch((error) => this.close(error));
 		else init();
 	}
 	async _closeSocket() {
@@ -197,4 +288,7 @@ var BaseEnvRunner = class {
 		this._address = void 0;
 	}
 };
-export { BaseEnvRunner };
+function closedBeforeReadyError(cause) {
+	return new Error("Runner closed before becoming ready", cause ? { cause } : void 0);
+}
+export { BaseEnvRunner, hostEnv };

package/dist/_chunks/common-process-data.mjs

@@ -0,0 +1,13 @@
+function receiveProcessData() {
+	return new Promise((resolve) => {
+		const onMessage = (message) => {
+			if (message?.event === "init-data") {
+				process.off("message", onMessage);
+				resolve(message.data);
+			}
+		};
+		process.on("message", onMessage);
+		process.send({ event: "request-init-data" });
+	}).then((json) => JSON.parse(json));
+}
+export { receiveProcessData };

package/dist/_chunks/common-runtime-deps.d.mts

@@ -1,18 +1,7 @@
 /**
- * A runtime dependency the application owns, not `env-runner`.
- *
- * Every runner option that names an external package accepts the same three
- * shapes, so the choice is about ergonomics rather than per-runner API:
- *
- * - the **imported module** (`import * as miniflare from "miniflare"`) — the
- *   version installed by the app is the version that runs
- * - a **module specifier** (`"miniflare"`, `import.meta.resolve("miniflare")`,
- *   or a `URL`) — resolved from {@link ResolveRuntimeDepOptions.from} (cwd by
- *   default), so a bare specifier resolves against the app rather than against
- *   `env-runner`'s own `node_modules`
- * - `false` — opt out of the package entirely
- *
- * Omitting the option falls back to an optional `import()` of the package.
+ * An app-owned package: the imported module, a specifier (resolved from the
+ * app, not `env-runner`), or `false` to opt out. Omitted falls back to an
+ * optional `import()`.
  */
 export type RuntimeDep<T> = T | string | URL | false;
 interface ResolveRuntimeDepOptions<T> {
@@ -22,29 +11,17 @@ interface ResolveRuntimeDepOptions<T> {
   option: string;
   /** Value as passed by the caller. */
   value?: RuntimeDep<T>;
-  /**
-   * Named export the resolved module must expose. A module that lacks it is
-   * treated as the wrong package (throws for an explicit value).
-   */
+  /** Named export identifying the package (a mismatch throws for an explicit value). */
   expect?: string;
   /** Directory bare specifiers resolve from. @default process.cwd() */
   from?: string;
-  /**
-   * Throw when the package cannot be resolved at all. Otherwise an
-   * unavailable optional package resolves to `undefined` and the caller
-   * degrades (minimal reader, shim, no-op).
-   */
+  /** Throw when unresolvable instead of resolving `undefined` (callers degrade). */
   required?: boolean;
   /** Extra sentence appended to the "not installed" error when `required`. */
   hint?: string;
 }
 /**
- * Resolve a {@link RuntimeDep} to an imported module.
- *
- * Resolution order: `false` → `undefined`; an imported module → validated and
- * returned as-is; a specifier → imported (errors propagate, since an explicit
- * specifier that cannot load is a mistake worth surfacing); omitted → optional
- * `import(name)`, which yields `undefined` when the package isn't installed
- * unless {@link ResolveRuntimeDepOptions.required} is set.
+ * Resolve a {@link RuntimeDep} to a module. An explicit specifier that fails to
+ * import throws; an omitted one resolves `undefined` unless `required`.
  */
 export declare function resolveRuntimeDep<T>(opts: ResolveRuntimeDepOptions<T>): Promise<T | undefined>;