@nielspeter/eess 0.4.0 → 0.5.0

package/dist/watch.js

@@ -0,0 +1,129 @@
+import { watch } from 'node:fs/promises';
+import path from 'node:path';
+import { isArchRuleError } from './errors.js';
+import { isNullaryCallable } from './type-guards.js';
+const DEFAULT_DEBOUNCE_MS = 250;
+/** `fs.watch` reports this when a watcher is closed; it is not a fault. */
+const ABORTED = 'The operation was aborted';
+/**
+ * Scheduling logic for watch mode — separate from the loop so it is testable
+ * without a filesystem.
+ *
+ * Debounces rapid triggers. A trigger arriving mid-run is remembered and
+ * replayed once the run finishes, so a save during a run is never dropped and
+ * never starts a second concurrent run.
+ */
+export class RunScheduler {
+    debounceTimer;
+    running = false;
+    _pendingRerun = false;
+    debounceMs;
+    onRun;
+    #runCount = 0;
+    constructor(onRun, debounceMs = DEFAULT_DEBOUNCE_MS) {
+        this.onRun = onRun;
+        this.debounceMs = debounceMs;
+    }
+    /**
+     * Completed runs.
+     *
+     * Hard-private with a getter: the counter is this class's own bookkeeping, and
+     * a caller that could reassign it would make the number mean nothing.
+     */
+    get runCount() {
+        return this.#runCount;
+    }
+    get pendingRerun() {
+        return this._pendingRerun;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /** Debounce a change on `trigger`, coalescing bursts into a single re-run. */
+    schedule(trigger) {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            if (this.running) {
+                this._pendingRerun = true;
+                return;
+            }
+            this.executeRun(trigger);
+        }, this.debounceMs);
+    }
+    executeRun(trigger) {
+        this.running = true;
+        this._pendingRerun = false;
+        this.#runCount++;
+        process.stdout.write('\x1B[2J\x1B[H'); // clear screen, preserve scrollback
+        process.stdout.write(`Change detected: ${trigger}\n\n`);
+        this.onRun(trigger)
+            .catch((err) => {
+            // A rule failure is the expected outcome of a watch run — swallow it and
+            // let the reporter's own output stand. Anything else is a real fault.
+            if (!isArchRuleError(err) && err instanceof Error) {
+                console.error(err.message);
+            }
+        })
+            .finally(() => {
+            this.running = false;
+            if (this._pendingRerun) {
+                this.executeRun('(queued change)');
+            }
+            else {
+                process.stdout.write('\nWatching for changes...\n');
+            }
+        });
+    }
+}
+/** Consume one watcher, scheduling on each qualifying event. */
+function consume(watcher, label, onEvent) {
+    void (async () => {
+        try {
+            for await (const event of watcher)
+                onEvent(event);
+        }
+        catch (err) {
+            if (err instanceof Error && err.message !== ABORTED) {
+                console.error(`Watcher error on ${label}: ${err.message}`);
+            }
+        }
+    })();
+}
+/**
+ * Watch for file changes and re-run the callback.
+ *
+ * Uses `fs.watch` with `recursive: true` (Node 24+). Debounces rapid events; a
+ * change during a run is queued and executed after it completes.
+ */
+export function watchAndRerun(options) {
+    const { watchDirs, watchFiles, watchedFileRe, onChangeDetected, debounceMs = DEFAULT_DEBOUNCE_MS, } = options;
+    const scheduler = new RunScheduler(onChangeDetected, debounceMs);
+    const watchers = [];
+    for (const dir of watchDirs) {
+        const watcher = watch(path.resolve(dir), { recursive: true });
+        watchers.push(watcher);
+        consume(watcher, dir, (event) => {
+            if (event.filename && watchedFileRe.test(event.filename)) {
+                scheduler.schedule(event.filename);
+            }
+        });
+    }
+    for (const file of watchFiles) {
+        const watcher = watch(path.resolve(file));
+        watchers.push(watcher);
+        consume(watcher, file, () => {
+            scheduler.schedule(path.basename(file));
+        });
+    }
+    // Graceful shutdown — close all watchers on SIGINT.
+    process.on('SIGINT', () => {
+        for (const w of watchers) {
+            if ('return' in w && isNullaryCallable(w.return)) {
+                void w.return();
+            }
+        }
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch.js.map

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

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@nielspeter/eess",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "eess kernel — the dialect-independent rule engine (RuleBuilder, Predicate, Condition, baseline, formatters). Specifications you can run.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     }
   },
   "files": [
@@ -26,6 +30,7 @@
   "license": "MIT",
   "scripts": {
     "prepublishOnly": "npm run build",
+    "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",