BREAKING CHANGE(smartwatch): Introduce Smartwatch: cross-runtime native file watching for Node.js, Deno and Bun; rename smartchok to smartwatch and bump major version to 2.0.0

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartchok',
-  version: '1.2.0',
-  description: 'A smart wrapper for chokidar 5.x with glob pattern support and enhanced features.'
+  version: '3.0.0',
+  description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.'
 }

ts/index.ts

@@ -1 +1 @@
-export * from './smartchok.classes.smartchok.js';
+export * from './smartwatch.classes.smartwatch.js';

ts/smartwatch.classes.smartwatch.ts

@@ -1,7 +1,8 @@
-import * as plugins from './smartchok.plugins.js';
+import * as plugins from './smartwatch.plugins.js';
 import { Stringmap } from '@push.rocks/lik';
+import { createWatcher, type IWatcher, type IWatchEvent, type TWatchEventType } from './watchers/index.js';
 
-export type TSmartchokStatus = 'idle' | 'starting' | 'watching';
+export type TSmartwatchStatus = 'idle' | 'starting' | 'watching';
 export type TFsEvent =
   | 'add'
   | 'addDir'
@@ -13,22 +14,31 @@ export type TFsEvent =
   | 'raw';
 
 /**
- * Smartchok allows easy wathcing of files
+ * Smartwatch allows easy watching of files
+ * Uses native file watching APIs (Node.js fs.watch, Deno.watchFs) for cross-runtime support
  */
