env-runner 0.2.2 → 0.2.3

package/dist/_chunks/netlify-runner.d.mts

@@ -7,27 +7,9 @@ export interface NetlifyEnvRunnerOptions {
   hooks?: WorkerHooks;
   data?: EnvRunnerData;
   /**
-   * Module specifier for the `@netlify/runtime` package, used inside the
-   * worker to call `startRuntime()` (full `globalThis.Netlify` + `caches`
-   * setup). `env-runner` does not depend on `@netlify/runtime`.
-   *
-   * Unlike the other runtime-dependency options, this one takes a **specifier
-   * only**: the runtime has to be instantiated inside the worker thread, and a
-   * live module instance cannot cross that boundary.
-   *
-   * ```ts
-   * new NetlifyEnvRunner({
-   *   name: "app",
-   *   netlifyRuntime: import.meta.resolve("@netlify/runtime"),
-   *   data: { entry },
-   * });
-   * ```
-   *
-   * A bare specifier (e.g. `"@netlify/runtime"`) is resolved from the current
-   * working directory. When omitted, the worker tries
-   * `import("@netlify/runtime")` and falls back to a lightweight
-   * `globalThis.Netlify` shim (env access only) if it isn't installed. Pass
-   * `false` to always use the shim.
+   * `@netlify/runtime` specifier (resolved from cwd), imported inside the worker
+   * since a module instance can't cross into it. Omitted: imported optionally,
+   * else an env-only `globalThis.Netlify` shim. `false` forces the shim.
    */
   netlifyRuntime?: string | URL | false;
 }

package/dist/_chunks/types.d.mts

@@ -1,11 +1,6 @@
 import { IncomingMessage } from "node:http";
 import { Socket } from "node:net";
-/**
- * Handler for proxying HTTP requests to the worker.
- *
- * A relative string input (e.g. `"/path"`) is resolved against a placeholder
- * `http://localhost` origin before dispatching.
- */
+/** Proxy a request to the worker; relative inputs resolve against `http://localhost`. */
 export type FetchHandler = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 /** Callback for receiving messages from the worker. */
 export type RunnerMessageListener = (data: unknown) => void;
@@ -30,11 +25,7 @@ export interface RunnerRPCHooks {
   /** Remove a previously registered message listener. */
   offMessage: (listener: RunnerMessageListener) => void;
 }
