@ideadesignmedia/watcher NPM

@ideadesignmedia/watcher

A lightweight, event-driven file and directory watcher built on top of chokidar, with buffered event queuing, rename detection, and TypeScript typings.

Features

Simple setup: Watch one or more paths with a single class.
Buffered events: Debounced and queued add, change, and unlink events for reliable ordering.
Rename detection: Automatically detects renames by matching file statistics.
Configurable: Fine-tune polling, ignore patterns, atomic writes, and more.
TypeScript support: Bundled .d.ts for type-safe development.

Installation

npm install @ideadesignmedia/watcher chokidar
# or
yarn add @ideadesignmedia/watcher chokidar

Note: chokidar is a peer dependency and must be installed separately.

Quick Start

const Watcher = require('@ideadesignmedia/watcher');

// Callback to handle file events:
function onFileEvent(eventName, { path, stats }, isRename) {
  console.log(`Event: ${eventName}`, path, stats, 'isRename:', isRename);
}

// Create a new watcher:
const watcher = new Watcher(
  ['./src', './assets'], // paths to watch
  onFileEvent,
  {
    ignored: ['**/*.tmp', 'node_modules'], // ignore patterns
    initialAdd: true,                     // emit add events for existing files on init
    persistent: true,                     // keep the process alive
    pollInterval: 1000,                   // interval for polling (ms)
    binaryInterval: 3000,                 // interval for binary files (ms)
    alwaysStat: true,                     // always stat files
    awaitWriteFinish: {                   // wait for write finish
      stabilityThreshold: 1000,
      pollInterval: 1500
    },
    ignorePermissionErrors: false,        // ignore EACCES errors
    atomic: 800                           // watch atomic writes
  }
);

// Dynamically add another path:
watcher.addPath('/var/logs');

// Manually refresh the folder/file list in console:
watcher.getFolders();

// Stop watching and clean up:
// watcher.close();

API

`new watcher(paths, FileEvent, options?)`

paths: string[] — An array of file system paths (files or directories) to watch.

FileEvent: function — A callback invoked for each queued event:

type EventName = 'addFile' | 'addDir' | 'changeFile' | 'deleteFile' | 'deleteDir';
type WatcherEvent = { path: string; stats?: Stats };
(eventName: EventName, eventData: WatcherEvent, isRename: boolean) => void;

options: WatcherOptions (all optional):

interface WatcherOptions {
  ignored?: string[];                // glob or regex patterns to ignore
  initialAdd?: boolean;              // emit existing files as add events on ready
  persistent?: boolean;              // keep process alive after ready
  polling?: boolean;                 // use fs polling (defaults to true)
  pollInterval?: number;             // polling interval in ms (default: 1000)
  binaryInterval?: number;           // polling interval for binary files in ms (default: 3000)
  alwaysStat?: boolean;              // always stat files for change detection
  awaitWriteFinish?: boolean | {     // wait for write finish settings
    stabilityThreshold: number;
    pollInterval: number;
  };
  ignorePermissionErrors?: boolean;  // skip permission errors
  atomic?: number;                   // threshold for atomic writes
}

Methods

addPath(path: string): void
Add a new path to the existing watcher at runtime.
getFolders(): void
Refresh and log the list of watched folders and files. Useful for debugging.
close(): void
Stops watching all paths and releases resources.

Example: TypeScript

import Watcher, { Stats } from '@ideadesignmedia/watcher';

const watcher = new Watcher(
  ['logs'],
  (eventName, { path, stats }, isRename) => {
    console.log(eventName, path, stats?.size, isRename);
  },
  { initialAdd: true }
);