npm - env-runner - Versions diffs - 0.1.0 → 0.1.2 - Mend

env-runner 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md +180 -8
package/dist/_chunks/base-runner.d.mts +7 -62
package/dist/_chunks/base-runner.mjs +65 -0
package/dist/_chunks/libs/std-env.mjs +1 -1
package/dist/_chunks/runner.d.mts +2 -1
package/dist/_chunks/runner.mjs +13 -5
package/dist/_chunks/runner2.d.mts +51 -2
package/dist/_chunks/runner2.mjs +404 -83
package/dist/_chunks/server.mjs +48 -0
package/dist/_chunks/types.d.mts +76 -0
package/dist/_chunks/worker-utils.mjs +11 -1
package/dist/cli.mjs +1 -1
package/dist/index.d.mts +10 -3
package/dist/runners/bun-process/runner.d.mts +2 -1
package/dist/runners/bun-process/runner.mjs +29 -8
package/dist/runners/bun-process/worker.mjs +26 -5
package/dist/runners/deno-process/worker.mjs +26 -5
package/dist/runners/miniflare/runner.d.mts +2 -2
package/dist/runners/node-process/runner.d.mts +2 -1
package/dist/runners/node-process/worker.mjs +26 -5
package/dist/runners/node-worker/runner.d.mts +2 -1
package/dist/runners/node-worker/worker.mjs +26 -5
package/dist/runners/self/runner.d.mts +12 -1
package/dist/runners/self/runner.mjs +13 -1
package/dist/vite.d.mts +32 -0
package/dist/vite.mjs +58 -0
package/package.json +3 -2

package/README.md CHANGED Viewed

@@ -141,24 +141,33 @@ const response = await runner.fetch("http://localhost/api");
 // Proxy WebSocket upgrades
 runner.upgrade?.({ node: { req, socket, head } });
+// Wait for runner to be ready
+await runner.waitForReady();
 // Bidirectional messaging
 runner.sendMessage({ type: "ping" });
 runner.onMessage((msg) => console.log(msg));
