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

package/src/dependency-watcher.ts

@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { watch, type ChokidarOptions, type FSWatcher } from "chokidar";
+
+export interface DependencyChange {
+  readonly paths: ReadonlySet<string>;
+}
+
+export type DependencyChangeListener = (change: DependencyChange) => void;
+
+export interface DependencyWatcherOptions {
+  /** Chokidar options passed to the file watcher. */
+  readonly watch?: ChokidarOptions | undefined;
+  readonly debounceMs?: number | undefined;
+}
+
+/**
+ * Watches an explicit set of absolute file paths and delivers debounced
+ * batches only when their contents change. Chokidar follows editor atomic-save
+ * replacements without polling by default. The set is replaced wholesale
+ * with {@link set}, so the watcher always mirrors exactly the files the caller
+ * currently depends on.
+ */
+export class DependencyWatcher {
+  readonly #options: DependencyWatcherOptions;
+  readonly #listeners = new Set<DependencyChangeListener>();
+  readonly #watcher: FSWatcher;
+  #dependencies: ReadonlySet<string> = new Set();
+  #fingerprints = new Map<string, string | undefined>();
+  #pending = new Set<string>();
+  #timer: NodeJS.Timeout | undefined;
+  #closed = false;
+
+  constructor(options: DependencyWatcherOptions = {}) {
+    this.#options = options;
+    this.#watcher = watch([], {
+      ...options.watch,
+      ignoreInitial: true,
+    });
+    this.#watcher.on("all", (_event, changed) => {
+      const absolute = path.resolve(this.#cwd(), changed);
+      if (this.#dependencies.has(absolute)) this.#queue(absolute);
+    });
+  }
+
+  get dependencies(): ReadonlySet<string> {
+    return this.#dependencies;
+  }
+
+  subscribe(listener: DependencyChangeListener): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  /** Replace the watched set with `dependencies` (absolute paths). */
+  set(dependencies: ReadonlySet<string>): void {
+    if (this.#closed) return;
+    const previous = this.#dependencies;
+    this.#dependencies = dependencies;
+    const removed = [...previous].filter(
+      (dependency) => !dependencies.has(dependency),
+    );
+    const added = [...dependencies].filter(
+      (dependency) => !previous.has(dependency),
+    );
+    if (removed.length > 0) {
+      for (const dependency of removed) {
+        this.#fingerprints.delete(dependency);
+        this.#pending.delete(dependency);
+      }
+      void this.#watcher.unwatch(removed);
+    }
+    if (added.length > 0) {
+      for (const dependency of added) {
+        this.#fingerprints.set(dependency, this.#fingerprint(dependency));
+      }
+      this.#watcher.add(added);
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#timer !== undefined) clearTimeout(this.#timer);
+    await this.#watcher.close();
+    this.#listeners.clear();
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close();
+  }
+
+  #cwd(): string {
+    return this.#options.watch?.cwd ?? process.cwd();
+  }
+
+  #queue(changed: string): void {
+    this.#pending.add(changed);
+    if (this.#timer !== undefined) clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined;
+      const pending = this.#pending;
+      this.#pending = new Set();
+      const paths = new Set<string>();
+      for (const dependency of pending) {
+        const previous = this.#fingerprints.get(dependency);
+        const current = this.#fingerprint(dependency);
+        if (current === previous) continue;
+        this.#fingerprints.set(dependency, current);
+        paths.add(dependency);
+      }
+      if (paths.size === 0) return;
+      for (const listener of this.#listeners) listener({ paths });
+    }, this.#options.debounceMs ?? 50);
+  }
+
+  #fingerprint(file: string): string | undefined {
+    try {
+      return createHash("sha256")
+        .update(readFileSync(file))
+        .digest("base64url");
+    } catch {
+      // Missing and unreadable are both materially different from the last
+      // successfully read contents, while repeated missing-file events fold
+      // onto the same value.
+      return undefined;
+    }
+  }
+}

package/src/import-loader.ts

@@ -0,0 +1,75 @@
+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);
+};

package/src/register-oxc.ts