-/**
- * Address reported by the worker once it is ready.
- *
- * Either a TCP `host`/`port` pair or a Unix `socketPath`.
- */
+/** Address reported by the worker once it is ready. */
 export type WorkerAddress = {
   host?: string;
   port: number;

package/dist/_chunks/vercel-runner.mjs

@@ -61,6 +61,7 @@ var VercelEnvRunner = class extends NodeWorkerEnvRunner {
 		input = this._resolveFetchInput(input);
 		const headers = new Headers(input instanceof Request ? input.headers : init?.headers);
 		const requestId = generateVercelId();
+		await this._waitForAddress();
 		if (this._address && this._address.port != null && !headers.has("x-vercel-deployment-url")) {
 			const host = this._address.host || "127.0.0.1";
 			headers.set("x-vercel-deployment-url", `http://${host}:${this._address.port}`);

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 import { EnvServer } from "./_chunks/server.mjs";
 import { resolve } from "node:path";
-import { serve } from "srvx";
 import { parseArgs } from "node:util";
+import { serve } from "srvx";
 const { values, positionals } = parseArgs({
 	allowPositionals: true,
 	options: {

package/dist/index.d.mts

@@ -7,10 +7,7 @@ import { VercelEnvRunner } from "./_chunks/vercel-runner.mjs";
 import { NetlifyEnvRunner } from "./_chunks/netlify-runner.mjs";
 import { ServerOptions, ServerPlugin } from "srvx";
 import { Hooks } from "crossws";
-/**
- * Manages an active `EnvRunner` instance, proxying all calls to it.
- * Supports hot-reload, auto-restart on unexpected exit, and message queueing.
- */
+/** Proxies an active `EnvRunner` with hot-reload, auto-restart and message queueing. */
 export declare class RunnerManager implements EnvRunner, AsyncDisposable {
   private _runner;
   private _messageQueue;
@@ -27,30 +24,18 @@ export declare class RunnerManager implements EnvRunner, AsyncDisposable {
   get closed(): boolean;
   get address(): WorkerAddress | undefined;
   /**
-   * Replace the active runner with a new one. Closes the previous runner.
-   *
-   * When called without a runner, a fresh one is created via `_createRunner()`
-   * (only available on subclasses with a runner factory, e.g. `EnvServer`).
+   * Replace (and close) the active runner. Without an argument, subclasses with
+   * `_createRunner()` (e.g. `EnvServer`) create a fresh one.
    */
   reload(runner?: EnvRunner): Promise<void>;
   /** Create a fresh runner for argument-less `reload()`. Overridden by subclasses with a runner factory. */
   protected _createRunner(): EnvRunner | Promise<EnvRunner>;
   fetch: FetchHandler;
   protected _fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-  /**
-   * Lazily satisfy a pending `invalidateModule()` with a single entry reload
-   * before serving — concurrent fetches share the same reload. A failed reload
-   * keeps the invalidation pending, so the next fetch retries.
-   */
+  /** Apply a pending invalidation with one shared reload; a failure retries on the next fetch. */
   private _flushInvalidation;
   upgrade: UpgradeHandler;
-  /**
-   * Create a runtime-native WebSocket reverse-proxy plugin for the public srvx
-   * server. Attach it via `serve({ plugins: [await manager.wsSrvxPlugin()] })`:
-   * on Node it proxies the raw upgrade socket to the worker, and on Bun/Deno it
-   * bridges the WebSocket with crossws. The plugin reads the active runner
-   * lazily, so it keeps working across hot-reloads.
-   */
+  /** WebSocket proxy plugin: `serve({ plugins: [await manager.wsSrvxPlugin()] })`. */
   wsSrvxPlugin(): Promise<ServerPlugin>;
   sendMessage(message: unknown): void;
   onMessage(listener: RunnerMessageListener): void;
@@ -60,11 +45,7 @@ export declare class RunnerManager implements EnvRunner, AsyncDisposable {
     timeout?: number;
   }): Promise<T>;
   reloadModule(timeout?: number): Promise<void>;
-  /**
-   * Invalidate a virtual module on the active runner and mark the manager
-   * dirty: the next `fetch()` reloads the entry automatically, so callers
-   * don't need to pair the call with an explicit `reloadModule()`.
-   */
+  /** Invalidate a virtual module; the next `fetch()` reloads the entry automatically. */
   invalidateModule(specifier: string, timeout?: number): Promise<void>;
   close(): Promise<void>;
   [Symbol.asyncDispose](): Promise<void>;
@@ -85,11 +66,7 @@ interface LoadRunnerOptions {
   hooks?: WorkerHooks;
   data?: EnvRunnerData;
   execArgv?: string[];
-  /**
-   * Additional runner-specific options (passed through to the runner
-   * constructor) — e.g. `miniflare` (the imported `miniflare` package) for the
-   * `miniflare` runner, which this package never imports itself.
-   */
+  /** Runner-specific constructor options (e.g. `miniflare` for the `miniflare` runner). */
   [key: string]: unknown;
 }
 export declare function loadRunner(runner: RunnerName, opts: LoadRunnerOptions): Promise<EnvRunner>;
@@ -110,13 +87,7 @@ interface EnvServerOptions {
   watch?: boolean;
   /** Additional paths to watch (directories or files). */
   watchPaths?: string[];
-  /**
-   * Extra runner-specific constructor options, spread into the runner.
-   *
-   * Runners that build on external packages take them as explicit options —
-   * e.g. `{ miniflare }` for the `miniflare` runner (env-runner never imports
-   * those packages itself).
-   */
+  /** Runner-specific constructor options (e.g. `{ miniflare }`). */
   runnerOptions?: Record<string, unknown>;
 }
 export declare class EnvServer extends RunnerManager {
@@ -132,17 +103,11 @@ export declare class EnvServer extends RunnerManager {
   offReload(listener: () => void): void;
   constructor(opts: EnvServerOptions);
   /**
-   * Start the server by loading and attaching the runner.
-   *
-   * Idempotent — concurrent and repeated calls share one startup. Calling
-   * `start()` explicitly is optional: the first `fetch()` auto-starts the
-   * server. A failed start resets so a later call can retry.
+   * Load and attach the runner. Idempotent and optional (the first `fetch()`
+   * auto-starts); a failed start can be retried.
    */
   start(): Promise<this>;
-  /**
-   * Replace the active runner. When called without an argument, a fresh
-   * runner is created from the server options.
-   */
+  /** Replace the active runner; without an argument, create one from the server options. */
   reload(runner?: EnvRunner): Promise<void>;
   close(): Promise<void>;
   /** Auto-start on first fetch so an explicit `start()` call is optional. */
@@ -162,12 +127,8 @@ interface AppEntryIPC {
   onClose?: () => void | Promise<void>;
 }
 /**
- * User entry module shape. Besides `fetch` and the env-runner specific hooks
- * (`upgrade`, `websocket`, `ipc`), any srvx `ServerOptions` (e.g. `error`,
- * `maxRequestBodySize`, `trustProxy`, `node`/`bun`/`deno`) is forwarded to
- * `serve()` by the built-in workers. The listener-related keys in
- * {@link RESERVED_SERVER_OPTIONS} are owned by the worker (it sits behind the
- * runner's proxy) and are ignored if set.
+ * User entry module. Other srvx `ServerOptions` are forwarded to `serve()`,
+ * except {@link RESERVED_SERVER_OPTIONS}.
  */
 interface AppEntry extends Omit<ServerOptions, "fetch"> {
   fetch: ServerOptions["fetch"];
@@ -175,29 +136,17 @@ interface AppEntry extends Omit<ServerOptions, "fetch"> {
   websocket?: Partial<Hooks>;
   ipc?: AppEntryIPC;
 }
-/**
- * srvx options the built-in workers always control themselves: the worker
- * listens on a random loopback port behind the runner's proxy, so the entry
- * must not be able to relocate or TLS-terminate it.
- */
+/** Worker-owned srvx options: the worker listens on a random loopback port behind the proxy. */
 export declare const RESERVED_SERVER_OPTIONS: ["port", "hostname", "protocol", "tls", "silent", "manual", "gracefulShutdown"];
 /**
- * Listener/TLS keys inside the runtime-specific option objects. srvx spreads
- * `node`/`bun`/`deno` *after* its resolved port/host/tls, so these would
- * otherwise bypass {@link RESERVED_SERVER_OPTIONS}. `node.http2` is dropped
- * too: srvx requires a TLS certificate for it, which the worker never has.
+ * srvx spreads `node`/`bun`/`deno` after its resolved listener options, so
+ * these would bypass {@link RESERVED_SERVER_OPTIONS}. `node.http2` needs TLS.
  */
 export declare const RESERVED_RUNTIME_OPTIONS: {
   readonly node: readonly ["port", "host", "path", "http2", "cert", "key", "passphrase"];
   readonly bun: readonly ["port", "hostname", "unix", "tls"];
   readonly deno: readonly ["port", "hostname", "path", "cert", "key"];
 };
-/**
- * Build the srvx `serve()` options for a user entry: forwards every srvx
- * option exported by the entry, drops env-runner specific keys (`fetch`,
- * `upgrade`, `websocket`, `ipc`) and pins the worker-owned listener options
- * (top-level and nested in `node`/`bun`/`deno`). Callers add `fetch` (bound
- * lazily so module reloads swap the handler) and the crossws plugin themselves.
- */
+/** Callers add `fetch` (bound lazily so reloads swap it) and the crossws plugin. */
 export declare function toServerOptions(entry: AppEntry): Omit<ServerOptions, "fetch">;
 export { type AppEntry, type AppEntryIPC, type AppEntryIPCContext, BaseEnvRunner, DenoProcessEnvRunner, type EnvRunnerData as DenoProcessEnvRunnerData, type EnvRunner, type EnvRunnerData, type EnvServerOptions, type FetchHandler, type LoadRunnerOptions, MiniflareEnvRunner, type MiniflareEnvRunnerOptions, type MiniflareExportInfo, NetlifyEnvRunner, type NodeUpgradeContext, type RPCOptions, type RunnerMessageListener, type RunnerName, type RunnerRPCHooks, type RuntimeDep, type TransformResult, type UpgradeContext, type UpgradeHandler, VercelEnvRunner, type VirtualModuleSource, type VirtualModules, type WorkerAddress, type WorkerHooks, resolveRuntimeDep };

package/dist/runners/deno-process/worker.mjs

@@ -1,10 +1,9 @@
 import { handleInvalidateModule, isVirtualSpecifier, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
 import { serve } from "srvx";
 import { plugin } from "crossws/server";
+process.on("disconnect", () => process.exit(0));
 const data = JSON.parse(process.env.ENV_RUNNER_DATA || "{}");
-const _stdout = globalThis.Deno?.stdout ? { write: (s) => globalThis.Deno.stdout.writeSync(new TextEncoder().encode(s)) } : process.stdout;
-const sendMessage = (message) => _stdout.write(JSON.stringify(message) + "\n");
-const _stdin = globalThis.Deno?.stdin?.readable || process.stdin;
+const sendMessage = (message) => process.send(message);
 const virtualEntry = isVirtualSpecifier(data.entry, data.virtual);
 let unregisterVirtualModules;
 let entry;
@@ -35,41 +34,21 @@ if (entry.upgrade) server.node?.server?.on("upgrade", (req, socket, head) => {
 	} });
 });
 if (entry.ipc) await entry.ipc.onOpen?.({ sendMessage });
-sendMessage({ address: parseServerAddress(server) });
-async function readMessages() {
-	const decoder = new TextDecoder();
-	let buffer = "";
-	for await (const chunk of _stdin) {
-		buffer += decoder.decode(chunk, { stream: true });
-		let newlineIdx;
-		while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
-			const line = buffer.slice(0, newlineIdx);
-			buffer = buffer.slice(newlineIdx + 1);
-			if (!line) continue;
-			let message;
-			try {
-				message = JSON.parse(line);
-			} catch {
-				continue;
-			}
-			await handleMessage(message);
-		}
-	}
-}
-async function handleMessage(message) {
+process.send({ address: parseServerAddress(server) });
+process.on("message", async (message) => {
 	if (message?.event === "shutdown") {
 		Promise.resolve(entry.ipc?.onClose?.()).then(() => server.close()).then(() => {
 			unregisterVirtualModules();
-			sendMessage({ event: "exit" });
+			process.send({ event: "exit" });
 		});
 		return;
 	}
 	if (message?.event === "reload-module") {
 		try {
 			entry = await reloadEntryModule(data.entry, entry, sendMessage, virtualEntry);
-			sendMessage({ event: "module-reloaded" });
+			process.send({ event: "module-reloaded" });
 		} catch (error) {
-			sendMessage({
+			process.send({
 				event: "module-reloaded",
 				error: error?.message || String(error)
 			});
@@ -81,13 +60,12 @@ async function handleMessage(message) {
 		return;
 	}
 	if (message?.type === "ping") {
-		sendMessage({
+		process.send({
 			type: "pong",
 			data: message.data
 		});
 		return;
 	}
 	entry.ipc?.onMessage?.(message);
-}
-readMessages().catch(() => {});
+});
 export {};

package/dist/runners/vercel/queue-dev.d.mts

@@ -20,11 +20,7 @@ export type VercelQueueRetryDirective = {
 export type VercelQueueMessageHandler<T = unknown> = (message: T, metadata: VercelQueueMessageMetadata) => Promise<void> | void;
 /** Called when the message handler throws (`RetryHandler`). */
 export type VercelQueueRetryHandler = (error: unknown, metadata: VercelQueueMessageMetadata) => VercelQueueRetryDirective | void | undefined;
-/**
- * The `@vercel/queue` package, as imported by the consumer
- * (`import * as queue from "@vercel/queue"`). Structurally typed so the real
- * module namespace is assignable without env-runner depending on the package.
- */
+/** `@vercel/queue` namespace, structurally typed to avoid depending on the package. */
 export interface VercelQueueSdk {
   QueueClient: new (options?: any) => any;
   registerDevConsumer?: (options: {
@@ -39,20 +35,8 @@ export interface VercelQueueSdk {
 }
 export interface VercelQueueDevConsumer {
   /**
-   * The `@vercel/queue` package: the imported module, or a specifier for it.
-   *
-   * ```ts
-   * import * as sdk from "@vercel/queue";
-   * await registerVercelQueueConsumer({ sdk, topic: "orders", handler });
-   *
-   * // or, equivalently
-   * await registerVercelQueueConsumer({ sdk: "@vercel/queue", topic, handler });
-   * ```
-   *
-   * Passing it explicitly is preferred (`@vercel/queue` is not a dependency of
-   * `env-runner`). Bare specifiers resolve from the current working directory.
-   * When omitted, `@vercel/queue` is imported optionally and registration
-   * becomes a no-op if the package isn't installed.
+   * The `@vercel/queue` package (`import * as sdk from "@vercel/queue"`) or a
+   * specifier resolved from cwd. Omitted: imported optionally.
    */
   sdk?: RuntimeDep<VercelQueueSdk>;
   /** Topic name. Wildcard patterns (e.g. `"user-*"`) are supported. */
@@ -60,39 +44,19 @@ export interface VercelQueueDevConsumer {
   /** Function invoked with each delivered message. */
   handler: VercelQueueMessageHandler;
   /**
-   * Logical consumer identifier. Re-registering with the same group on the same
-   * topic replaces the previous handler (HMR-safe). Use distinct groups to fan
-   * a topic out to multiple coexisting handlers.
-   *
+   * Same group + topic replaces the handler; distinct groups coexist.
    * @default "env-runner-vercel-dev"
    */
   consumerGroup?: string;
-  /**
-   * Lock duration for in-flight messages. Forwarded to the SDK's
-   * `coreHandleCallback`.
-   */
+  /** Lock duration for in-flight messages (SDK `coreHandleCallback`). */
   visibilityTimeoutSeconds?: number;
-  /**
-   * Convenience: rescheduled re-delivery delay applied when the handler throws.
-   * Equivalent to `retry: () => ({ afterSeconds })`. Ignored if `retry` is set.
-   */
+  /** Re-delivery delay when the handler throws; shorthand for `retry` (which wins). */
   retryAfterSeconds?: number;
-  /**
-   * Full retry handler. Receives the thrown error and message metadata; return
-   * `{ afterSeconds }` to reschedule, `{ acknowledge: true }` to drop, or
-   * `undefined` to let the error propagate.
-   */
+  /** Return `{ afterSeconds }` to reschedule, `{ acknowledge: true }` to drop, or `undefined` to rethrow. */
   retry?: VercelQueueRetryHandler;
 }
 /**
- * Bind a handler to a topic. Resolves to an unregister function.
- *
- * A shared `QueueClient` is constructed from `sdk` on first use and reused for
- * later registrations with the same SDK. Re-registering with the same topic
- * replaces the handler (HMR-safe; the SDK keys consumers by `consumerGroup`,
- * so calling unregister on a replaced registration is a no-op).
- *
- * If no SDK is available, or it does not expose `registerDevConsumer`,
- * resolves to a no-op unregister and logs a one-time warning.
+ * Bind a handler to a topic; resolves to an unregister function (a no-op once
+ * replaced). Without a usable SDK, warns once and no-ops.
  */
 export declare function registerVercelQueueConsumer(consumer: VercelQueueDevConsumer): Promise<() => void>;

package/dist/vite.d.mts

@@ -12,17 +12,7 @@ export interface ViteTransport {
   }) => void;
   send: (payload: any) => void;
 }
-/**
- * Create a Vite `HotChannel` from an env-runner's RPC hooks.
- *
- * Use on the **host side** to bridge env-runner IPC → Vite's DevEnvironment transport.
- * Messages are namespaced by `envName` so multiple Vite environments can share one runner.
- */
+/** Host-side Vite `HotChannel`, namespaced by `envName` so environments can share a runner. */
 export declare function createViteHotChannel(hooks: RunnerRPCHooks, envName: string): ViteHotChannel;
-/**
- * Create a Vite `ModuleRunner` transport from worker-side IPC primitives.
- *
- * Use on the **worker side** to bridge worker IPC → Vite's `ModuleRunner` transport.
- * Filters messages by `envName` so multiple Vite environments can share one IPC channel.
- */
+/** Worker-side Vite `ModuleRunner` transport, filtered by `envName` to share one IPC channel. */
 export declare function createViteTransport(sendMessage: (data: any) => void, onMessage: (listener: (value: any) => void) => void, envName: string): ViteTransport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "env-runner",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Generic environment runner for JavaScript runtimes.",
   "license": "MIT",
   "repository": {
@@ -38,25 +38,25 @@
     "crossws": "^0.4.12",
     "exsolve": "^1.1.1",
     "httpxy": "^0.5.5",
-    "srvx": "^1.0.3"
+    "srvx": "^1.0.5"
   },
   "devDependencies": {
     "@netlify/runtime": "^5.0.3",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.5.1",
     "@vercel/queue": "^0.5.1",
     "@vitest/coverage-v8": "^5.0.0",
     "automd": "^0.4.3",
     "changelogen": "^0.6.2",
     "cjs-module-lexer": "^2.2.1",
     "env-runner-fixture": "link:",
-    "es-module-lexer": "^3.0.1",
+    "es-module-lexer": "^3.0.2",
     "miniflare": "^4.20260730.0",
     "obuild": "^0.4.39",
     "oxfmt": ">=0.67.0",
-    "oxlint": "^1.81.0",
+    "oxlint": "^1.82.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0",
-    "wrangler": "^4.129.0"
+    "wrangler": "^4.131.0"
   },
   "scripts": {
     "build": "obuild",