+// Request-response RPC
+const result = await runner.rpc<string>("transformHTML", "<html>...</html>");
+// Hot-reload entry module without restarting the worker
+await runner.reloadModule();
 // Graceful shutdown
 await runner.close();
 ```
 **Available runners:**
-| Runner                 | Isolation                      | IPC mechanism                       |
-| ---------------------- | ------------------------------ | ----------------------------------- |
-| `NodeWorkerEnvRunner`  | Worker thread                  | `workerData` / `parentPort`         |
-| `NodeProcessEnvRunner` | Child process (`fork`)         | `ENV_RUNNER_DATA` / `process.send`  |
-| `BunProcessEnvRunner`  | Bun or Node.js process         | `Bun.spawn` IPC or `fork()`         |
-| `DenoProcessEnvRunner` | Deno process                   | `deno run` with IPC channel         |
-| `SelfEnvRunner`        | In-process                     | In-memory channel                   |
-| `MiniflareEnvRunner`   | Cloudflare Workers (miniflare) | `serviceBindings` + `dispatchFetch` |
+| Runner                 | Isolation                      | IPC mechanism                      |
+| ---------------------- | ------------------------------ | ---------------------------------- |
+| `NodeWorkerEnvRunner`  | Worker thread                  | `workerData` / `parentPort`        |
+| `NodeProcessEnvRunner` | Child process (`fork`)         | `ENV_RUNNER_DATA` / `process.send` |
+| `BunProcessEnvRunner`  | Bun or Node.js process         | `Bun.spawn` IPC or `fork()`        |
+| `DenoProcessEnvRunner` | Deno process                   | `deno run` with IPC channel        |
+| `SelfEnvRunner`        | In-process                     | In-memory channel                  |
+| `MiniflareEnvRunner`   | Cloudflare Workers (miniflare) | WebSocket pair via `dispatchFetch` |
 #### Miniflare Runner
@@ -186,6 +195,165 @@ await runner.close();
 The `miniflareOptions` object is passed directly to the [Miniflare constructor](https://developers.cloudflare.com/workers/testing/miniflare/) — you can configure bindings, KV, D1, Durable Objects, and any other Miniflare option.
+#### Module Transform Pipeline
+Pass a `transformRequest` callback to route module resolution through Vite's (or any) transform pipeline. This enables TS, JSX, and other non-JS formats to be compiled on-the-fly inside the Workers runtime without pre-bundling:
+```ts
+import { MiniflareEnvRunner } from "env-runner/runners/miniflare";
+const runner = new MiniflareEnvRunner({
+  name: "my-worker",
+  data: { entry: "./worker.ts" },
+  // Route module resolution through Vite's transform pipeline
+  transformRequest: (id) => viteDevEnvironment.transformRequest(id),
+});
+```
+When `transformRequest` is provided:
+- The `unsafeModuleFallbackService` calls it with the resolved file path before falling back to raw disk reads
+- Module rules for `.ts`, `.tsx`, `.jsx`, and `.mts` are added automatically
+- Static `export *` re-exports are skipped in the wrapper to avoid miniflare's ModuleLocator pre-walking the import tree
+The callback should return `{ code: string }` for transformed modules, or `null`/`undefined` to fall back to the default raw file read.
+#### Auto-detected Exports
+`MiniflareEnvRunner` automatically scans the entry file for `export class` declarations and wires them as Durable Object bindings (binding name = class name). This means you don't need to manually configure `miniflareOptions.durableObjects` for simple cases:
+```ts
+// worker.ts
+export class Counter {
+  /* ... Durable Object implementation ... */
+}
+export default {
+  async fetch(request, env) {
+    // env.Counter is auto-wired — no manual config needed
+    const id = env.Counter.idFromName("test");
+    const stub = env.Counter.get(id);
+    return stub.fetch(request);
+  },
+};
+```
+To explicitly declare exports or override auto-detection:
+```ts
+const runner = new MiniflareEnvRunner({
+  name: "my-worker",
+  data: { entry: "./worker.ts" },
+  // Explicit exports (merged with auto-detected ones)
+  exports: { Counter: { type: "DurableObject" } },
+});
+```
+Set `exports: false` to disable auto-detection entirely.
+#### Error Capture
+By default, the runner wraps the user's `fetch` handler in a try/catch that returns structured JSON error responses with preserved stack traces:
+```json
+{
+  "error": "Cannot read properties of undefined",
+  "stack": "Error: Cannot read properties...\n    at fetch (worker.ts:10:5)",
+  "name": "TypeError"
+}
+```
+Error responses include `Content-Type: application/json` and `X-Env-Runner-Error: 1` headers. Disable with `captureErrors: false`.
+#### Persistent Miniflare
+By default, `close()` disposes the Miniflare instance. With `persistent: true`, the Miniflare instance is cached and reused across runner swaps — only the IPC connection is re-established:
+```ts
+const runner1 = new MiniflareEnvRunner({
+  name: "my-worker",
+  data: { entry: "./worker.ts" },
+  persistent: true,
+});
+// Later, after close() + creating a new runner with the same config,
+// the Miniflare instance is reused (faster startup)
+await runner1.close();
+const runner2 = new MiniflareEnvRunner({
+  name: "my-worker",
+  data: { entry: "./worker.ts" },
+  persistent: true,
+});
+// Fully destroy: runner.dispose() or MiniflareEnvRunner.disposeAll()
+```
+### Vite Environment API
+env-runner provides helpers for integrating with Vite's [Environment API](https://vite.dev/guide/api-environment-runtimes.html):
+```ts
+import { createViteHotChannel, createViteTransport } from "env-runner/vite";
+```
+**Host side** — create a Vite `HotChannel` from any runner's messaging hooks:
+```ts
+import { createViteHotChannel } from "env-runner/vite";
+// Bridge env-runner IPC → Vite's DevEnvironment transport
+const transport = createViteHotChannel(runner, "ssr");
+const env = new DevEnvironment("ssr", config, { hot: true, transport });
+```
+**Worker side** — create a `ModuleRunner` transport:
+```ts
+import { createViteTransport } from "env-runner/vite";
+const transport = createViteTransport(sendMessage, onMessage, "ssr");
+const runner = new ModuleRunner({ transport, sourcemapInterceptor: "prepareStackTrace" });
+```
+Messages are namespaced by environment name, so multiple Vite environments can share a single runner's IPC channel.
+**Miniflare + Vite** — combine `MiniflareEnvRunner.transformRequest` with Vite helpers for a full Cloudflare Workers dev environment with HMR and on-the-fly transforms:
+```ts
+import { MiniflareEnvRunner } from "env-runner/runners/miniflare";
+import { createViteHotChannel } from "env-runner/vite";
+const runner = new MiniflareEnvRunner({
+  name: "worker",
+  data: { entry: "./src/worker.ts" },
+  transformRequest: (id) => devEnvironment.transformRequest(id),
+});
+const hotChannel = createViteHotChannel(runner, "worker");
+```
+### RPC
+Send request-response messages over IPC with automatic ID generation, timeout, and error propagation:
+```ts
+// Host side
+const html = await runner.rpc<string>("transformHTML", rawHtml, { timeout: 5000 });
+// Worker side (in entry's ipc.onMessage)
+onMessage(msg) {
+  if (msg?.__rpc === "transformHTML") {
+    const result = await transform(msg.data);
+    sendMessage({ __rpc_id: msg.__rpc_id, data: result });
+  }
+}
+```
+Errors can be propagated back by sending `{ __rpc_id, error: "message" }`.
+### Dynamic Runner Loading
 You can also use `loadRunner()` to dynamically load a runner by name:
 ```ts
