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

package/lib/watch-import-bun.d.ts

@@ -0,0 +1,30 @@
+import { 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;
+}
+/**
+ * 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 declare class BunImportTracker {
+    #private;
+    constructor(options: BunImportTrackerOptions);
+    get dependencies(): ReadonlySet<string>;
+    subscribe(listener: DependencyChangeListener): () => void;
+    /** Stops watching. The load hook stays registered but only echoes sources. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare const trackBunImports: (options: BunImportTrackerOptions) => BunImportTracker;
+//# sourceMappingURL=watch-import-bun.d.ts.map

package/lib/watch-import-bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-import-bun.d.ts","sourceRoot":"","sources":["../src/watch-import-bun.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAgBD;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;;IAI3B,YAAY,OAAO,EAAE,uBAAuB,EAgC3C;IAED,IAAI,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAEtC;IAED,SAAS,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAExD;IAED,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;CACF;AAED,eAAO,MAAM,eAAe,YAAa,uBAAuB,qBACjC,CAAC"}

package/lib/watch-import-bun.js

@@ -0,0 +1,73 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { DependencyWatcher, } from "./dependency-watcher.js";
+const loaders = {
+    ".js": "js",
+    ".mjs": "js",
+    ".cjs": "js",
+    ".jsx": "jsx",
+    ".ts": "ts",
+    ".mts": "ts",
+    ".cts": "ts",
+    ".tsx": "tsx",
+};
+const escapeRegExp = (value) => 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 {
+    #watcher;
+    #dependencies = new Set();
+    constructor(options) {
+        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 = `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(path.sep)})?${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() {
+        return this.#watcher.dependencies;
+    }
+    subscribe(listener) {
+        return this.#watcher.subscribe(listener);
+    }
+    /** Stops watching. The load hook stays registered but only echoes sources. */
+    close() {
+        return this.#watcher.close();
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}
+export const trackBunImports = (options) => new BunImportTracker(options);
+//# sourceMappingURL=watch-import-bun.js.map

package/lib/watch-import-bun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-import-bun.js","sourceRoot":"","sources":["../src/watch-import-bun.ts"],"names":[],"mappings":"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"}

package/lib/watch-import.d.ts

@@ -0,0 +1,27 @@
+import { type DependencyChangeListener, type DependencyWatcherOptions } from "./dependency-watcher.ts";
+import type { OxcLoaderOptions } from "./register-oxc.ts";
+export interface ImportGeneration<T> {
+    readonly value: T;
+    readonly namespace: string;
+    readonly dependencies: ReadonlySet<string>;
+}
+export interface ImportWatcherOptions extends OxcLoaderOptions, 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 declare class ImportWatcher<T = unknown> {
+    #private;
+    constructor(specifier: string, options: ImportWatcherOptions);
+    get dependencies(): ReadonlySet<string>;
+    subscribe(listener: DependencyChangeListener): () => void;
+    import(): Promise<ImportGeneration<T>>;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare const watchImport: <T = unknown>(specifier: string, options: ImportWatcherOptions) => ImportWatcher<T>;
+//# sourceMappingURL=watch-import.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watch-import.d.ts","sourceRoot":"","sources":["../src/watch-import.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAa,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErE,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,oBACf,SAAQ,gBAAgB,EAAE,wBAAwB;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,aAAa,CAAC,CAAC,GAAG,OAAO;;IAQpC,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAI3D;IAED,IAAI,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAEtC;IAED,SAAS,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAExD;IAEK,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAwC3C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3B;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;CACF;AAED,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,OAAO,aAC1B,MAAM,WACR,oBAAoB,qBACc,CAAC"}

package/lib/watch-import.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { DependencyWatcher, } from "./dependency-watcher.js";
+/**
+ * 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 {
+    #specifier;
+    #options;
+    #watcher;
+    #registration;
+    #dependencies = new Set();
+    #closed = false;
+    constructor(specifier, options) {
+        this.#specifier = specifier;
+        this.#options = options;
+        this.#watcher = new DependencyWatcher(options);
+    }
+    get dependencies() {
+        return this.#dependencies;
+    }
+    subscribe(listener) {
+        return this.#watcher.subscribe(listener);
+    }
+    async import() {
+        if (this.#closed)
+            throw new Error("ImportWatcher is closed");
+        const namespace = randomUUID();
+        const dependencies = new Set();
+        const { debounceMs: _, parentURL, watch: _watch, ...registerOptions } = this.#options;
+        // 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.js");
+        const registration = registerOxc({
+            ...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(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() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await this.#registration?.unregister();
+        await this.#watcher.close();
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}
+export const watchImport = (specifier, options) => new ImportWatcher(specifier, options);
+//# sourceMappingURL=watch-import.js.map

package/lib/watch-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-import.js","sourceRoot":"","sources":["../src/watch-import.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alchemy.run/node-utils",
-  "version": "2.0.0-beta.76",
-  "description": "Gitignore-compatible path matching for Alchemy packages.",
+  "version": "2.0.0-beta.78",
+  "description": "Runtime utilities for Alchemy packages.",
   "homepage": "https://alchemy.run",
   "author": "Sam Goodwin <sam@alchemy.run>",
   "keywords": [
@@ -33,8 +33,27 @@
       "types": "./lib/ignore.d.ts",
       "bun": "./src/ignore.ts",
       "import": "./lib/ignore.js"
+    },
+    "./register-oxc": {
+      "types": "./lib/register-oxc.d.ts",
+      "bun": "./src/register-oxc.ts",
+      "import": "./lib/register-oxc.js"
+    },
+    "./watch-import": {
+      "types": "./lib/watch-import.d.ts",
+      "bun": "./src/watch-import.ts",
+      "import": "./lib/watch-import.js"
+    },
+    "./watch-import-bun": {
+      "types": "./lib/watch-import-bun.d.ts",
+      "bun": "./src/watch-import-bun.ts",
+      "import": "./lib/watch-import-bun.js"
     }
   },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "rolldown": "1.2.5"
+  },
   "publishConfig": {
     "access": "public"
   },

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;
+    }
+  }
+}