change events for any file descriptors that are referenced by a watched path or were referenced by a watched path for as long as they are active
JavaScript Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Build Status


Watch events open,change,unlink on all files that are refrenced or become refrenced by path

provide events for any file descriptors that are referenced by a watched path, or were referenced by a watched path for as long as they are still changing. active is defined by a timeout since last event. file descriptors that become inactive are removed.


npm install watchfd


var watchfd = require('watchfd').watch;
	console.log(prev.size,' changed to ',cur.size);

a use case

an issue with log/file forwarding utilities currently available in npm is that they only watch the file descriptor under the filename. when a log is rotated and a new log is created the server may not stop writing to the old file descriptor immediately. Any data written to that descriptor in this state ends up in /dev/null

argument structure, [options], listener)

  • filename its really intended that this be a regular file or non existant. i dont know what would happen right now if its a directory.

  • options. supported custom options are

     "timeout": 60*60*1000, //defaults to one hour
     //how long an inactive file descriptor can remain inactive
     "timeoutInterval":60*5*1000 //every five minutes
     // how often to check for inactive file descriptors
     //the options object is also passed directly to watch and watchFile so you may configure
     "persistent":true, //defaults to true
     //persistent indicates whether the process should continue to run as long as files are being watched
     "interval":0, //defaults 0
     //interval indicates how often the target should be polled, in milliseconds. (On Linux systems with inotify, interval is ignored.) 
  • callback this is bound to the change event of the watcher. its required


    cur and prev are instances of fs.Stats

  • @returns an instance of Watcher

Watcher methods


  • paused, changed and last state is kept for each file descriptor
    • stops file descriptors from timing out.
    • all events except error are paused.
    • unlink, open, change etc will be fired in the correct order after resume. no events will be missed but change events will be combined


  • resumed
    • for each file descriptor pending events are fired in the corect order open,change,unlink
    • the change event has the stat from first change event while paused and the most recent so no change is missed.


  • is paused
  • readonly please.

Watcher events

Watcher.on(event name,call back);

  • change fs.Stats cur, fs.Stats prev
  • open fs.Stats cur,{fd:file descriptor,stat:fs.Stats cur}
  • unlink fs.Stats cur,{fd:file descriptor,stat:fs.Stats cur}
  • timeout fs.Stats cur,{fd:file descriptor,stat:fs.Stats cur}

windows support problems

  • It uses file inode as a unique id for each descriptor. I know there is a way to get a unique id for a file in windows i just don't know if that would be passed to stat as stat.ino.
  • I use watchFile which is not supported at all on windows but this would be easier to overcome considering i can use a configured polling interval as a stat polling fall back on windows.
  • I also don't know windows very well and don't know if windows has the problem this module solves...but i imagine it would


I noticed distinct differences in watchFile vs watch api fs.watchFile will issue events for a file that is currently referenced by a path will take a path but issue events whenever that file descriptor is changed even after it's unlinked

We should probably design servers to listen to SIGHUP and grab new file descriptors for all loggers but even if you used logrotate with copytruncate mode as to not change the file referenced by a path the chance that you will loose data is still there. I feel safer waiting for a file descriptor to be quiet so i know its out of use before i close it in a process that has the ability to read data out of it.