@@ -0,0 +1,342 @@
+import { randomUUID } from "node:crypto";
+import {
+  registerHooks,
+  type LoadFnOutput,
+  type LoadHookContext,
+  type ResolveFnOutput,
+  type ResolveHookContext,
+} from "node:module";
+import { pathToFileURL } from "node:url";
+import type {
+  ImportLoader,
+  ImportLoaderRegistrationOptions,
+} from "./import-loader.ts";
+import {
+  filePathOfUrl,
+  isFileLikeSpecifier,
+  isProjectPath,
+  SpecifierResolver,
+  splitSpecifierMetadata,
+} from "./resolve-specifier.ts";
+import { SourceTransformer } from "./transform-source.ts";
+
+export type {
+  ImportLoader as RegisteredOxcImporter,
+  ImportLoaderRegistrationOptions as RegisterOxcOptions,
+  SourceTransform,
+  SourceTransformResult,
+  TransformContext,
+} from "./import-loader.ts";
+
+const protocol = "alchemy-import:";
+const namespaceParameter = "alchemy-import-namespace";
+const globalRegistrationKey = Symbol.for(
+  "@alchemy.run/node-utils/register-oxc",
+);
+
+interface ImportRequest {
+  readonly namespace?: string | undefined;
+  readonly parentURL: string;
+  readonly specifier: string;
+}
+
+type NextResolve = (
+  specifier: string,
+  context?: Partial<ResolveHookContext>,
+) => ResolveFnOutput;
+
+const namespaceOf = (url: string | undefined) => {
+  if (url === undefined || !url.startsWith("file:")) return undefined;
+  return new URL(url).searchParams.get(namespaceParameter) ?? undefined;
+};
+
+const withoutNamespace = (url: string) => {
+  if (!url.startsWith("file:")) return url;
+  const parsed = new URL(url);
+  parsed.searchParams.delete(namespaceParameter);
+  return parsed.href;
+};
+
+const withNamespace = (url: string, namespace: string) => {
+  const parsed = new URL(url);
+  parsed.searchParams.set(namespaceParameter, namespace);
+  return parsed.href;
+};
+
+const parseRequest = (specifier: string): ImportRequest | undefined => {
+  if (!specifier.startsWith(protocol)) return undefined;
+  return JSON.parse(decodeURIComponent(specifier.slice(protocol.length)));
+};
+
+/** Specifiers Node owns outright: builtins, data URLs, remote schemes. */
+const isForeignSpecifier = (specifier: string) =>
+  /^(?:node:|data:|[a-z][a-z\d+.-]*:\/\/)/i.test(specifier) &&
+  !specifier.startsWith("file:");
+
+const notFoundCodes = new Set([
+  "ERR_MODULE_NOT_FOUND",
+  "MODULE_NOT_FOUND",
+  "ERR_UNSUPPORTED_DIR_IMPORT",
+  "ERR_PACKAGE_PATH_NOT_EXPORTED",
+]);
+
+const isNotFound = (error: unknown): error is Error & { url?: string } =>
+  error instanceof Error &&
+  notFoundCodes.has((error as { code?: string }).code ?? "");
+
+/**
+ * The file Node could not find, from the error it raised. Node names the
+ * resolved target (`url` on ESM errors, the message on CommonJS ones) —
+ * for a package `exports` entry pointing at emitted JavaScript that was
+ * never built, that is the `.js` path whose `.ts` source we can substitute.
+ */
+const missingPathOf = (error: Error & { url?: string }) => {
+  if (error.url !== undefined) return filePathOfUrl(error.url);
+  const match = error.message.match(/^Cannot find module '([^']+)'/);
+  if (match === null) return undefined;
+  const [, target] = match;
+  if (target === undefined) return undefined;
+  if (target.startsWith("file:")) return filePathOfUrl(target);
+  return target.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(target)
+    ? target
+    : undefined;
+};
+
+/** A `require()` reaching the hooks: Node's CommonJS resolver wants paths, not URLs. */
+const isRequireContext = (context: ResolveHookContext) =>
+  context.conditions?.includes("require") === true &&
+  !context.conditions.includes("import");
+
+const resolveWithCandidate = (
+  candidate: string,
+  metadata: string,
+  context: ResolveHookContext,
+  nextResolve: NextResolve,
+): ResolveFnOutput | undefined => {
+  const specifier = isRequireContext(context)
+    ? candidate + metadata
+    : pathToFileURL(candidate).href + metadata;
+  try {
+    return nextResolve(specifier, context);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * tsx-compatible resolution. Node's resolver decides in the end; Oxc's
+ * resolver supplies the TypeScript-aware candidate (tsconfig `paths`,
+ * `.js` → `.ts` substitution, extensionless and directory imports) that
+ * Node would not find on its own.
+ */
+const resolveSpecifier = (
+  resolver: SpecifierResolver,
+  specifier: string,
+  context: ResolveHookContext,
+  nextResolve: NextResolve,
+): ResolveFnOutput => {
+  if (isForeignSpecifier(specifier)) return nextResolve(specifier, context);
+
+  const parentPath = filePathOfUrl(context.parentURL);
+  const { specifier: clean, metadata } = splitSpecifierMetadata(specifier);
+  const conditions = context.conditions ?? [];
+
+  // TypeScript's rules apply to project code. Dependencies keep Node's plain
+  // resolution so published packages behave exactly as they would without us.
+  if (parentPath !== undefined && isProjectPath(parentPath)) {
+    const candidate = resolver.resolve(parentPath, clean, conditions);
+    if (candidate !== undefined) {
+      const resolved = resolveWithCandidate(
+        candidate,
+        metadata,
+        context,
+        nextResolve,
+      );
+      if (resolved !== undefined) return resolved;
+    }
+  }
+
+  try {
+    return nextResolve(specifier, context);
+  } catch (error) {
+    if (!isNotFound(error)) throw error;
+    // A package `exports`/`main` target naming emitted JavaScript that only
+    // exists as TypeScript source (workspace packages in a checkout).
+    const missing = missingPathOf(error);
+    if (missing !== undefined && isFileLikeSpecifier(missing)) {
+      const candidate = resolver.resolveMissing(missing, conditions);
+      if (candidate !== undefined && candidate !== missing) {
+        const resolved = resolveWithCandidate(
+          candidate,
+          metadata,
+          context,
+          nextResolve,
+        );
+        if (resolved !== undefined) return resolved;
+      }
+    }
+    throw error;
+  }
+};
+
+/**
+ * `import data from "./x.json"` without an import attribute is how
+ * TypeScript projects import JSON (`resolveJsonModule`); Node insists on
+ * `with { type: "json" }` for ESM. Supply it, as tsx does.
+ */
+const withJsonAttribute = (url: string, context: LoadHookContext) => {
+  if (!/\.json(?:[?#]|$)/.test(url) || context.importAttributes?.type) {
+    return context;
+  }
+  return {
+    ...context,
+    importAttributes: { ...context.importAttributes, type: "json" },
+  };
+};
+
+/**
+ * Registers synchronous Node module hooks that transpile TypeScript with
+ * Rolldown's Oxc transformer and resolve it the way TypeScript (and tsx)
+ * does. A namespaced registration also provides a scoped import whose
+ * namespace propagates through the complete ESM graph.
+ */
+export const registerOxc = (
+  options: ImportLoaderRegistrationOptions = {},
+): ImportLoader => {
+  // One global (un-namespaced) registration per process. Alchemy starts every
+  // Node process with `--import` of a file that calls this, and in-process
+  // callers (the dev exec child, tests) may call it again; a second copy of
+  // the hooks would only re-run the resolve chain. The marker lives on
+  // globalThis because a checkout can load this module twice (src/ and lib/).
+  const globalRegistration = globalThis as typeof globalThis & {
+    [globalRegistrationKey]?: ImportLoader;
+  };
+  if (options.namespace === undefined) {
+    const existing = globalRegistration[globalRegistrationKey];
+    if (existing !== undefined) return existing;
+  }
+  const transformer = new SourceTransformer(options);
+  const resolver = new SpecifierResolver({
+    tsconfig: options.tsconfig ?? true,
+  });
+  const shouldInvalidate = options.shouldInvalidate ?? (() => true);
+
+  // Transformed sources carry inline source maps; Node only applies them to
+  // stack traces once source-map support is on.
+  const sourceMapsWereEnabled = process.sourceMapsEnabled;
+  process.setSourceMapsEnabled(true);
+
+  const hooks = registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const request = parseRequest(specifier);
+      const inheritedNamespace = namespaceOf(context.parentURL);
+      const namespace =
+        options.namespace === undefined
+          ? undefined
+          : (request?.namespace ?? inheritedNamespace);
+
+      if (options.namespace !== undefined && namespace !== options.namespace) {
+        return nextResolve(specifier, context);
+      }
+
+      const resolutionContext =
+        options.conditions === undefined || options.conditions.length === 0
+          ? context
+          : {
+              ...context,
+              conditions: [
+                ...new Set([...options.conditions, ...context.conditions]),
+              ],
+            };
+      const resolved = request
+        ? resolveSpecifier(
+            resolver,
+            request.specifier,
+            { ...resolutionContext, parentURL: request.parentURL },
+            nextResolve,
+          )
+        : resolveSpecifier(resolver, specifier, resolutionContext, nextResolve);
+      if (
+        namespace !== undefined &&
+        resolved.url.startsWith("file:") &&
+        shouldInvalidate(
+          withoutNamespace(resolved.url),
+          context.parentURL === undefined
+            ? undefined
+            : withoutNamespace(context.parentURL),
+        )
+      ) {
+        return { ...resolved, url: withNamespace(resolved.url, namespace) };
+      }
+      return resolved;
+    },
+    load(url, context, nextLoad): LoadFnOutput {
+      const namespace = namespaceOf(url);
+      if (options.namespace !== undefined && namespace !== options.namespace) {
+        return nextLoad(url, context);
+      }
+
+      const cleanUrl = withoutNamespace(url);
+      const filePath = filePathOfUrl(cleanUrl);
+      if (filePath === undefined) return nextLoad(cleanUrl, context);
+      options.onImport?.(cleanUrl);
+
+      if (options.filter !== undefined && !options.filter(filePath)) {
+        return nextLoad(cleanUrl, withJsonAttribute(cleanUrl, context));
+      }
+      const transformed = transformer.transform(
+        filePath,
+        cleanUrl,
+        context.format,
+      );
+      if (transformed === undefined) {
+        return nextLoad(cleanUrl, withJsonAttribute(cleanUrl, context));
+      }
+      return { ...transformed, shortCircuit: true };
+    },
+  });
+
+  const loader: ImportLoader = {
+    import<T>(specifier: string, parentURL: string) {
+      const request: ImportRequest = {
+        namespace: options.namespace,
+        parentURL: parentURL.startsWith("file:")
+          ? parentURL
+          : pathToFileURL(parentURL).href,
+        specifier,
+      };
+      return import(
+        `${protocol}${encodeURIComponent(JSON.stringify(request))}`
+      ) as Promise<T>;
+    },
+    unregister() {
+      hooks.deregister();
+      if (globalRegistration[globalRegistrationKey] === loader) {
+        delete globalRegistration[globalRegistrationKey];
+      }
+      if (sourceMapsWereEnabled === false) process.setSourceMapsEnabled(false);
+    },
+  };
+  if (options.namespace === undefined) {
+    globalRegistration[globalRegistrationKey] = loader;
+  }
+  return loader;
+};
+
+/**
+ * One-shot TypeScript import that leaves the rest of the runtime untouched:
+ * a private namespace is registered for the call, so nothing is shared with
+ * other imports of the same files. Mirrors tsx's `tsImport`.
+ */
+export const tsImport = async <T = unknown>(
+  specifier: string,
+  parentURL: string,
+  options: Omit<ImportLoaderRegistrationOptions, "namespace"> = {},
+): Promise<T> => {
+  const loader = registerOxc({ ...options, namespace: randomUUID() });
+  try {
+    return await loader.import<T>(specifier, parentURL);
+  } finally {
+    await loader.unregister();
+  }
+};