env-runner 0.3.0 → 0.3.1

package/dist/_chunks/common-base-runner.d.mts

@@ -1,6 +1,414 @@
 import { EnvRunner, ResolvedVirtualModule, RunnerMessageListener, VirtualModuleUpdates, VirtualModules, WorkerAddress, WorkerHooks } from "./types.mjs";
-import { IncomingMessage } from "node:http";
 import { Socket } from "node:net";
+import { MessagePort } from "node:worker_threads";
+import { IncomingMessage } from "node:http";
+/**
+ * Module type of code: `js`, `jsx`, `ts`, `tsx` and `json` from the
+ * extension, other extensions as themselves (`vue` for `.vue`), `js` without
+ * an extension.
+ */
+export type PluginModuleType = "js" | "jsx" | "ts" | "tsx" | "json" | (string & {});
+/** A RegExp as sent to workers (`glob`: compiled from an `id` glob). */
+interface SerializedPattern {
+  source: string;
+  flags: string;
+  glob?: true;
+}
+/** A filter expression as sent to workers. */
+type SerializedFilterNode = {
+  kind: "and" | "or";
+  args: SerializedFilterNode[];
+} | {
+  kind: "not";
+  expr: SerializedFilterNode;
+} | {
+  kind: "id";
+  pattern: SerializedPattern;
+} | {
+  kind: "code";
+  pattern: string | SerializedPattern;
+} | {
+  kind: "moduleType";
+  pattern: string;
+} | {
+  kind: "query";
+  key: string;
+  pattern: string | boolean | SerializedPattern;
+};
+interface SerializedFilterExpression {
+  kind: "include" | "exclude";
+  expr: SerializedFilterNode;
+}
+/**
+ * A plugin's filter as workers check it: its `id`/`moduleType` filters, or
+ * its filter expressions (`code` is unknown there).
+ */
+interface SerializedPrefilter {
+  id?: {
+    include: SerializedPattern[];
+    exclude: SerializedPattern[];
+  };
+  moduleTypes?: PluginModuleType[];
+  expr?: SerializedFilterExpression[];
+  /**
+   * A `load` filter: it can't name module types, so a module its `id`
+   * include (or include expression) names counts as `"typed"`
+   * ({@link PrefilterMatch}).
+   */
+  load?: true;
+  /** A `resolveId` hook for imports the runtime fails to resolve. */
+  fallback?: true;
+}
+type MaybeArray<T> = T | T[];
+/** Include values, or `{ include, exclude }` (exclude wins). */
+export type PluginStringFilter = MaybeArray<string | RegExp> | {
+  include?: MaybeArray<string | RegExp>;
+  exclude?: MaybeArray<string | RegExp>;
+};
+/**
+ * `transform` hook filter (all given properties must match; empty ones are
+ * ignored). Ids are matched `/`-separated and with their query string: the
+ * glob `**\/*.svg` and the RegExp `/\.svg$/` don't match `/app/a.svg?raw`, but
+ * `/\.svg(?:\?.*)?$/` does (or add a `query` filter expression).
+ * - `id`: RegExps are tested, strings are globs: `*` (within a path segment),
+ *   `?`, `**` (any number of segments), `[abc]`/`[!abc]`, `{a,b}` and `\`
+ *   escapes, case-sensitive; `*` and `**` also match dot files and
+ *   directories. Globs not starting with `**` and not absolute resolve from
+ *   the working directory when the runner is created.
+ * - `code`: strings are substrings, RegExps are tested.
+ * - `moduleType`: see {@link PluginModuleType}.
+ *
+ * `id` and `moduleType` are also checked in the worker, before a module is
+ * sent to the runner: give plugins both where possible, so other modules
+ * load without a round trip.
+ */
+export interface PluginTransformFilter {
+  id?: PluginStringFilter;
+  code?: PluginStringFilter;
+  moduleType?: PluginModuleType[] | {
+    include?: PluginModuleType[];
+  };
+}
+/**
+ * `resolveId` and `load` hook filter: `id` only, matched like
+ * {@link PluginTransformFilter} `id`. For `resolveId` it is the import
+ * specifier (with its query) and globs match it as written (not resolved
+ * from the working directory).
+ */
+export interface PluginHookFilter {
+  id?: PluginStringFilter;
+}
+/**
+ * A filter expression, matched like the {@link PluginTransformFilter}
+ * properties. `query` parses the id's query with `URLSearchParams`: `true`
+ * matches when `key` is present (`?raw`), `false` when it's absent, a string
+ * equals its value, a RegExp tests it (`""` when absent). `importerId` is
+ * rejected. `resolveId` and `load` filters take no `code` or `moduleType`
+ * expressions.
+ */
+export type PluginFilterExpression = {
+  kind: "and" | "or";
+  args: PluginFilterExpression[];
+} | {
+  kind: "not";
+  expr: PluginFilterExpression;
+} | {
+  kind: "id" | "importerId";
+  pattern: string | RegExp;
+} | {
+  kind: "code";
+  pattern: string | RegExp;
+} | {
+  kind: "moduleType";
+  pattern: PluginModuleType;
+} | {
+  kind: "query";
+  key: string;
+  pattern: string | RegExp | boolean;
+};
+/**
+ * A filter as a list of include and exclude expressions: the first one that
+ * matches decides (an include matches, an exclude doesn't); if none does, the
+ * module matches only when there are no includes. The worker's prefilter
+ * sends a module unless the expressions can't match whatever its code.
+ */
+export interface PluginTopLevelFilterExpression {
+  kind: "include" | "exclude";
+  expr: PluginFilterExpression;
+}
+/** Passed to every handler. */
+export interface PluginTransformMeta {
+  /** Language of `code` (updated by results returning a `moduleType`). */
+  moduleType: PluginModuleType;
+}
+/**
+ * A message for {@link PluginContext}: a string, or a log object. A log's
+ * `loc` (1-based line, 0-based column) or `pos` (an offset) is used when no
+ * position is given, and its `frame` is shown below the message.
+ */
+export type PluginLog = string | {
+  message: string;
+  loc?: {
+    line: number;
+    column: number;
+    file?: string;
+  };
+  pos?: number;
+  frame?: string;
+};
+/** An offset in the code, or a 1-based line and 0-based column. */
+export type PluginLogPosition = number | {
+  line: number;
+  column: number;
+};
+/**
+ * `this` in handlers. Messages are prefixed with the plugin name and module
+ * id, and a position given is appended to the id (`id:line:column`).
+ */
+export interface PluginContext {
+  /** Log a warning (on the host). */
+  warn(log: PluginLog, pos?: PluginLogPosition): void;
+  /** Log a message (on the host). */
+  info(log: PluginLog, pos?: PluginLogPosition): void;
+  /** Ignored (debug messages aren't shown). */
+  debug(log: PluginLog, pos?: PluginLogPosition): void;
+  /**
+   * Throw an error (an `Error` or log object given is kept as its `cause`).
+   * Errors a handler throws are reported the same way, with their `loc`,
+   * `pos` and `frame`.
+   */
+  error(log: PluginLog, pos?: PluginLogPosition): never;
+  /**
+   * Resolve an import like the runner would, on the host: the `resolveId`
+   * hooks (with `skipSelf`, the default, without the calling plugin's), then
+   * Node.js ESM resolution from `importer` (or the working directory) with
+   * the runner's export conditions: a file path, a builtin (`external`), or
+   * `null` when it doesn't resolve. No extensions or directory indexes are
+   * tried, as in Node.js.
+   */
+  resolve(source: string, importer?: string, options?: PluginContextResolveOptions): Promise<PluginResolvedId | null>;
+  /** Ignored: the runner doesn't watch files (nothing is ever returned). */
+  addWatchFile(id: string): void;
+  /** Always empty (see `addWatchFile`). */
+  getWatchFiles(): string[];
+  /** `watchMode` is `false`: plugins aren't told about file changes. */
+  meta: {
+    watchMode: boolean;
+  };
+}
+/**
+ * Runs on the host and may be async. Return nullish to keep the code. `id` is
+ * the module's path with the import's query (`/app/a.ts?raw`), or an id a
+ * `resolveId` hook returned.
+ */
+export type PluginTransformHandler = (this: PluginContext, code: string, id: string, meta: PluginTransformMeta) => PluginTransformResult | Promise<PluginTransformResult>;
+/**
+ * New code, or `{ code, map, moduleType }`: a `moduleType` tells later
+ * handlers the new language (e.g. `js` after compiling TypeScript).
+ * `moduleSideEffects` and `meta` are accepted and ignored.
+ */
+export type PluginTransformResult = string | {
+  code?: string;
+  map?: SourceMapLike | string | null;
+  moduleType?: PluginModuleType;
+  moduleSideEffects?: unknown;
+  meta?: unknown;
+} | null | undefined;
+/** Options of {@link PluginContext.resolve}. */
+export interface PluginContextResolveOptions {
+  /**
+   * Skip the calling plugin's `resolveId` hook, also when other plugins call
+   * `this.resolve()` with the same source and importer meanwhile (default
+   * `true`; only for calls from `resolveId`).
+   */
+  skipSelf?: boolean;
+  isEntry?: boolean;
+  attributes?: Record<string, string>;
+}
+/** Passed to `resolveId` handlers. */
+export interface PluginResolveIdOptions {
+  /** Whether this is the runner's entry. */
+  isEntry: boolean;
+  /** Import attributes (`with { type: "json" }`), when the runtime reports them. */
+  attributes: Record<string, string>;
+}
+/**
+ * Runs on the host for the imports its filter matches (the import specifier
+ * as written, with its query, `file:` URLs as paths) and may be async.
+ * `importer` is the importing module's id (a path with its query, or an id a
+ * `resolveId` returned), `undefined` for the entry.
+ */
+export type PluginResolveIdHandler = (this: PluginContext, source: string, importer: string | undefined, options: PluginResolveIdOptions) => PluginResolveIdResult | Promise<PluginResolveIdResult>;
+/**
+ * The module's id, or nullish to try the next plugin (then the runtime
+ * resolves it). An absolute path loads that file (through `load` hooks,
+ * then from disk); any other id (like `\0virtual:foo`) must be loaded by a
+ * `load` hook. `false` or `external` leaves the import (or the returned id)
+ * to the runtime. `moduleSideEffects`, `meta` and other properties are
+ * ignored.
+ */
+export type PluginResolveIdResult = string | false | {
+  id: string;
+  external?: boolean | "absolute" | "relative";
+  [key: string]: unknown;
+} | null | undefined;
+/**
+ * Runs on the host for the modules its filter matches and may be async:
+ * return the module's code, or nullish to try the next plugin (then the file
+ * is read from disk, without the id's query). `transform` hooks run on the
+ * result. `id` is like the {@link PluginTransformHandler} one.
+ */
+export type PluginLoadHandler = (this: PluginContext, id: string) => PluginLoadResult | Promise<PluginLoadResult>;
+/**
+ * Code, or `{ code, map, moduleType }`: without a `moduleType`, it is the
+ * id's ({@link PluginModuleType}), `js` for other extensions.
+ * `moduleSideEffects` and `meta` are accepted and ignored.
+ */
+export type PluginLoadResult = string | {
+  code: string;
+  map?: SourceMapLike | string | null;
+  moduleType?: PluginModuleType;
+  moduleSideEffects?: unknown;
+  meta?: unknown;
+} | null | undefined;
+interface SourceMapLike {
+  version?: number;
+  mappings: string;
+  names?: string[];
+  sources?: string[];
+  sourcesContent?: (string | null)[];
+}
+/** A hook: its handler, or `{ order, filter, handler }`. */
+export type PluginHook<Handler, Filter> = Handler | {
+  order?: "pre" | "post" | null;
+  filter?: Filter | PluginTopLevelFilterExpression[];
+  handler: Handler;
+};
+/**
+ * A runner plugin. Plugins live on the host: workers send the imports and
+ * modules their filters match to the runner, which runs the hooks and sends
+ * the result back. Each hook runs in `plugins` order within its `order`
+ * group: `"pre"`, then unordered, then `"post"` (plugins are sorted by
+ * `enforce` first). Other properties (and hooks) are ignored.
+ *
+ * - `resolveId`: resolve an import; the first result wins.
+ * - `load`: provide a module's code; the first result wins.
+ * - `transform`: change a module's code; every matching handler runs.
+ */
+export interface EnvRunnerPlugin {
+  name?: string;
+  /**
+   * Orders the whole plugin: `"pre"` plugins come first and `"post"` last,
+   * keeping `plugins` order within each group. Each hook's own `order`
+   * applies on top of that.
+   */
+  enforce?: "pre" | "post";
+  resolveId?: PluginResolveIdHook;
+  load?: PluginHook<PluginLoadHandler, PluginHookFilter>;
+  transform?: PluginHook<PluginTransformHandler, PluginTransformFilter>;
+}
+/**
+ * A `resolveId` hook. With `fallback: true`, it only runs for imports the
+ * runtime fails to resolve (the worker tries first, so imports it resolves
+ * take no round trip), after the other `resolveId` hooks, which run before
+ * the runtime.
+ */
+export type PluginResolveIdHook = PluginResolveIdHandler | {
+  order?: "pre" | "post" | null;
+  filter?: PluginHookFilter | PluginTopLevelFilterExpression[];
+  fallback?: boolean;
+  handler: PluginResolveIdHandler;
+};
+/** `plugins` option entries: nested arrays are flattened, falsy ones skipped. */
+export type EnvRunnerPluginOption = EnvRunnerPlugin | EnvRunnerPluginOption[] | false | null | undefined;
+/** Result of {@link PluginPipeline.transform} and {@link PluginPipeline.load}. */
+interface PluginTransformOutput {
+  /** The new code, with an inline source map when a plugin returned one. */
+  code: string;
+  /**
+   * `js`; `ts` when no plugin compiled it (the worker strips the types where
+   * the runtime does it natively, like for untransformed files); `json` for
+   * JSON (served as a JSON module).
+   */
+  moduleType: "js" | "ts" | "json";
+}
+/** Options of {@link PluginPipeline.resolveId}. */
+interface PluginResolveIdCallOptions extends Partial<PluginResolveIdOptions> {
+  /** Run the `fallback` hooks: the runtime failed to resolve the import. */
+  fallback?: boolean;
+}
+/** Result of {@link PluginPipeline.resolveId}. */
+export type PluginResolvedId = {
+  id: string;
+  /** Leave the import (as `id`) to the runtime. */
+  external: boolean;
+};
+/** The `plugins` option of a runner, ready to run on the host. */
+interface PluginPipeline {
+  /** Plugin names, in `plugins` order. */
+  names: string[];
+  /** The `load` and `transform` filters as the worker's prefilter checks them. */
+  prefilters: SerializedPrefilter[];
+  /** The `resolveId` filters as the worker's prefilter checks them. */
+  resolvePrefilters: SerializedPrefilter[];
+  /**
+   * Whether a module goes through the plugins: some `load` or `transform`
+   * filter may match (its `code` parts aren't checked). Modules of other than
+   * script types only match filters naming them (see {@link requiredMatch}),
+   * and disk modules under `/node_modules/` only ones naming that, unless
+   * `resolved` (a `resolveId` hook returned the path) or an id with a
+   * `moduleType` (virtual modules) is given.
+   */
+  filter(id: string, moduleType?: PluginModuleType, resolved?: boolean): boolean;
+  /**
+   * Whether some `resolveId` filter matches an import specifier (`fallback`:
+   * of the hooks for imports the runtime can't resolve).
+   */
+  resolveFilter(source: string, fallback?: boolean): boolean;
+  /**
+   * Run the `resolveId` hooks (`fallback`: those for imports the runtime
+   * failed to resolve): the first result, or `undefined` when none resolved
+   * it (the runtime resolves it, or fails). Rejects with their errors.
+   */
+  resolveId(source: string, importer?: string, options?: PluginResolveIdCallOptions): Promise<PluginResolvedId | undefined>;
+  /**
+   * Run the `load` hooks, then the `transform` hooks on the loaded code. When
+   * no `load` hook returned code, `read()` reads the module (none: rejects,
+   * the id isn't a file), and the result is `undefined` when no plugin changed
+   * it (load it as if unmatched). Rejects like {@link PluginPipeline.transform}.
+   */
+  load(id: string, read?: () => string, options?: {
+    resolved?: boolean;
+  }): Promise<PluginTransformOutput | undefined>;
+  /**
+   * Run the `transform` hooks: `undefined` when none changed the code (load it
+   * as if unmatched). Rejects with their errors (naming the plugin and id), and
+   * when the code changed but is still neither JavaScript, TypeScript nor JSON
+   * (e.g. JSX no plugin compiled).
+   */
+  transform(id: string, code: string, moduleType?: PluginModuleType): Promise<PluginTransformOutput | undefined>;
+}
+/** How a worker reaches the runner's plugins (part of the runner data). */
+interface TransformChannel {
+  port?: MessagePort;
+  state?: Int32Array;
+  socket?: string;
+}
+/** Runner side of an open channel. */
+interface TransformChannelHost {
+  /** Sent to the worker (`port` must be in the transfer list). */
+  channel: TransformChannel;
+  close(): void;
+}
+/** Runner data key of {@link PluginWorkerData} (only set with the `plugins` option). */
+declare const PLUGINS_DATA_KEY = "__envRunnerPlugins";
+/** What a worker gets for the runner's `plugins`. */
+interface PluginWorkerData extends TransformChannel {
+  /** `load` and `transform` filters. */
+  prefilters: SerializedPrefilter[];
+  /** `resolveId` filters (none: imports are never sent). */
+  resolvePrefilters?: SerializedPrefilter[];
+}
 export interface EnvRunnerData {
   name?: string;
   /**
@@ -29,11 +437,22 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
   protected _virtualResolved?: Promise<void>;
   protected _virtualUpdates: Promise<void>;
   protected _processData?: string;
+  protected _plugins?: PluginPipeline;
+  protected _transformChannel?: TransformChannelHost;
   constructor(opts: {
     name: string;
     workerEntry: string;
     hooks?: WorkerHooks;
     data?: EnvRunnerData;
+    /**
+     * Plugins whose `resolveId`, `load` and `transform` hooks run on the host
+     * for the imports, disk modules and virtual modules their filters match
+     * (e.g. compiling TypeScript enums and JSX, or serving generated modules).
+     * The worker sends each matching import or module to the runner and uses
+     * the result. Nested arrays are flattened and falsy entries skipped. Not
+     * supported by the `self` runner.
+     */
+    plugins?: EnvRunnerPluginOption[];
   });
   get ready(): boolean;
   get address(): WorkerAddress | undefined;
@@ -83,6 +502,20 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
    * base64; throws if not JSON-serializable.
    */
   protected _processEnv(): NodeJS.ProcessEnv;
+  /**
+   * Export conditions the runtime resolves packages with, for the plugins'
+   * `this.resolve()` (`undefined`: Node.js's). Called lazily, after the
+   * subclass constructor.
+   */
+  protected _resolveConditions(): string[] | undefined;
+  /**
+   * Runner data entries for the `plugins` option (none without plugins): the
+   * plugins' prefilters and a transform channel, opened on the first call.
+   * A `port` channel's `MessagePort` must be transferred to the worker.
+   */
+  protected _pluginWorkerData(kind: "port" | "socket"): {
+    [PLUGINS_DATA_KEY]?: PluginWorkerData;
+  };
   /**
    * Process worker messages: answer the `request-init-data` handshake with the
    * runner data (internal, not forwarded to listeners), handle everything else.