-export class Smartchok {
+export class Smartwatch {
   public watchStringmap = new Stringmap();
-  public status: TSmartchokStatus = 'idle';
-  private watcher: plugins.chokidar.FSWatcher;
+  public status: TSmartwatchStatus = 'idle';
+  private watcher: IWatcher | null = null;
   private globPatterns: string[] = [];
   private globMatchers: Map<string, (path: string) => boolean> = new Map();
-  private watchingDeferred = plugins.smartpromise.defer<void>(); // used to run things when watcher is initialized
-  private eventObservablemap = new plugins.smartrx.Observablemap(); // register one observable per event
+  private watchingDeferred = plugins.smartpromise.defer<void>();
+
+  // Event subjects for each event type
+  private eventSubjects: Map<TFsEvent, plugins.smartrx.rxjs.Subject<[string, plugins.fs.Stats | undefined]>> = new Map();
 
   /**
-   * constructor of class smartchok
+   * constructor of class Smartwatch
    */
   constructor(watchArrayArg: string[]) {
     this.watchStringmap.addStringArray(watchArrayArg);
+
+    // Initialize subjects for each event type
+    const eventTypes: TFsEvent[] = ['add', 'addDir', 'change', 'error', 'unlink', 'unlinkDir', 'ready', 'raw'];
+    for (const eventType of eventTypes) {
+      this.eventSubjects.set(eventType, new plugins.smartrx.rxjs.Subject());
+    }
   }
 
   private getGlobBase(globPattern: string) {
@@ -80,11 +90,12 @@ export class Smartchok {
   ): Promise<plugins.smartrx.rxjs.Observable<[string, plugins.fs.Stats]>> {
     const done = plugins.smartpromise.defer<plugins.smartrx.rxjs.Observable<any>>();
     this.watchingDeferred.promise.then(() => {
-      const eventObservable = this.eventObservablemap.getSubjectForEmitterEvent(
-        this.watcher,
-        fsEvent
-      );
-      done.resolve(eventObservable);
+      const subject = this.eventSubjects.get(fsEvent);
+      if (subject) {
+        done.resolve(subject.asObservable());
+      } else {
+        done.reject(new Error(`Unknown event type: ${fsEvent}`));
+      }
     });
     return done.promise;
   }
@@ -93,18 +104,17 @@ export class Smartchok {
    * starts the watcher
    * @returns Promise<void>
    */
-  public start(): Promise<void> {
-    const done = plugins.smartpromise.defer<void>();
+  public async start(): Promise<void> {
     this.status = 'starting';
-    
+
     // Store original glob patterns and create matchers
     this.globPatterns = this.watchStringmap.getStringArray();
     const basePaths = new Set<string>();
-    
+
     this.globPatterns.forEach((pattern) => {
       const basePath = this.getGlobBase(pattern);
       basePaths.add(basePath);
-      
+
       // Create a picomatch matcher for each glob pattern
       const matcher = plugins.picomatch(pattern, {
         dot: true,
@@ -112,62 +122,63 @@ export class Smartchok {
       });
       this.globMatchers.set(pattern, matcher);
     });
-    
-    // Convert Set to Array for chokidar
+
+    // Convert Set to Array for the watcher
     const watchPaths = Array.from(basePaths);
     console.log('Base paths to watch:', watchPaths);
-    
-    this.watcher = plugins.chokidar.watch(watchPaths, {
-      persistent: true,
-      ignoreInitial: false,
-      followSymlinks: false,
+
+    // Create the platform-appropriate watcher
+    this.watcher = await createWatcher({
+      basePaths: watchPaths,
       depth: 4,
-      awaitWriteFinish: {
-        stabilityThreshold: 300,
-        pollInterval: 100
-      },
-      ignored: (path: string, stats?: plugins.fs.Stats) => {
-        // Don't filter during initialization - let chokidar watch everything
-        // We'll filter events as they come in
-        return false;
+      followSymlinks: false,
+      stabilityThreshold: 300,
+      pollInterval: 100
+    });
+
+    // Subscribe to watcher events and dispatch to appropriate subjects
+    this.watcher.events$.subscribe((event: IWatchEvent) => {
+      this.handleWatchEvent(event);
+    });
+
+    // Start the watcher
+    await this.watcher.start();
+
+    this.status = 'watching';
+    this.watchingDeferred.resolve();
+  }
+
+  /**
+   * Handle events from the native watcher
+   */
+  private handleWatchEvent(event: IWatchEvent): void {
+    // Handle ready event
+    if (event.type === 'ready') {
+      const subject = this.eventSubjects.get('ready');
+      if (subject) {
+        subject.next(['', undefined]);
       }
-    });
-    
-    // Set up event handlers with glob filtering
-    const fileEvents: Array<'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir'> = 
-      ['add', 'addDir', 'change', 'unlink', 'unlinkDir'];
-    
-    // Handle file events
-    fileEvents.forEach(eventName => {
-      this.watcher.on(eventName, (path: string, stats?: plugins.fs.Stats) => {
-        // Only emit event if the path matches our glob patterns
-        if (this.shouldWatchPath(path)) {
-          this.eventObservablemap.getSubjectForEmitterEvent(this.watcher, eventName)
-            .next([path, stats]);
-        }
-      });
-    });
-    
-    // Handle error events
-    this.watcher.on('error', (error: Error) => {
-      this.eventObservablemap.getSubjectForEmitterEvent(this.watcher, 'error')
-        .next([error, undefined]);
-    });
-    
-    // Handle raw events
-    this.watcher.on('raw', (eventType: string, path: string, details: any) => {
-      if (this.shouldWatchPath(path)) {
-        this.eventObservablemap.getSubjectForEmitterEvent(this.watcher, 'raw')
-          .next([path, undefined]);
+      return;
+    }
+
+    // Handle error event
+    if (event.type === 'error') {
+      const subject = this.eventSubjects.get('error');
+      if (subject) {
+        subject.next([event.error?.message || 'Unknown error', undefined]);
       }
-    });
-    
-    this.watcher.on('ready', () => {
-      this.status = 'watching';
-      this.watchingDeferred.resolve();
-      done.resolve();
-    });
-    return done.promise;
+      return;
+    }
+
+    // Filter file/directory events by glob patterns
+    if (!this.shouldWatchPath(event.path)) {
+      return;
+    }
+
+    const subject = this.eventSubjects.get(event.type as TFsEvent);
+    if (subject) {
+      subject.next([event.path, event.stats]);
+    }
   }
 
   /**
@@ -175,8 +186,12 @@ export class Smartchok {
    */
   public async stop() {
     const closeWatcher = async () => {
-      await this.watcher.close();
+      if (this.watcher) {
+        await this.watcher.stop();
+        this.watcher = null;
+      }
     };
+
     if (this.status === 'watching') {
       console.log('closing while watching');
       await closeWatcher();
@@ -184,8 +199,10 @@ export class Smartchok {
       await this.watchingDeferred.promise;
       await closeWatcher();
     }
+
+    this.status = 'idle';
   }
-  
+
   /**
    * Checks if a path should be watched based on glob patterns
    */
@@ -195,7 +212,7 @@ export class Smartchok {
     if (normalizedPath.startsWith('./')) {
       normalizedPath = normalizedPath.substring(2);
     }
-    
+
     // Check if the path matches any of our glob patterns
     for (const [pattern, matcher] of this.globMatchers) {
       // Also normalize the pattern for comparison
@@ -203,12 +220,12 @@ export class Smartchok {
       if (normalizedPattern.startsWith('./')) {
         normalizedPattern = normalizedPattern.substring(2);
       }
-      
+
       // Try matching with both the original pattern and normalized
       if (matcher(normalizedPath) || matcher(filePath)) {
         return true;
       }
-      
+
       // Also try matching without the leading path
       const withoutLeading = 'test/' + normalizedPath.split('test/').slice(1).join('test/');
       if (matcher(withoutLeading)) {

ts/smartwatch.plugins.ts

@@ -11,18 +11,18 @@ export {
 import * as lik from '@push.rocks/lik';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrx from '@push.rocks/smartrx';
+import { Smartenv } from '@push.rocks/smartenv';
 
 export {
   lik,
   smartpromise,
-  smartrx
+  smartrx,
+  Smartenv
 }
 
 // thirdparty scope
-import * as chokidar from 'chokidar';
 import picomatch from 'picomatch';
 
 export {
-  chokidar,
   picomatch,
 }

ts/utils/write-stabilizer.ts

@@ -0,0 +1,97 @@
+import * as fs from 'fs';
+
+interface IPendingWrite {
+  lastSize: number;
+  lastChange: number;
+  timeoutId: ReturnType<typeof setTimeout>;
+  resolve: (stats: fs.Stats) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Implements awaitWriteFinish functionality by polling file size until stable.
+ * This replaces chokidar's built-in write stabilization.
+ */
+export class WriteStabilizer {
+  private pendingWrites = new Map<string, IPendingWrite>();
+
+  constructor(
+    private stabilityThreshold: number = 300,
+    private pollInterval: number = 100
+  ) {}
+
+  /**
+   * Wait for a file write to complete by polling until size is stable
+   */
+  async waitForWriteFinish(filePath: string): Promise<fs.Stats> {
+    // Cancel any existing pending check for this file
+    this.cancel(filePath);
+
+    return new Promise((resolve, reject) => {
+      const poll = async () => {
+        try {
+          const stats = await fs.promises.stat(filePath);
+          const pending = this.pendingWrites.get(filePath);
+
+          if (!pending) {
+            // Was cancelled
+            return;
+          }
+
+          const now = Date.now();
+
+          if (stats.size !== pending.lastSize) {
+            // Size changed - file is still being written, reset timer
+            pending.lastSize = stats.size;
+            pending.lastChange = now;
+            pending.timeoutId = setTimeout(poll, this.pollInterval);
+          } else if (now - pending.lastChange >= this.stabilityThreshold) {
+            // Size has been stable for the threshold duration
+            this.pendingWrites.delete(filePath);
+            resolve(stats);
+          } else {
+            // Size is the same but not yet past threshold
+            pending.timeoutId = setTimeout(poll, this.pollInterval);
+          }
+        } catch (error: any) {
+          this.pendingWrites.delete(filePath);
+          if (error.code === 'ENOENT') {
+            // File was deleted during polling
+            reject(new Error(`File was deleted: ${filePath}`));
+          } else {
+            reject(error);
+          }
+        }
+      };
+
+      this.pendingWrites.set(filePath, {
+        lastSize: -1,
+        lastChange: Date.now(),
+        timeoutId: setTimeout(poll, this.pollInterval),
+        resolve,
+        reject
+      });
+    });
+  }
+
+  /**
+   * Cancel any pending write stabilization for a file
+   */
+  cancel(filePath: string): void {
+    const pending = this.pendingWrites.get(filePath);
+    if (pending) {
+      clearTimeout(pending.timeoutId);
+      this.pendingWrites.delete(filePath);
+    }
+  }
+
+  /**
+   * Cancel all pending write stabilizations
+   */
+  cancelAll(): void {
+    for (const [filePath, pending] of this.pendingWrites) {
+      clearTimeout(pending.timeoutId);
+    }
+    this.pendingWrites.clear();
+  }
+}

ts/watchers/index.ts

@@ -0,0 +1,33 @@
+import { Smartenv } from '@push.rocks/smartenv';
+import type { IWatcher, IWatcherOptions, IWatchEvent, TWatchEventType } from './interfaces.js';
+
+export type { IWatcher, IWatcherOptions, IWatchEvent, TWatchEventType };
+
+/**
+ * Creates a platform-appropriate file watcher based on the current runtime
+ * Uses @push.rocks/smartenv for runtime detection
+ */
+export async function createWatcher(options: IWatcherOptions): Promise<IWatcher> {
+  const env = new Smartenv();
+
+  if (env.isDeno) {
+    // Deno runtime - use Deno.watchFs
+    const { DenoWatcher } = await import('./watcher.deno.js');
+    return new DenoWatcher(options);
+  } else {
+    // Node.js or Bun - both use fs.watch (Bun has Node.js compatibility)
+    const { NodeWatcher } = await import('./watcher.node.js');
+    return new NodeWatcher(options);
+  }
+}
+
+/**
+ * Default watcher options
+ */
+export const defaultWatcherOptions: IWatcherOptions = {
+  basePaths: [],
+  depth: 4,
+  followSymlinks: false,
+  stabilityThreshold: 300,
+  pollInterval: 100
+};

ts/watchers/interfaces.ts

@@ -0,0 +1,47 @@
+import type * as fs from 'fs';
+import type * as smartrx from '@push.rocks/smartrx';
+
+/**
+ * File system event types that the watcher emits
+ */
+export type TWatchEventType = 'add' | 'addDir' | 'change' | 'unlink' | 'unlinkDir' | 'ready' | 'error';
+
+/**
+ * Data structure for watch events
+ */
+export interface IWatchEvent {
+  type: TWatchEventType;
+  path: string;
+  stats?: fs.Stats;
+  error?: Error;
+}
+
+/**
+ * Options for creating a watcher
+ */
+export interface IWatcherOptions {
+  /** Base paths to watch (extracted from glob patterns) */
+  basePaths: string[];
+  /** Maximum directory depth to watch */
+  depth: number;
+  /** Whether to follow symbolic links */
+  followSymlinks: boolean;
+  /** Stability threshold for write detection (ms) */
+  stabilityThreshold: number;
+  /** Poll interval for write detection (ms) */
+  pollInterval: number;
+}
+
+/**
+ * Common interface for file watchers across runtimes
+ */
+export interface IWatcher {
+  /** Start watching files */
+  start(): Promise<void>;
+  /** Stop watching and clean up */
+  stop(): Promise<void>;
+  /** Whether the watcher is currently active */
+  readonly isWatching: boolean;
+  /** Subject that emits watch events */
+  readonly events$: smartrx.rxjs.Subject<IWatchEvent>;
+}

ts/watchers/watcher.deno.ts

@@ -0,0 +1,329 @@
+import * as smartrx from '@push.rocks/smartrx';
+import type { IWatcher, IWatcherOptions, IWatchEvent, TWatchEventType } from './interfaces.js';
+
+// Type definitions for Deno APIs (these exist at runtime in Deno)
+declare const Deno: {
+  watchFs(paths: string | string[], options?: { recursive?: boolean }): AsyncIterable<{
+    kind: 'create' | 'modify' | 'remove' | 'access' | 'any' | 'other';
+    paths: string[];
+    flag?: { rescan: boolean };
+  }> & { close(): void };
+  stat(path: string): Promise<{
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+    size: number;
+    mtime: Date | null;
+    atime: Date | null;
+    birthtime: Date | null;
+    mode: number | null;
+    uid: number | null;
+    gid: number | null;
+  }>;
+  lstat(path: string): Promise<{
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+    size: number;
+    mtime: Date | null;
+    atime: Date | null;
+    birthtime: Date | null;
+    mode: number | null;
+    uid: number | null;
+    gid: number | null;
+  }>;
+  readDir(path: string): AsyncIterable<{
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+  }>;
+};
+
+/**
+ * Convert Deno stat to Node.js-like Stats object
+ */
+function denoStatToNodeStats(denoStat: Awaited<ReturnType<typeof Deno.stat>>): any {
+  return {
+    isFile: () => denoStat.isFile,
+    isDirectory: () => denoStat.isDirectory,
+    isSymbolicLink: () => denoStat.isSymlink,
+    size: denoStat.size,
+    mtime: denoStat.mtime,
+    atime: denoStat.atime,
+    birthtime: denoStat.birthtime,
+    mode: denoStat.mode,
+    uid: denoStat.uid,
+    gid: denoStat.gid
+  };
+}
+
+/**
+ * Deno file watcher using native Deno.watchFs API
+ */
+export class DenoWatcher implements IWatcher {
+  private watcher: ReturnType<typeof Deno.watchFs> | null = null;
+  private watchedFiles: Set<string> = new Set();
+  private _isWatching = false;
+  private abortController: AbortController | null = null;
+  private recentEvents: Map<string, number> = new Map();
+  private throttleMs = 50;
+  private pendingWrites: Map<string, ReturnType<typeof setTimeout>> = new Map();
+
+  public readonly events$ = new smartrx.rxjs.Subject<IWatchEvent>();
+
+  constructor(private options: IWatcherOptions) {}
+
+  get isWatching(): boolean {
+    return this._isWatching;
+  }
+
+  async start(): Promise<void> {
+    if (this._isWatching) {
+      return;
+    }
+
+    try {
+      this.abortController = new AbortController();
+
+      // Start watching all base paths
+      this.watcher = Deno.watchFs(this.options.basePaths, { recursive: true });
+      this._isWatching = true;
+
+      // Perform initial scan
+      for (const basePath of this.options.basePaths) {
+        await this.scanDirectory(basePath, 0);
+      }
+
+      // Emit ready event
+      this.events$.next({ type: 'ready', path: '' });
+
+      // Start processing events
+      this.processEvents();
+    } catch (error: any) {
+      this.events$.next({ type: 'error', path: '', error });
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    this._isWatching = false;
+
+    // Cancel all pending write stabilizations
+    for (const timeout of this.pendingWrites.values()) {
+      clearTimeout(timeout);
+    }
+    this.pendingWrites.clear();
+
+    // Close the watcher
+    if (this.watcher) {
+      (this.watcher as any).close();
+      this.watcher = null;
+    }
+
+    this.watchedFiles.clear();
+    this.recentEvents.clear();
+  }
+
+  /**
+   * Process events from the Deno watcher
+   */
+  private async processEvents(): Promise<void> {
+    if (!this.watcher) {
+      return;
+    }
+
+    try {
+      for await (const event of this.watcher) {
+        if (!this._isWatching) {
+          break;
+        }
+
+        for (const filePath of event.paths) {
+          await this.handleDenoEvent(event.kind, filePath);
+        }
+      }
+    } catch (error: any) {
+      if (this._isWatching) {
+        this.events$.next({ type: 'error', path: '', error });
+      }
+    }
+  }
+
+  /**
+   * Handle a Deno file system event
+   */
+  private async handleDenoEvent(
+    kind: 'create' | 'modify' | 'remove' | 'access' | 'any' | 'other',
+    filePath: string
+  ): Promise<void> {
+    // Ignore 'access' events (just reading the file)
+    if (kind === 'access') {
+      return;
+    }
+
+    // Throttle duplicate events
+    if (!this.shouldEmit(filePath, kind)) {
+      return;
+    }
+
+    try {
+      if (kind === 'create') {
+        const stats = await this.statSafe(filePath);
+        if (stats) {
+          // Wait for write to stabilize
+          await this.waitForWriteFinish(filePath);
+          const finalStats = await this.statSafe(filePath);
+
+          if (finalStats) {
+            this.watchedFiles.add(filePath);
+            const eventType: TWatchEventType = finalStats.isDirectory() ? 'addDir' : 'add';
+            this.events$.next({ type: eventType, path: filePath, stats: finalStats });
+          }
+        }
+      } else if (kind === 'modify') {
+        const stats = await this.statSafe(filePath);
+        if (stats && !stats.isDirectory()) {
+          // Wait for write to stabilize
+          await this.waitForWriteFinish(filePath);
+          const finalStats = await this.statSafe(filePath);
+
+          if (finalStats) {
+            this.events$.next({ type: 'change', path: filePath, stats: finalStats });
+          }
+        }
+      } else if (kind === 'remove') {
+        const wasDirectory = this.isKnownDirectory(filePath);
+        this.watchedFiles.delete(filePath);
+        this.events$.next({
+          type: wasDirectory ? 'unlinkDir' : 'unlink',
+          path: filePath
+        });
+      }
+    } catch (error: any) {
+      this.events$.next({ type: 'error', path: filePath, error });
+    }
+  }
+
+  /**
+   * Wait for file write to complete (polling-based)
+   */
+  private async waitForWriteFinish(filePath: string): Promise<void> {
+    return new Promise((resolve) => {
+      let lastSize = -1;
+      let lastChange = Date.now();
+
+      const poll = async () => {
+        try {
+          const stats = await this.statSafe(filePath);
+          if (!stats) {
+            resolve();
+            return;
+          }
+
+          const now = Date.now();
+          if (stats.size !== lastSize) {
+            lastSize = stats.size;
+            lastChange = now;
+            this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
+          } else if (now - lastChange >= this.options.stabilityThreshold) {
+            this.pendingWrites.delete(filePath);
+            resolve();
+          } else {
+            this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
+          }
+        } catch {
+          this.pendingWrites.delete(filePath);
+          resolve();
+        }
+      };
+
+      this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
+    });
+  }
+
+  /**
+   * Scan directory and emit 'add' events for existing files
+   */
+  private async scanDirectory(dirPath: string, depth: number): Promise<void> {
+    if (depth > this.options.depth) {
+      return;
+    }
+
+    try {
+      for await (const entry of Deno.readDir(dirPath)) {
+        const fullPath = `${dirPath}/${entry.name}`;
+        const stats = await this.statSafe(fullPath);
+
+        if (!stats) {
+          continue;
+        }
+
+        if (entry.isDirectory) {
+          this.watchedFiles.add(fullPath);
+          this.events$.next({ type: 'addDir', path: fullPath, stats });
+          await this.scanDirectory(fullPath, depth + 1);
+        } else if (entry.isFile) {
+          this.watchedFiles.add(fullPath);
+          this.events$.next({ type: 'add', path: fullPath, stats });
+        }
+      }
+    } catch (error: any) {
+      if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
+        this.events$.next({ type: 'error', path: dirPath, error });
+      }
+    }
+  }
+
+  /**
+   * Safely stat a path, returning null if it doesn't exist
+   */
+  private async statSafe(filePath: string): Promise<any | null> {
+    try {
+      const statFn = this.options.followSymlinks ? Deno.stat : Deno.lstat;
+      const denoStats = await statFn(filePath);
+      return denoStatToNodeStats(denoStats);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if a path was known to be a directory
+   */
+  private isKnownDirectory(filePath: string): boolean {
+    for (const watched of this.watchedFiles) {
+      if (watched.startsWith(filePath + '/')) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Throttle duplicate events
+   */
+  private shouldEmit(filePath: string, eventType: string): boolean {
+    const key = `${filePath}:${eventType}`;
+    const now = Date.now();
+    const lastEmit = this.recentEvents.get(key);
+
+    if (lastEmit && now - lastEmit < this.throttleMs) {
+      return false;
+    }
+
+    this.recentEvents.set(key, now);
+
+    // Clean up old entries periodically
+    if (this.recentEvents.size > 1000) {
+      const cutoff = now - this.throttleMs * 2;
+      for (const [k, time] of this.recentEvents) {
+        if (time < cutoff) {
+          this.recentEvents.delete(k);
+        }
+      }
+    }
+
+    return true;
+  }
+}

ts/watchers/watcher.node.ts

@@ -0,0 +1,281 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as smartrx from '@push.rocks/smartrx';
+import type { IWatcher, IWatcherOptions, IWatchEvent, TWatchEventType } from './interfaces.js';
+import { WriteStabilizer } from '../utils/write-stabilizer.js';
+
+/**
+ * Node.js/Bun file watcher using native fs.watch API
+ */
+export class NodeWatcher implements IWatcher {
+  private watchers: Map<string, fs.FSWatcher> = new Map();
+  private watchedFiles: Set<string> = new Set();
+  private _isWatching = false;
+  private writeStabilizer: WriteStabilizer;
+  private recentEvents: Map<string, number> = new Map();
+  private throttleMs = 50;
+
+  public readonly events$ = new smartrx.rxjs.Subject<IWatchEvent>();
+
+  constructor(private options: IWatcherOptions) {
+    this.writeStabilizer = new WriteStabilizer(
+      options.stabilityThreshold,
+      options.pollInterval
+    );
+  }
+
+  get isWatching(): boolean {
+    return this._isWatching;
+  }
+
+  async start(): Promise<void> {
+    if (this._isWatching) {
+      return;
+    }
+
+    try {
+      // Start watching each base path
+      for (const basePath of this.options.basePaths) {
+        await this.watchPath(basePath, 0);
+      }
+
+      this._isWatching = true;
+
+      // Perform initial scan to emit 'add' events for existing files
+      for (const basePath of this.options.basePaths) {
+        await this.scanDirectory(basePath, 0);
+      }
+
+      // Emit ready event
+      this.events$.next({ type: 'ready', path: '' });
+    } catch (error: any) {
+      this.events$.next({ type: 'error', path: '', error });
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    this._isWatching = false;
+    this.writeStabilizer.cancelAll();
+
+    // Close all watchers
+    for (const [watchPath, watcher] of this.watchers) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.watchedFiles.clear();
+    this.recentEvents.clear();
+  }
+
+  /**
+   * Start watching a path (file or directory)
+   */
+  private async watchPath(watchPath: string, depth: number): Promise<void> {
+    if (depth > this.options.depth) {
+      return;
+    }
+
+    try {
+      const stats = await this.statSafe(watchPath);
+      if (!stats) {
+        return;
+      }
+
+      if (stats.isDirectory()) {
+        // Watch the directory with recursive option (Node.js 20+ supports this on all platforms)
+        const watcher = fs.watch(
+          watchPath,
+          { recursive: true, persistent: true },
+          (eventType, filename) => {
+            if (filename) {
+              this.handleFsEvent(watchPath, filename, eventType);
+            }
+          }
+        );
+
+        watcher.on('error', (error) => {
+          this.events$.next({ type: 'error', path: watchPath, error });
+        });
+
+        this.watchers.set(watchPath, watcher);
+      }
+    } catch (error: any) {
+      this.events$.next({ type: 'error', path: watchPath, error });
+    }
+  }
+
+  /**
+   * Handle raw fs.watch events and normalize them
+   */
+  private async handleFsEvent(
+    basePath: string,
+    filename: string,
+    eventType: 'rename' | 'change' | string
+  ): Promise<void> {
+    const fullPath = path.join(basePath, filename);
+
+    // Throttle duplicate events
+    if (!this.shouldEmit(fullPath, eventType)) {
+      return;
+    }
+
+    try {
+      const stats = await this.statSafe(fullPath);
+
+      if (eventType === 'rename') {
+        // 'rename' can mean add or unlink - check if file exists
+        if (stats) {
+          // File exists - it's either a new file or was renamed to this location
+          if (stats.isDirectory()) {
+            if (!this.watchedFiles.has(fullPath)) {
+              this.watchedFiles.add(fullPath);
+              this.events$.next({ type: 'addDir', path: fullPath, stats });
+            }
+          } else {
+            // Wait for write to stabilize before emitting
+            try {
+              const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);
+              const wasWatched = this.watchedFiles.has(fullPath);
+              this.watchedFiles.add(fullPath);
+              this.events$.next({
+                type: wasWatched ? 'change' : 'add',
+                path: fullPath,
+                stats: stableStats
+              });
+            } catch {
+              // File was deleted during stabilization
+              if (this.watchedFiles.has(fullPath)) {
+                this.watchedFiles.delete(fullPath);
+                this.events$.next({ type: 'unlink', path: fullPath });
+              }
+            }
+          }
+        } else {
+          // File doesn't exist - it was deleted
+          if (this.watchedFiles.has(fullPath)) {
+            const wasDir = this.isKnownDirectory(fullPath);
+            this.watchedFiles.delete(fullPath);
+            this.events$.next({
+              type: wasDir ? 'unlinkDir' : 'unlink',
+              path: fullPath
+            });
+          }
+        }
+      } else if (eventType === 'change') {
+        // File was modified
+        if (stats && !stats.isDirectory()) {
+          try {
+            const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);
+            // Check if this is a new file (not yet in watchedFiles)
+            const wasWatched = this.watchedFiles.has(fullPath);
+            if (!wasWatched) {
+              // This is actually an 'add' - file wasn't being watched before
+              this.watchedFiles.add(fullPath);
+              this.events$.next({ type: 'add', path: fullPath, stats: stableStats });
+            } else {
+              this.events$.next({ type: 'change', path: fullPath, stats: stableStats });
+            }
+          } catch {
+            // File was deleted during write
+            if (this.watchedFiles.has(fullPath)) {
+              this.watchedFiles.delete(fullPath);
+              this.events$.next({ type: 'unlink', path: fullPath });
+            }
+          }
+        }
+      }
+    } catch (error: any) {
+      this.events$.next({ type: 'error', path: fullPath, error });
+    }
+  }
+
+  /**
+   * Scan directory and emit 'add' events for existing files
+   */
+  private async scanDirectory(dirPath: string, depth: number): Promise<void> {
+    if (depth > this.options.depth) {
+      return;
+    }
+
+    try {
+      const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        const stats = await this.statSafe(fullPath);
+
+        if (!stats) {
+          continue;
+        }
+
+        if (entry.isDirectory()) {
+          this.watchedFiles.add(fullPath);
+          this.events$.next({ type: 'addDir', path: fullPath, stats });
+          await this.scanDirectory(fullPath, depth + 1);
+        } else if (entry.isFile()) {
+          this.watchedFiles.add(fullPath);
+          this.events$.next({ type: 'add', path: fullPath, stats });
+        }
+      }
+    } catch (error: any) {
+      if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
+        this.events$.next({ type: 'error', path: dirPath, error });
+      }
+    }
+  }
+
+  /**
+   * Safely stat a path, returning null if it doesn't exist
+   */
+  private async statSafe(filePath: string): Promise<fs.Stats | null> {
+    try {
+      if (this.options.followSymlinks) {
+        return await fs.promises.stat(filePath);
+      } else {
+        return await fs.promises.lstat(filePath);
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if a path was known to be a directory (for proper unlink event type)
+   */
+  private isKnownDirectory(filePath: string): boolean {
+    // Check if any watched files are children of this path
+    for (const watched of this.watchedFiles) {
+      if (watched.startsWith(filePath + path.sep)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Throttle duplicate events
+   */
+  private shouldEmit(filePath: string, eventType: string): boolean {
+    const key = `${filePath}:${eventType}`;
+    const now = Date.now();
+    const lastEmit = this.recentEvents.get(key);
+
+    if (lastEmit && now - lastEmit < this.throttleMs) {
+      return false;
+    }
+
+    this.recentEvents.set(key, now);
+
+    // Clean up old entries periodically
+    if (this.recentEvents.size > 1000) {
+      const cutoff = now - this.throttleMs * 2;
+      for (const [k, time] of this.recentEvents) {
+        if (time < cutoff) {
+          this.recentEvents.delete(k);
+        }
+      }
+    }
+
+    return true;
+  }
+}