API Live Sync Part 5: File Watching

In this fifth part, I explore the file watching system that enables real-time detection of changes in API specification files.

Real-Time File Monitoring

The file watching component is crucial for maintaining live synchronization, as it detects changes in API specification files and triggers immediate updates.

File Watcher Interface

interface FileWatcher {
  // Watch management
  watchDirectory(path: string, options: WatchOptions): Promise<void>;
  unwatchDirectory(path: string): Promise<void>;

  // Event handling
  onFileChange(callback: (event: FileChangeEvent) => void): void;
  onFileDelete(callback: (event: FileDeleteEvent) => void): void;

  // Status and control
  isWatching(path: string): boolean;
  getWatchedPaths(): string[];
  stopAllWatching(): Promise<void>;
}

Watch Options Configuration

interface WatchOptions {
  recursive: boolean;
  ignorePatterns: string[];
  debounceMs: number;
  maxDepth: number;
  fileExtensions: string[];
}

Implementation Details

The file watcher uses Node.js’s fs.watch API with several optimizations:

Debouncing: Prevents excessive events from rapid file changes
Pattern Filtering: Only watches relevant file types (.yaml, .json, .md)
Recursive Watching: Monitors subdirectories for nested API specs
Event Aggregation: Groups related file changes to reduce processing overhead

Performance Considerations

File watching can be resource-intensive, so we’ve implemented several optimizations:

class OptimizedFileWatcher {
  private debounceTimers = new Map<string, NodeJS.Timeout>();
  private eventQueue: FileChangeEvent[] = [];

  private debounceEvent(path: string, callback: () => void, delay: number) {
    if (this.debounceTimers.has(path)) {
      clearTimeout(this.debounceTimers.get(path)!);
    }

    const timer = setTimeout(() => {
      callback();
      this.debounceTimers.delete(path);
    }, delay);

    this.debounceTimers.set(path, timer);
  }
}

Read the full article on Hashnode →