env-runner 0.2.1 → 0.2.3

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

@@ -3,147 +3,100 @@ import { BaseEnvRunner, EnvRunnerData } from "./common-base-runner.mjs";
 import { RuntimeDep } from "./common-runtime-deps.mjs";
 import { IncomingMessage } from "node:http";
 import { Socket } from "node:net";
-/**
- * The `wrangler` package, as imported by the consumer.
- *
- * `wrangler` is not a dependency of `env-runner` — pass the module namespace
- * (`import * as wrangler from "wrangler"`) or a specifier for it, so the
- * dependency stays owned by the application. It is only imported here as a
- * fallback when neither is passed.
- */
-interface WranglerModule {
+/** The `wrangler` package namespace, as imported by the app. */
+export interface WranglerModule {
   unstable_readConfig?: (...args: any[]) => any;
   unstable_getMiniflareWorkerOptions?: (...args: any[]) => any;
   [key: string]: unknown;
 }
 /** Raw (snake_case) Wrangler config object, mirroring `wrangler.json` contents. */
-type WranglerInlineConfig = Record<string, unknown>;
+export type WranglerInlineConfig = Record<string, unknown>;
 /** Result from a module transform (compatible with Vite's `TransformResult`). */
-interface TransformResult {
+export interface TransformResult {
   code: string;
 }
 /** Detected or declared export for auto-wiring Durable Object / Entrypoint bindings. */
-interface MiniflareExportInfo {
+export interface MiniflareExportInfo {
   type?: "DurableObject" | "WorkerEntrypoint" | "class";
 }
-/**
- * The `miniflare` package, as imported by the consumer.
- *
- * `miniflare` is not a dependency of `env-runner` — pass the module namespace
- * (`import * as miniflare from "miniflare"`) so the dependency stays owned by
- * the application. The runner only falls back to importing it itself when this
- * is omitted.
- */
-interface MiniflareModule {
+/** The `miniflare` package namespace, as imported by the app. */
+export interface MiniflareModule {
   Miniflare: new (options: any) => any;
-  /**
-   * Newest compatibility date supported by the installed `workerd` binary,
-   * clamped to today. Used as the default `compatibilityDate`.
-   */
+  /** Newest date the installed `workerd` supports, clamped to today. */
   supportedCompatibilityDate?: string;
   [key: string]: unknown;
 }
-interface MiniflareEnvRunnerOptions {
+export interface MiniflareEnvRunnerOptions {
   name: string;
   hooks?: WorkerHooks;
   data?: EnvRunnerData;
   /**
-   * The `miniflare` package: the imported module, or a specifier for it.
-   *
-   * ```ts
-   * import * as miniflare from "miniflare";
-   * new MiniflareEnvRunner({ name: "app", miniflare, data: { entry } });
-   *
-   * // or, equivalently
-   * new MiniflareEnvRunner({ name: "app", miniflare: "miniflare", data: { entry } });
-   * ```
-   *
-   * Passing it explicitly is preferred (`miniflare` is not a dependency of
-   * `env-runner`, so the version you install is the version that runs). Bare
-   * specifiers resolve from the current working directory. When omitted, the
-   * runner falls back to importing `miniflare` itself and only fails if that
-   * is unavailable too.
+   * The `miniflare` package (`import * as miniflare from "miniflare"`) or a
+   * specifier resolved from cwd. Omitted: imported optionally.
    */
   miniflare?: RuntimeDep<MiniflareModule>;
   /** 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
+   * `"latest"` uses the installed workerd's newest date. Precedence:
+   * `miniflareOptions` > this > wrangler config > newest supported. Dates newer
+   * than workerd supports fall back with a warning (workerd refuses them).
    */
-  transformRequest?: (id: string) => Promise<TransformResult | null | undefined>;
+  compatibilityDate?: "latest" | (string & {});
   /**
-   * 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.
+   * Transform modules served by the fallback service (e.g. Vite's
+   * `environment.transformRequest`). `id` is an absolute path; return nullish to
+   * read from disk.
    */
-  exports?: Record<string, MiniflareExportInfo> | boolean;
+  transformRequest?: (id: string) => Promise<TransformResult | null | undefined>;
   /**
-   * 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.
+   * Named exports (Durable Objects, WorkerEntrypoints) to bind and re-export.
+   * `true` detects `export class`; a record merges with detected ones.
    */
+  exports?: Record<string, MiniflareExportInfo> | boolean;
+  /** Reuse the Miniflare instance across runner swaps; only `dispose()` destroys it. */
   persistent?: boolean;
   /** Wrap the user's `fetch` in a try/catch that returns structured JSON error responses. Default: `true`. */
   captureErrors?: boolean;
-  /**
-   * Export conditions for bare-specifier module resolution in the module
-   * fallback service. Ensures packages with conditional exports (e.g.
-   * `"workerd"`) resolve to the correct entry instead of the Node.js one.
-   *
-   * Defaults to `["workerd", "worker"]`.
-   */
+  /** Export conditions for the fallback service (default `["workerd", "worker"]`). */
   exportConditions?: string[];
   /**
-   * Load a Cloudflare `wrangler` config to populate Miniflare options
-   * (compatibility date/flags and bindings: `vars`, KV, R2, D1, Durable
-   * Objects, queues).
+   * Load a wrangler config into Miniflare options (compat date/flags, bindings).
    *
-   * - `true` — auto-discover `wrangler.{json,jsonc,toml}` next to the entry
-   *   file, then in the current working directory.
-   * - `string` — explicit path to a wrangler config file.
-   * - `object` — an inline raw (snake_case) wrangler config, as you would
-   *   write in `wrangler.json` (no file needed). A config file is still
-   *   auto-discovered (next to the entry, then cwd) and the inline config is
-   *   merged on top of it (inline wins per key, binding records merge,
-   *   `compatibilityFlags` are unioned).
+   * - `true` — auto-discover `wrangler.{json,jsonc,toml}` near the entry or cwd
+   * - `string` — config file path
+   * - `object` — inline raw config merged over the file config (inline wins per
+   *   key, binding records merge, flags union); its top level is used when it
+   *   lacks the selected env
    *
-   * The `wrangler` package is used for full fidelity when available (TOML,
-   * `env` inheritance, `.dev.vars`, every binding type; an inline config is
-   * normalized through a short-lived temp file) — passed explicitly as
-   * `wranglerModule`, or imported optionally. Otherwise a built-in minimal
-   * reader handles plain JSON files and inline objects (common fields only);
-   * JSONC and TOML files are skipped with a warning. Values from
-   * `miniflareOptions` always win over config-derived ones; binding records
-   * (e.g. `bindings`) merge per key and `compatibilityFlags` are unioned.
+   * Options a single dev worker can't run (`assets`, services, queue consumers,
+   * workflows, tails, other-script Durable Objects) are dropped with a warning.
+   * `defaultPersistRoot` defaults to `.wrangler/state/v3` next to the config
+   * (else cwd), shared with `wrangler dev`. The `wrangler` package gives full
+   * fidelity (and may run its npm update check); without it only plain JSON is
+   * read. `miniflareOptions` always win.
    */
   wrangler?: boolean | string | WranglerInlineConfig;
   /**
-   * Wrangler environment (`--env`) to select when loading the config.
-   * Defaults to the `CLOUDFLARE_ENV` environment variable.
+   * Config file instead of auto-discovery when `wrangler` is `true` or inline
+   * (resolved from cwd). Ignored when `wrangler` is a path.
    */
+  wranglerConfigPath?: string;
+  /** Wrangler `--env` to select (default: `CLOUDFLARE_ENV`). */
   wranglerEnv?: string;
   /**
-   * The imported `wrangler` package (`import * as wrangler from "wrangler"`),
-   * used to parse the {@link MiniflareEnvRunnerOptions.wrangler} config with
-   * full fidelity. When omitted, `import("wrangler")` is tried, and a built-in
-   * minimal reader (plain JSON configs and inline objects) handles the rest.
-   *
-   * Pass `false` to skip the `wrangler` package entirely and always use the
-   * built-in minimal reader.
+   * `.env` files for dev vars (like `getPlatformProxy({ envFiles })`), resolved
+   * from the config dir; later files win. Non-empty skips `.dev.vars`; `[]`
+   * reads only `.dev.vars`. Requires the `wrangler` package.
+   */
+  wranglerEnvFiles?: string[];
+  /**
+   * The `wrangler` package for full-fidelity config parsing. Omitted: imported
+   * optionally. `false`: always use the minimal JSON reader.
    */
   wranglerModule?: RuntimeDep<WranglerModule>;
 }
-declare class MiniflareEnvRunner extends BaseEnvRunner {
+export declare class MiniflareEnvRunner extends BaseEnvRunner {
   #private;
   constructor(opts: MiniflareEnvRunnerOptions);
   /** Dispose all persistent Miniflare instances from the cache. */
@@ -152,24 +105,11 @@ declare class MiniflareEnvRunner extends BaseEnvRunner {
   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.
-   */
+  /** Hot-reload the entry without recreating the Miniflare instance. */
   reloadModule(timeout?: number): Promise<void>;
   /**
-   * Invalidate a virtual module so the next `reloadModule()` re-evaluates it.
-   *
-   * Host-side only (no worker round-trip): the module fallback service serves
-   * virtual sources from a live map, so re-running a factory source and
-   * bumping the per-specifier versions — the module plus its transitive
-   * virtual importers — is enough. Import specifiers in re-served module code
-   * are rewritten to the versioned form, giving workerd fresh module
-   * identities (it caches by name). A `persistent` instance is evicted from
-   * the cache, since its served sources no longer match the cache key.
+   * Host-side only: the fallback service serves a live map, so bumping versions
+   * (see {@link rewriteVirtualImports}) is enough.
    */
   invalidateModule(specifier: string, _timeout?: number): Promise<void>;
   protected _hasRuntime(): boolean;
@@ -182,5 +122,4 @@ declare class MiniflareEnvRunner extends BaseEnvRunner {
       head: any;
     };
   }): Promise<void>;
-}
-export { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, MiniflareModule, TransformResult, WranglerInlineConfig, WranglerModule };
+}