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

package/src/resolve-specifier.ts

@@ -0,0 +1,179 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ResolverFactory, type ResolveOptions } from "rolldown/experimental";
+
+/**
+ * TypeScript-aware specifier resolution on top of Oxc's resolver, mirroring
+ * what tsx layers over Node's resolver:
+ *
+ * - `tsconfig.json` `paths` / `baseUrl` aliases, discovered per importing file
+ * - emitted-extension substitution (`./x.js` → `x.ts`/`x.tsx`, `.mjs` → `.mts`,
+ *   `.cjs` → `.cts`, `.jsx` → `.tsx`), TypeScript source winning over an
+ *   emitted sibling
+ * - extensionless specifiers and directory indexes, TypeScript first
+ *
+ * Node's own resolver stays the authority: every candidate this class
+ * produces is handed back to Node (`nextResolve`) so it decides the format,
+ * validates package exports, and reports the canonical error.
+ */
+export interface SpecifierResolverOptions {
+  /** Discover `tsconfig.json` upward from each importing file. */
+  readonly tsconfig: boolean;
+}
+
+export const nodeModulesSegment = `${path.sep}node_modules${path.sep}`;
+
+/** Local project code: a file path outside every `node_modules` directory. */
+export const isProjectPath = (filePath: string) =>
+  !filePath.includes(nodeModulesSegment);
+
+const typeScriptExtensions = /\.(?:[cm]?ts|[tj]sx)$/;
+
+/** Whether TypeScript's extension substitution applies to this importer. */
+export const isTypeScriptPath = (filePath: string) =>
+  typeScriptExtensions.test(filePath);
+
+export const isFileLikeSpecifier = (specifier: string) =>
+  specifier.startsWith("./") ||
+  specifier.startsWith("../") ||
+  specifier === "." ||
+  specifier === ".." ||
+  specifier.startsWith("file:") ||
+  path.isAbsolute(specifier);
+
+/**
+ * Splits `?query#fragment` metadata off a specifier. Bare specifiers never
+ * carry fragments in Node, so only `?` is honoured there.
+ */
+export const splitSpecifierMetadata = (specifier: string) => {
+  const index = isFileLikeSpecifier(specifier)
+    ? specifier.search(/[?#]/)
+    : specifier.indexOf("?");
+  return index === -1
+    ? { specifier, metadata: "" }
+    : {
+        specifier: specifier.slice(0, index),
+        metadata: specifier.slice(index),
+      };
+};
+
+export const filePathOfUrl = (url: string | undefined) => {
+  if (url === undefined || !url.startsWith("file:")) return undefined;
+  try {
+    return fileURLToPath(new URL(url));
+  } catch {
+    return undefined;
+  }
+};
+
+export class SpecifierResolver {
+  readonly #options: ResolveOptions;
+  readonly #base: ResolverFactory;
+  readonly #byConditions = new Map<string, ResolverFactory>();
+
+  constructor(options: SpecifierResolverOptions) {
+    this.#options = {
+      tsconfig: options.tsconfig ? "auto" : undefined,
+      // TypeScript source first, then Node's implicit extensions.
+      extensions: [
+        ".ts",
+        ".tsx",
+        ".mts",
+        ".cts",
+        ".jsx",
+        ".js",
+        ".mjs",
+        ".cjs",
+        ".json",
+        ".node",
+      ],
+      // TypeScript's emitted-extension substitution: `./x.js` may point at
+      // `x.ts` (source) or `x.js` (emitted); source wins when both exist.
+      extensionAlias: {
+        ".js": [".ts", ".tsx", ".js"],
+        ".jsx": [".tsx", ".jsx"],
+        ".mjs": [".mts", ".mjs"],
+        ".cjs": [".cts", ".cjs"],
+      },
+      mainFiles: ["index"],
+      builtinModules: true,
+      moduleType: true,
+    };
+    this.#base = new ResolverFactory(this.#options);
+  }
+
+  /**
+   * Bare specifiers are probed without following symlinks: a workspace
+   * package linked into `node_modules` must still read as a package (and be
+   * left to Node), not as the project file its real path points at.
+   */
+  #resolver(conditions: ReadonlyArray<string>, symlinks: boolean) {
+    const key = `${symlinks} ${conditions.join(" ")}`;
+    let resolver = this.#byConditions.get(key);
+    if (resolver === undefined) {
+      // `cloneWithOptions` replaces the option set (sharing only the cache),
+      // so each conditions variant restates the base options.
+      resolver = this.#base.cloneWithOptions({
+        ...this.#options,
+        symlinks,
+        conditionNames: [...conditions],
+      });
+      this.#byConditions.set(key, resolver);
+    }
+    return resolver;
+  }
+
+  /**
+   * Resolves `specifier` as imported from `parentPath` to an absolute file
+   * path, or `undefined` when Oxc cannot resolve it (Node then reports the
+   * error), when it is a builtin, or when a bare specifier lands inside
+   * `node_modules` — packages are Node's business, only `paths` aliases
+   * that map onto project files are ours.
+   */
+  resolve(
+    parentPath: string,
+    specifier: string,
+    conditions: ReadonlyArray<string>,
+  ): string | undefined {
+    const request = specifier.startsWith("file:")
+      ? filePathOfUrl(specifier)
+      : specifier;
+    if (request === undefined) return undefined;
+    let result;
+    try {
+      result = this.#resolver(
+        conditions,
+        isFileLikeSpecifier(request),
+      ).resolveFileSync(parentPath, request);
+    } catch {
+      return undefined;
+    }
+    if (result.path === undefined) return undefined;
+    if (!isFileLikeSpecifier(request) && !isProjectPath(result.path)) {
+      return undefined;
+    }
+    return result.path;
+  }
+
+  /**
+   * Given a file path Node failed to find (typically an `exports`/`main`
+   * target that names emitted JavaScript that was never built), finds the
+   * TypeScript source it was emitted from via extension substitution.
+   */
+  resolveMissing(
+    missingPath: string,
+    conditions: ReadonlyArray<string>,
+  ): string | undefined {
+    const directory = path.dirname(missingPath);
+    const base = path.basename(missingPath);
+    try {
+      const result = this.#resolver(conditions, true).sync(
+        directory,
+        `./${base}`,
+      );
+      return result.path;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/transform-source.ts

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import {
+  parseSync,
+  transformSync,
+  TsconfigCache,
+  type TransformOptions,
+} from "rolldown/utils";
+import type { ImportLoaderOptions, TransformContext } from "./import-loader.ts";
+
+/** Extensions Oxc transpiles; everything else is JavaScript Node can run. */
+export const transformExtensions = new Set([
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".jsx",
+]);
+
+export type ModuleFormat = "module" | "commonjs";
+
+/**
+ * Module format from Node's `load` hook context. Node derives these from the
+ * extension and the nearest `package.json#type`; `*-typescript` variants are
+ * its TypeScript-aware spellings and mean the same thing.
+ */
+const nodeFormat = (
+  format: string | null | undefined,
+): ModuleFormat | undefined => {
+  switch (format) {
+    case "module":
+    case "module-typescript":
+      return "module";
+    case "commonjs":
+    case "commonjs-typescript":
+      return "commonjs";
+    default:
+      return undefined;
+  }
+};
+
+/** Fallback for older Nodes that pass no format: extension, then package type. */
+const inferFormat = (filePath: string): ModuleFormat => {
+  const extension = path.extname(filePath);
+  if (extension === ".mts" || extension === ".mjs") return "module";
+  if (extension === ".cts" || extension === ".cjs") return "commonjs";
+  let directory = path.dirname(filePath);
+  while (true) {
+    const packageJson = path.join(directory, "package.json");
+    if (existsSync(packageJson)) {
+      try {
+        return JSON.parse(readFileSync(packageJson, "utf8")).type === "module"
+          ? "module"
+          : "commonjs";
+      } catch {
+        return "commonjs";
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return "commonjs";
+    directory = parent;
+  }
+};
+
+const language = (filePath: string): TransformOptions["lang"] => {
+  switch (path.extname(filePath)) {
+    case ".tsx":
+      return "tsx";
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    case ".jsx":
+      return "jsx";
+    default:
+      return "js";
+  }
+};
+
+const sourceMapComment = (map: string | object) => {
+  const json = typeof map === "string" ? map : JSON.stringify(map);
+  return `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(json).toString("base64")}`;
+};
+
+export interface TransformedSource {
+  readonly format: ModuleFormat;
+  readonly source: string;
+}
+
+export class SourceTransformer {
+  readonly #options: ImportLoaderOptions;
+  readonly #tsconfigCache = new TsconfigCache();
+
+  constructor(options: ImportLoaderOptions) {
+    this.#options = options;
+  }
+
+  /**
+   * Transpiles `filePath` for Node, or returns `undefined` when the file is
+   * JavaScript that needs no work. `format` is what Node's `load` hook was
+   * told; it decides `sourceType` and the format handed back.
+   */
+  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;
+
+    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 context: TransformContext = {
+      url,
+      path: filePath,
+      format: moduleFormat,
+    };
+    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

@@ -0,0 +1,94 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import {
+  DependencyWatcher,
+  type DependencyChangeListener,
+  type DependencyWatcherOptions,
+} from "./dependency-watcher.ts";
+
+export interface BunImportTrackerOptions extends DependencyWatcherOptions {
+  /**
+   * Directory whose modules belong to the tracked graph. Files outside it and
+   * anything under a `node_modules` directory load untouched.
+   */
+  readonly root: string;
+}
+
+const loaders: Record<string, "js" | "jsx" | "ts" | "tsx"> = {
+  ".js": "js",
+  ".mjs": "js",
+  ".cjs": "js",
+  ".jsx": "jsx",
+  ".ts": "ts",
+  ".mts": "ts",
+  ".cts": "ts",
+  ".tsx": "tsx",
+};
+
+const escapeRegExp = (value: string) =>
+  value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Records every project-local module Bun loads after registration and watches
+ * those files for changes.
+ *
+ * Bun has no loader hooks that can evict or re-namespace an evaluated module,
+ * so unlike Node's {@link ImportWatcher} this cannot import a fresh
+ * generation in-process. A runtime `Bun.plugin` `onLoad` hook is used purely
+ * as a dependency probe: it hands the source back unchanged with the loader
+ * Bun would have picked itself. Callers react to a change by exiting so a
+ * supervisor can start a fresh process.
+ */
+export class BunImportTracker {
+  readonly #watcher: DependencyWatcher;
+  readonly #dependencies = new Set<string>();
+
+  constructor(options: BunImportTrackerOptions) {
+    if (process.versions.bun === undefined) {
+      throw new Error(
+        "BunImportTracker requires Bun; Node callers should use watchImport.",
+      );
+    }
+    this.#watcher = new DependencyWatcher(options);
+    // 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 filter = new RegExp(
+      `^${escapeRegExp(root)}(?!.*${escapeRegExp(nodeModules)}).*\\.[cm]?[jt]sx?$`,
+    );
+    Bun.plugin({
+      name: "@alchemy.run/node-utils/watch-import-bun",
+      setup: (build) => {
+        build.onLoad({ filter }, async (args) => {
+          this.#dependencies.add(args.path);
+          this.#watcher.set(new Set(this.#dependencies));
+          return {
+            contents: await Bun.file(args.path).text(),
+            loader: loaders[path.extname(args.path)] ?? "js",
+          };
+        });
+      },
+    });
+  }
+
+  get dependencies(): ReadonlySet<string> {
+    return this.#watcher.dependencies;
+  }
+
+  subscribe(listener: DependencyChangeListener): () => void {
+    return this.#watcher.subscribe(listener);
+  }
+
+  /** Stops watching. The load hook stays registered but only echoes sources. */
+  close(): Promise<void> {
+    return this.#watcher.close();
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close();
+  }
+}
+
+export const trackBunImports = (options: BunImportTrackerOptions) =>
+  new BunImportTracker(options);

package/src/watch-import.ts

@@ -0,0 +1,107 @@
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import {
+  DependencyWatcher,
+  type DependencyChangeListener,
+  type DependencyWatcherOptions,
+} from "./dependency-watcher.ts";
+import {
+  createImportLoader,
+  type ImportLoader,
+  type ImportLoaderOptions,
+} from "./import-loader.ts";
+
+export interface ImportGeneration<T> {
+  readonly value: T;
+  readonly namespace: string;
+  readonly dependencies: ReadonlySet<string>;
+}
+
+export interface ImportWatcherOptions
+  extends ImportLoaderOptions, DependencyWatcherOptions {
+  readonly parentURL: string;
+}
+
+/**
+ * Imports fresh Node module generations and watches the exact files loaded by
+ * the current generation. Bun callers should use `BunImportTracker` from
+ * `./watch-import-bun.ts`: Bun cannot evict evaluated modules, so a change
+ * there restarts the process instead of importing a new generation.
+ */
+export class ImportWatcher<T = unknown> {
+  readonly #specifier: string;
+  readonly #options: ImportWatcherOptions;
+  readonly #watcher: DependencyWatcher;
+  #registration: ImportLoader | undefined;
+  #dependencies = new Set<string>();
+  #closed = false;
+
+  constructor(specifier: string, options: ImportWatcherOptions) {
+    this.#specifier = specifier;
+    this.#options = options;
+    this.#watcher = new DependencyWatcher(options);
+  }
+
+  get dependencies(): ReadonlySet<string> {
+    return this.#dependencies;
+  }
+
+  subscribe(listener: DependencyChangeListener): () => void {
+    return this.#watcher.subscribe(listener);
+  }
+
+  async import(): Promise<ImportGeneration<T>> {
+    if (this.#closed) throw new Error("ImportWatcher is closed");
+    const namespace = randomUUID();
+    const dependencies = new Set<string>();
+    const {
+      debounceMs: _,
+      parentURL,
+      watch: _watch,
+      ...registerOptions
+    } = this.#options;
+    const registration = await createImportLoader({
+      ...registerOptions,
+      namespace,
+      onImport: (url) => {
+        if (!url.startsWith("file:")) return;
+        dependencies.add(fileURLToPath(url));
+        // A lazy import evaluated after this generation became current
+        // extends the watched set immediately.
+        if (this.#dependencies === dependencies)
+          this.#watcher.set(dependencies);
+      },
+    });
+    try {
+      const value = await registration.import<T>(this.#specifier, parentURL);
+      await this.#registration?.unregister();
+      this.#registration = registration;
+      this.#dependencies = dependencies;
+      this.#watcher.set(dependencies);
+      return { value, namespace, dependencies };
+    } catch (error) {
+      await registration.unregister();
+      // Keep watching everything the failed import touched so the next save
+      // of any of those files retries.
+      this.#dependencies = new Set([...this.#dependencies, ...dependencies]);
+      this.#watcher.set(this.#dependencies);
+      throw error;
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    await this.#registration?.unregister();
+    await this.#watcher.close();
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close();
+  }
+}
+
+export const watchImport = <T = unknown>(
+  specifier: string,
+  options: ImportWatcherOptions,
+) => new ImportWatcher<T>(specifier, options);