@alchemy.run/node-utils 2.0.0-beta.77 → 2.0.0-beta.78

package/src/transform-source.ts

@@ -1,12 +1,15 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveTsconfig } from "rolldown/experimental";
 import {
   parseSync,
   transformSync,
   TsconfigCache,
   type TransformOptions,
 } from "rolldown/utils";
-import type { ImportLoaderOptions, TransformContext } from "./import-loader.ts";
+import type { OxcLoaderOptions } from "./register-oxc.ts";
+import { resolveCacheDirectory, TransformCache } from "./transform-cache.ts";
 
 /** Extensions Oxc transpiles; everything else is JavaScript Node can run. */
 export const transformExtensions = new Set([
@@ -77,22 +80,93 @@ const language = (filePath: string): TransformOptions["lang"] => {
   }
 };
 
-const sourceMapComment = (map: string | object) => {
+/**
+ * Inline map, for when there is no cache file to point at. Only the
+ * fallback: the base64 becomes part of the script source V8 retains, and
+ * for a non-ASCII source it is stored two bytes per character on top.
+ */
+const inlineSourceMapComment = (map: string | object) => {
   const json = typeof map === "string" ? map : JSON.stringify(map);
   return `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(json).toString("base64")}`;
 };
 
+/**
+ * Map by reference. Node's source-map support only understands `data:`
+ * URLs and scheme-less paths (it resolves the latter against the module
+ * URL and reads the file), so this is the file URL's path component —
+ * `/var/…/x.map` on POSIX, `/C:/…/x.map` on Windows — never a `file:` URL.
+ */
+const fileSourceMapComment = (mapFile: string) =>
+  `\n//# sourceMappingURL=${pathToFileURL(mapFile).pathname}`;
+
+/**
+ * The transform's map without `sourcesContent`. Every source is a file on
+ * this machine, named by the map's `sources`, so embedding its text only
+ * makes the map larger than the code it describes and every process that
+ * loads the module pay for it.
+ */
+const withoutSourcesContent = ({
+  sourcesContent: _,
+  ...map
+}: NonNullable<ReturnType<typeof transformSync>["map"]>) => map;
+
 export interface TransformedSource {
   readonly format: ModuleFormat;
   readonly source: string;
 }
 
 export class SourceTransformer {
-  readonly #options: ImportLoaderOptions;
+  readonly #options: OxcLoaderOptions;
   readonly #tsconfigCache = new TsconfigCache();
+  readonly #cache: TransformCache | undefined;
 
-  constructor(options: ImportLoaderOptions) {
+  constructor(options: OxcLoaderOptions) {
     this.#options = options;
+    const directory = resolveCacheDirectory(options.cache);
+    this.#cache =
+      directory === undefined ? undefined : new TransformCache(directory);
+  }
+
+  /**
+   * Cache key for one transform, or `undefined` when the result must not be
+   * cached. Every input Oxc's output depends on is part of it: the file's
+   * path (source maps name it), its size and mtime standing in for its
+   * contents — a stat instead of a read plus a hash per module on the warm
+   * path — the effective transform options, Node's module format, and the
+   * tsconfig that would be discovered for the file, resolved through the
+   * same cache `transformSync` uses with the `extends` chain already
+   * merged, so editing any tsconfig in the chain is a new key.
+   */
+  #cacheKey(
+    filePath: string,
+    options: TransformOptions,
+    format: ModuleFormat,
+  ): string | undefined {
+    if (this.#cache === undefined) return undefined;
+    let stat: { size: bigint; mtimeNs: bigint };
+    try {
+      stat = statSync(filePath, { bigint: true });
+    } catch {
+      return undefined;
+    }
+    let tsconfig: unknown = null;
+    try {
+      if (options.tsconfig === true) {
+        tsconfig = resolveTsconfig(filePath, this.#tsconfigCache)?.tsconfig;
+      } else if (typeof options.tsconfig === "string") {
+        tsconfig = readFileSync(options.tsconfig, "utf8");
+      }
+    } catch {
+      // A broken tsconfig is the transform's error to report; don't cache.
+      return undefined;
+    }
+    return this.#cache.key([
+      filePath,
+      `${stat.size}:${stat.mtimeNs}`,
+      JSON.stringify(options),
+      JSON.stringify(tsconfig ?? null),
+      format,
+    ]);
   }
 
   /**
@@ -102,69 +176,79 @@ export class SourceTransformer {
    */
   transform(
     filePath: string,
-    url: string,
     format: string | null | undefined,
   ): TransformedSource | undefined {
     const extension = path.extname(filePath);
-    const transpile = transformExtensions.has(extension);
-    if (!transpile && this.#options.transforms === undefined) return undefined;
+    if (!transformExtensions.has(extension)) return undefined;
 
     let moduleFormat = nodeFormat(format) ?? inferFormat(filePath);
-    let source = readFileSync(filePath, "utf8");
-    let map: string | object | undefined;
-    if (transpile) {
-      const lang = this.#options.transform?.lang ?? language(filePath);
-      // A `.ts` file in a CommonJS package that uses `import`/`export` runs
-      // as ESM — the same call Node's own module-syntax detection makes for
-      // `.js`. Explicit `.cts` stays CommonJS regardless.
-      if (
-        moduleFormat === "commonjs" &&
-        extension !== ".cts" &&
-        parseSync(filePath, source, { lang, sourceType: "unambiguous" }).module
-          .hasModuleSyntax
-      ) {
-        moduleFormat = "module";
-      }
-      const transformed = transformSync(
-        filePath,
-        source,
-        {
-          tsconfig: this.#options.tsconfig ?? true,
-          sourcemap: true,
-          ...this.#options.transform,
-          lang,
-          sourceType: this.#options.transform?.sourceType ?? moduleFormat,
-        },
-        this.#tsconfigCache,
-      );
-      if (transformed.errors.length > 0) {
-        const [error] = transformed.errors;
-        throw error instanceof Error
-          ? error
-          : new SyntaxError(
-              `${filePath}: ${(error as { message?: string }).message ?? String(error)}`,
-            );
-      }
-      source = transformed.code;
-      map = transformed.map;
+    const lang = language(filePath);
+    const options: TransformOptions = {
+      tsconfig: this.#options.tsconfig ?? true,
+      sourcemap: true,
+      lang,
+    };
+    // The key is taken before the source is read so a hit costs one stat
+    // and one cache read, never the source itself.
+    const key = this.#cacheKey(filePath, options, moduleFormat);
+    const cached = key === undefined ? undefined : this.#cache?.get(key);
+    if (cached !== undefined) {
+      return {
+        format: cached.format,
+        source:
+          cached.mapFile === undefined
+            ? cached.code
+            : cached.code + fileSourceMapComment(cached.mapFile),
+      };
     }
-
-    const context: TransformContext = {
-      url,
-      path: filePath,
+    const source = readFileSync(filePath, "utf8");
+    // A `.ts` file in a CommonJS package that uses `import`/`export` runs
+    // as ESM — the same call Node's own module-syntax detection makes for
+    // `.js`. Explicit `.cts` stays CommonJS regardless.
+    if (
+      moduleFormat === "commonjs" &&
+      extension !== ".cts" &&
+      parseSync(filePath, source, { lang, sourceType: "unambiguous" }).module
+        .hasModuleSyntax
+    ) {
+      moduleFormat = "module";
+    }
+    const transformed = transformSync(
+      filePath,
+      source,
+      { ...options, sourceType: moduleFormat },
+      this.#tsconfigCache,
+    );
+    if (transformed.errors.length > 0) {
+      const [error] = transformed.errors;
+      throw error instanceof Error
+        ? error
+        : new SyntaxError(
+            `${filePath}: ${(error as { message?: string }).message ?? String(error)}`,
+          );
+    }
+    const map =
+      transformed.map === undefined
+        ? undefined
+        : JSON.stringify(withoutSourcesContent(transformed.map));
+    // The map ends up in the module exactly one way: on disk next to the
+    // cache entry and referenced by path, or (cache off) inlined.
+    const mapFile =
+      key === undefined || map === undefined
+        ? undefined
+        : this.#cache?.set(key, {
+            format: moduleFormat,
+            code: transformed.code,
+            map,
+          });
+    return {
       format: moduleFormat,
+      source:
+        mapFile !== undefined
+          ? transformed.code + fileSourceMapComment(mapFile)
+          : map !== undefined
+            ? transformed.code + inlineSourceMapComment(map)
+            : transformed.code,
     };
-    for (const transform of this.#options.transforms ?? []) {
-      const result = transform(source, context);
-      if (typeof result === "string") {
-        source = result;
-        map = undefined;
-      } else if (result !== undefined) {
-        source = result.code;
-        map = result.map;
-      }
-    }
-    if (map !== undefined) source += sourceMapComment(map);
-    return { format: moduleFormat, source };
   }
 }

package/src/watch-import-bun.ts

@@ -53,9 +53,14 @@ export class BunImportTracker {
     // Bun reports real paths (`/private/tmp/...` for `/tmp/...` on macOS);
     // match them against the root's real path too.
     const root = realpathSync.native(path.resolve(options.root)) + path.sep;
-    const nodeModules = `${path.sep}node_modules${path.sep}`;
+    const nodeModules = `node_modules${path.sep}`;
+    // `root` already ends in a separator, so the segment right after it has no
+    // leading one: a `.*${sep}node_modules${sep}` lookahead alone would miss
+    // `<root>node_modules/...` and intercept every dependency. Bun cannot
+    // return CommonJS source from `onLoad` (oven-sh/bun#19279), so a CJS
+    // dependency that reaches this probe loses its exports.
     const filter = new RegExp(
-      `^${escapeRegExp(root)}(?!.*${escapeRegExp(nodeModules)}).*\\.[cm]?[jt]sx?$`,
+      `^${escapeRegExp(root)}(?!(?:.*${escapeRegExp(path.sep)})?${escapeRegExp(nodeModules)}).*\\.[cm]?[jt]sx?$`,
     );
     Bun.plugin({
       name: "@alchemy.run/node-utils/watch-import-bun",

package/src/watch-import.ts

@@ -5,11 +5,7 @@ import {
   type DependencyChangeListener,
   type DependencyWatcherOptions,
 } from "./dependency-watcher.ts";
-import {
-  createImportLoader,
-  type ImportLoader,
-  type ImportLoaderOptions,
-} from "./import-loader.ts";
+import type { OxcLoader, OxcLoaderOptions } from "./register-oxc.ts";
 
 export interface ImportGeneration<T> {
   readonly value: T;
@@ -18,7 +14,7 @@ export interface ImportGeneration<T> {
 }
 
 export interface ImportWatcherOptions
-  extends ImportLoaderOptions, DependencyWatcherOptions {
+  extends OxcLoaderOptions, DependencyWatcherOptions {
   readonly parentURL: string;
 }
 
@@ -32,7 +28,7 @@ export class ImportWatcher<T = unknown> {
   readonly #specifier: string;
   readonly #options: ImportWatcherOptions;
   readonly #watcher: DependencyWatcher;
-  #registration: ImportLoader | undefined;
+  #registration: OxcLoader | undefined;
   #dependencies = new Set<string>();
   #closed = false;
 
@@ -60,7 +56,10 @@ export class ImportWatcher<T = unknown> {
       watch: _watch,
       ...registerOptions
     } = this.#options;
-    const registration = await createImportLoader({
+    // Loaded here, not at module scope: the exec child imports this file on
+    // both runtimes, and the loader's Node hooks do not exist under Bun.
+    const { registerOxc } = await import("./register-oxc.ts");
+    const registration = registerOxc({
       ...registerOptions,
       namespace,
       onImport: (url) => {

package/lib/import-loader.d.ts

@@ -1,54 +0,0 @@
-import type { TransformOptions } from "rolldown/utils";
-export interface TransformContext {
-    readonly url: string;
-    readonly path: string;
-    readonly format: "module" | "commonjs";
-}
-export interface SourceTransformResult {
-    readonly code: string;
-    readonly map?: string | object | undefined;
-}
-export type SourceTransform = (code: string, context: TransformContext) => string | SourceTransformResult | undefined;
-export interface ImportLoaderOptions {
-    /**
-     * Additional package export conditions used during module resolution.
-     * They are made available alongside Node's ambient conditions to both the
-     * TypeScript-aware resolver and Node's package exports resolver.
-     */
-    readonly conditions?: ReadonlyArray<string> | undefined;
-    /**
-     * Oxc transform configuration, layered over the nearest `tsconfig.json`
-     * of each transformed file (`jsx`, decorators, …).
-     */
-    readonly transform?: TransformOptions | undefined;
-    /** Additional synchronous source transforms, applied after Oxc. */
-    readonly transforms?: ReadonlyArray<SourceTransform> | undefined;
-    /**
-     * Honour `tsconfig.json` discovered upward from each file: compiler
-     * options for the transform, `paths`/`baseUrl` aliases for resolution.
-     * @default true
-     */
-    readonly tsconfig?: boolean | undefined;
-    /** Controls which file URLs belong to the fresh import graph. */
-    readonly shouldInvalidate?: ((url: string, parentURL: string | undefined) => boolean) | undefined;
-    /**
-     * Limits transformation to matching absolute file paths; everything else
-     * loads through Node untouched. Lets a published install transpile only
-     * the user's own TypeScript while alchemy and its dependencies run their
-     * built JavaScript.
-     */
-    readonly filter?: ((path: string) => boolean) | undefined;
-}
-export interface ImportLoaderRegistrationOptions extends ImportLoaderOptions {
-    /** Isolates one import graph in the runtime's module cache. */
-    readonly namespace?: string | undefined;
-    /** Called once the runtime loads a file in this registration's graph. */
-    readonly onImport?: ((url: string) => void) | undefined;
-}
-export interface ImportLoader {
-    import<T = unknown>(specifier: string, parentURL: string): Promise<T>;
-    unregister(): void | Promise<void>;
-}
-/** Creates a Node import loader using synchronous module hooks backed by Oxc. */
-export declare const createImportLoader: (options?: ImportLoaderRegistrationOptions) => Promise<ImportLoader>;
-//# sourceMappingURL=import-loader.d.ts.map

package/lib/import-loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"import-loader.d.ts","sourceRoot":"","sources":["../src/import-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;CACxC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAClD,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,SAAS,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,gBAAgB,CAAC,EACtB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,GACzD,SAAS,CAAC;IACd;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CAC3D;AAED,MAAM,WAAW,+BAAgC,SAAQ,mBAAmB;IAC1E,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACzD;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtE,UAAU,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,aACpB,+BAA+B,KACvC,OAAO,CAAC,YAAY,CAQtB,CAAC"}

package/lib/import-loader.js

@@ -1,9 +0,0 @@
-/** Creates a Node import loader using synchronous module hooks backed by Oxc. */
-export const createImportLoader = async (options = {}) => {
-    if (process.versions.bun !== undefined) {
-        throw new Error("The import-aware loader is only available in Node; use Bun's process-level watcher instead.");
-    }
-    const { registerOxc } = await import("./register-oxc.js");
-    return registerOxc(options);
-};
-//# sourceMappingURL=import-loader.js.map

package/lib/import-loader.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"import-loader.js","sourceRoot":"","sources":["../src/import-loader.ts"],"names":[],"mappings":"AA+DA,iFAAiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,OAAO,GAAoC,EAAE,EACtB,EAAE;IACzB,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,6FAA6F,CAC9F,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC1D,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC,CAAC"}

package/src/import-loader.ts

@@ -1,75 +0,0 @@
-import type { TransformOptions } from "rolldown/utils";
-
-export interface TransformContext {
-  readonly url: string;
-  readonly path: string;
-  readonly format: "module" | "commonjs";
-}
-
-export interface SourceTransformResult {
-  readonly code: string;
-  readonly map?: string | object | undefined;
-}
-
-export type SourceTransform = (
-  code: string,
-  context: TransformContext,
-) => string | SourceTransformResult | undefined;
-
-export interface ImportLoaderOptions {
-  /**
-   * Additional package export conditions used during module resolution.
-   * They are made available alongside Node's ambient conditions to both the
-   * TypeScript-aware resolver and Node's package exports resolver.
-   */
-  readonly conditions?: ReadonlyArray<string> | undefined;
-  /**
-   * Oxc transform configuration, layered over the nearest `tsconfig.json`
-   * of each transformed file (`jsx`, decorators, …).
-   */
-  readonly transform?: TransformOptions | undefined;
-  /** Additional synchronous source transforms, applied after Oxc. */
-  readonly transforms?: ReadonlyArray<SourceTransform> | undefined;
-  /**
-   * Honour `tsconfig.json` discovered upward from each file: compiler
-   * options for the transform, `paths`/`baseUrl` aliases for resolution.
-   * @default true
-   */
-  readonly tsconfig?: boolean | undefined;
-  /** Controls which file URLs belong to the fresh import graph. */
-  readonly shouldInvalidate?:
-    | ((url: string, parentURL: string | undefined) => boolean)
-    | undefined;
-  /**
-   * Limits transformation to matching absolute file paths; everything else
-   * loads through Node untouched. Lets a published install transpile only
-   * the user's own TypeScript while alchemy and its dependencies run their
-   * built JavaScript.
-   */
-  readonly filter?: ((path: string) => boolean) | undefined;
-}
-
-export interface ImportLoaderRegistrationOptions extends ImportLoaderOptions {
-  /** Isolates one import graph in the runtime's module cache. */
-  readonly namespace?: string | undefined;
-  /** Called once the runtime loads a file in this registration's graph. */
-  readonly onImport?: ((url: string) => void) | undefined;
-}
-
-export interface ImportLoader {
-  import<T = unknown>(specifier: string, parentURL: string): Promise<T>;
-  unregister(): void | Promise<void>;
-}
-
-/** Creates a Node import loader using synchronous module hooks backed by Oxc. */
-export const createImportLoader = async (
-  options: ImportLoaderRegistrationOptions = {},
-): Promise<ImportLoader> => {
-  if (process.versions.bun !== undefined) {
-    throw new Error(
-      "The import-aware loader is only available in Node; use Bun's process-level watcher instead.",
-    );
-  }
-  const { registerOxc } = await import("./register-oxc.ts");
-  return registerOxc(options);
-};