@@ -207,6 +375,10 @@ export default {
   fetch(request: Request) {
     return new Response("Hello!");
   },
+  upgrade(context) {
+    // Optional: handle WebSocket upgrade requests (Node.js only)
+    // context.node gives { req, socket, head }
+  },
   middleware: [], // Optional srvx middleware
   plugins: [], // Optional srvx plugins
   ipc: {

package/dist/_chunks/base-runner.d.mts CHANGED Viewed

@@ -1,67 +1,7 @@
+import { a as RunnerMessageListener, l as WorkerAddress, t as EnvRunner, u as WorkerHooks } from "./types.mjs";
 import { IncomingMessage } from "node:http";
 import { Socket } from "node:net";
-//#region src/types.d.ts
-/** Handler for proxying HTTP requests to the worker. */
-type FetchHandler = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-/** Callback for receiving messages from the worker. */
-type RunnerMessageListener = (data: unknown) => void;
-/** Raw Node.js upgrade request context. */
-interface NodeUpgradeContext {
-  req: IncomingMessage;
-  socket: Socket;
-  head: any;
-}
-/** Context passed to the upgrade handler for WebSocket upgrades. */
-interface UpgradeContext {
-  node: NodeUpgradeContext;
-}
-/** Handler for proxying WebSocket upgrade requests to the worker. */
-type UpgradeHandler = (context: UpgradeContext) => void;
-/** Bidirectional RPC messaging interface between the runner and worker. */
-interface RunnerRPCHooks {
-  /** Send a message to the worker. */
-  sendMessage: (message: unknown) => void;
-  /** Register a listener for messages from the worker. */
-  onMessage: (listener: RunnerMessageListener) => void;
-  /** 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`.
- */
-type WorkerAddress = {
-  host?: string;
-  port: number;
-  socketPath?: undefined;
-} | {
-  host?: undefined;
-  port?: undefined;
-  socketPath: string;
-};
-/** Lifecycle hooks for observing runner state changes. */
-interface WorkerHooks {
-  /** Called when the worker closes, optionally with the cause. */
-  onClose?: (worker: EnvRunner, cause?: unknown) => void;
-  /** Called when the worker is ready and listening at the given address. */
-  onReady?: (worker: EnvRunner, address?: WorkerAddress) => void;
-}
-/** Core runner interface combining lifecycle hooks, RPC, and request proxying. */
-interface EnvRunner extends WorkerHooks, RunnerRPCHooks {
-  /** Whether the worker is ready to accept requests. */
-  readonly ready: boolean;
-  /** Whether the runner has been closed. */
-  readonly closed: boolean;
-  /** Proxy an HTTP request to the worker. */
-  fetch: FetchHandler;
-  /** Proxy a WebSocket upgrade request to the worker. */
-  upgrade?: UpgradeHandler;
-  /** Gracefully shut down the worker. */
-  close(): Promise<void>;
-}
-//#endregion
 //#region src/common/base-runner.d.ts
 interface EnvRunnerData {
   name?: string;
@@ -93,6 +33,11 @@ declare abstract class BaseEnvRunner implements EnvRunner {
   abstract sendMessage(message: unknown): void;
   onMessage(listener: RunnerMessageListener): void;
   offMessage(listener: RunnerMessageListener): void;
+  waitForReady(timeout?: number): Promise<void>;
+  rpc<T = unknown>(name: string, data?: unknown, opts?: {
+    timeout?: number;
+  }): Promise<T>;
+  reloadModule(timeout?: number): Promise<void>;
   close(cause?: unknown): Promise<void>;
   protected _handleMessage(message: any): void;
   protected _closeSocket(): Promise<void>;
@@ -102,4 +47,4 @@ declare abstract class BaseEnvRunner implements EnvRunner {
   protected abstract _runtimeType(): string;
 }
 //#endregion
-export { NodeUpgradeContext as a, UpgradeContext as c, WorkerHooks as d, FetchHandler as i, UpgradeHandler as l, EnvRunnerData as n, RunnerMessageListener as o, EnvRunner as r, RunnerRPCHooks as s, BaseEnvRunner as t, WorkerAddress as u };
+export { EnvRunnerData as n, BaseEnvRunner as t };

package/dist/_chunks/base-runner.mjs CHANGED Viewed

@@ -35,6 +35,71 @@ var BaseEnvRunner = class {
 	offMessage(listener) {
 		this._messageListeners.delete(listener);
 	}
+	waitForReady(timeout = 5e3) {
+		if (this.ready) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this._messageListeners.delete(listener);
+				reject(/* @__PURE__ */ new Error("Runner did not become ready in time"));
+			}, timeout);
+			const listener = () => {
+				if (this.ready) {
+					clearTimeout(timer);
+					this._messageListeners.delete(listener);
+					resolve();
+				}
+			};
+			this._messageListeners.add(listener);
+		});
+	}
+	rpc(name, data, opts) {
+		const id = Math.random().toString(36).slice(2);
+		const timeout = opts?.timeout ?? 3e3;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error(`RPC "${name}" timed out`));
+			}, timeout);
+			const listener = (msg) => {
+				if (msg?.__rpc_id === id) {
+					cleanup();
+					if (msg.error) reject(typeof msg.error === "string" ? new Error(msg.error) : msg.error);
+					else resolve(msg.data);
+				}
+			};
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.offMessage(listener);
+			};
+			this.onMessage(listener);
+			this.sendMessage({
+				__rpc: name,
+				__rpc_id: id,
+				data
+			});
+		});
+	}
+	async reloadModule(timeout = 5e3) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Module reload timed out"));
+			}, timeout);
+			const listener = (msg) => {
+				if (msg?.event === "module-reloaded") {
+					cleanup();
+					if (msg.error) reject(typeof msg.error === "string" ? new Error(msg.error) : msg.error);
+					else resolve();
+				}
+			};
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.offMessage(listener);
+			};
+			this.onMessage(listener);
+			this.sendMessage({ event: "reload-module" });
+		});
+	}
 	async close(cause) {
 		if (this.closed) return;
 		this.closed = true;

package/dist/_chunks/libs/std-env.mjs CHANGED Viewed

@@ -1,4 +1,4 @@
-//#region node_modules/.deno/std-env@4.0.0-rc.1/node_modules/std-env/dist/index.mjs
+//#region node_modules/.pnpm/std-env@4.0.0-rc.1/node_modules/std-env/dist/index.mjs
 const e = globalThis.process?.env || Object.create(null), t = globalThis.process || { env: e }, n = t !== void 0 && t.env && t.env.NODE_ENV || void 0, r = [
 	[`claude`, [`CLAUDECODE`, `CLAUDE_CODE`]],
 	[`replit`, [`REPL_ID`]],

package/dist/_chunks/runner.d.mts CHANGED Viewed

@@ -1,4 +1,5 @@
-import { d as WorkerHooks, n as EnvRunnerData, t as BaseEnvRunner } from "./base-runner.mjs";
+import { u as WorkerHooks } from "./types.mjs";
+import { n as EnvRunnerData, t as BaseEnvRunner } from "./base-runner.mjs";
 //#region src/runners/deno-process/runner.d.ts
 declare class DenoProcessEnvRunner extends BaseEnvRunner {

package/dist/_chunks/runner.mjs CHANGED Viewed

@@ -26,11 +26,17 @@ var DenoProcessEnvRunner = class extends BaseEnvRunner {
 	}
 	async _closeRuntime() {
 		if (!this.#process) return;
-		await this._requestGracefulShutdown(() => this.#process.send({ event: "shutdown" }), (resolve) => {
+		if (this.#process._exitCode == null) await this._requestGracefulShutdown(() => {
+			try {
+				this.#process.send({ event: "shutdown" });
+			} catch {}
+		}, (resolve) => {
 			this.#process?.exited.then(() => resolve());
 		}, () => this.#process?._exitCode != null);
 		this.#process.removeAllListeners?.();
-		this.#process.kill();
+		try {
+			this.#process.kill();
+		} catch {}
 		this.#process = void 0;
 	}
 	#initProcess(execArgv) {
@@ -73,9 +79,11 @@ var DenoProcessEnvRunner = class extends BaseEnvRunner {
 			handle._exitCode = code;
 			this.close(`process exited with code ${code}`);
 		});
-		child.once("error", (error) => {
-			console.error(`Process error:`, error);
-			this.close(error);
+		child.on("error", (error) => {
+			if (!this.closed) {
+				console.error(`Process error:`, error);
+				this.close(error);
+			}
 		});
 		child.on("message", (message) => {
 			this._handleMessage(message);

package/dist/_chunks/runner2.d.mts CHANGED Viewed

@@ -1,21 +1,70 @@
-import { d as WorkerHooks, n as EnvRunnerData, t as BaseEnvRunner } from "./base-runner.mjs";
+import { u as WorkerHooks } from "./types.mjs";
+import { n as EnvRunnerData, t as BaseEnvRunner } from "./base-runner.mjs";
 //#region src/runners/miniflare/runner.d.ts
+/** Result from a module transform (compatible with Vite's `TransformResult`). */
+interface TransformResult {
+  code: string;
+}
+/** Detected or declared export for auto-wiring Durable Object / Entrypoint bindings. */
+interface MiniflareExportInfo {
+  type?: "DurableObject" | "WorkerEntrypoint" | "class";
+}
 interface MiniflareEnvRunnerOptions {
   name: string;
   hooks?: WorkerHooks;
   data?: EnvRunnerData;
   /** Options passed directly to the Miniflare constructor. */
   miniflareOptions?: Record<string, unknown>;
+  /**
+   * Optional module transform callback. When provided, the module fallback
+   * service calls this instead of reading raw files from disk.
+   *
+   * This enables integration with Vite's transform pipeline — pass
+   * `environment.transformRequest` to get TS/JSX/etc. compiled on the fly.
+   *
+   * @param id - Absolute file path of the module to transform
+   * @returns Transformed code, or null/undefined to fall back to raw disk read
+   */
+  transformRequest?: (id: string) => Promise<TransformResult | null | undefined>;
+  /**
+   * Declare named exports (Durable Objects, WorkerEntrypoints) to auto-wire
+   * bindings and generate re-exports in the wrapper module.
+   *
+   * When set to `true`, `export class` declarations are auto-detected from
+   * the entry file. When set to a record, the listed exports are used
+   * (merged with auto-detected ones). Disabled by default.
+   */
+  exports?: Record<string, MiniflareExportInfo> | boolean;
+  /**
+   * When `true`, the Miniflare instance is cached and reused across runner
+   * swaps (e.g. via `RunnerManager.reload()`). `close()` tears down IPC but
+   * keeps Miniflare alive. Call `dispose()` to fully destroy it.
+   */
+  persistent?: boolean;
+  /** Wrap the user's `fetch` in a try/catch that returns structured JSON error responses. Default: `true`. */
+  captureErrors?: boolean;
 }
 declare class MiniflareEnvRunner extends BaseEnvRunner {
   #private;
   constructor(opts: MiniflareEnvRunnerOptions);
+  /** Dispose all persistent Miniflare instances from the cache. */
+  static disposeAll(): Promise<void>;
+  /** Fully dispose the Miniflare instance (even if persistent). */
+  dispose(): Promise<void>;
   fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
   sendMessage(message: unknown): void;
+  /**
+   * Hot-reload the user entry module without recreating the Miniflare instance.
+   *
+   * Sends `reload-module` event over the WebSocket. The worker wrapper uses
+   * `unsafeEvalBinding` to re-import the entry with a cache-busting query string
+   * and responds with `module-reloaded` when done.
+   */
+  reloadModule(timeout?: number): Promise<void>;
   protected _hasRuntime(): boolean;
   protected _runtimeType(): string;
   protected _closeRuntime(): Promise<void>;
 }
 //#endregion
-export { MiniflareEnvRunnerOptions as n, MiniflareEnvRunner as t };
+export { TransformResult as i, MiniflareEnvRunnerOptions as n, MiniflareExportInfo as r, MiniflareEnvRunner as t };