{
  "name": "watchfd",
  "description": "watch events open,change,unlink on all files that are refrenced or become refrenced by path. pause/resumeable",
  "version": "0.0.13",
  "author": {
    "name": "Ryan Day",
    "email": "soldair@gmail.com"
  },
  "keywords": [
    "watch",
    "descriptors",
    "log",
    "fs"
  ],
  "main": "./watch.js",
  "homepage": "http://github.com/soldair/node-watchfd",
  "repository": {
    "type": "git",
    "url": "git://github.com/soldair/node-watchfd.git"
  },
  "scripts": {
    "test": "tap ./test/unit/*.js"
  },
  "devDependencies": {
    "tap": "*",
    "jshint": "0.5.x"
  },
  "engines": {
    "node": ">=0.6.0"
  },
  "dependencies": {},
  "license": "MIT/X11",
  "readme": "[![Build Status](https://secure.travis-ci.org/soldair/node-watchfd.png)](http://travis-ci.org/soldair/node-watchfd)\n\n## watchfd\n\nWatch events open,change,unlink on all files that are refrenced or become refrenced by path\n\nprovide events for any file descriptors that are referenced by a watched path, \nor were referenced by a watched path for as long as they are still changing.\nactive is defined by a timeout since last event. file descriptors that become inactive are removed.\n\n\n## install\n\n\tnpm install watchfd\n\n## use\n\n\tvar watchfd = require('watchfd').watch;\n\twatchfd('/some.log',function(cur,prev){\n\t\tconsole.log(prev.size,' changed to ',cur.size);\n\t});\n\n### a use case\n\nan 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\n\n\n### argument structure\n\nwatchfd.watch(filename, [options], listener)\n\n- filename\n  its really intended that this be a regular file or non existant. i dont know what would happen right now if its a directory.\n- options. supported custom options are\n\n\t```js\n\t{\n\t\"timeout\": 60*60*1000, //defaults to one hour\n\t//how long an inactive file descriptor can remain inactive\n\n\t\"timeoutInterval\":60*5*1000 //every five minutes\n\t// how often to check for inactive file descriptors\n\t}\n\n\t//the options object is also passed directly to watch and watchFile so you may configure\n\n\t{\n\t\"persistent\":true, //defaults to true\n\t//persistent indicates whether the process should continue to run as long as files are being watched\n\n\t\"interval\":0, //defaults 0\n\t//interval indicates how often the target should be polled, in milliseconds. (On Linux systems with inotify, interval is ignored.) \n\t}\n\t```\n\n- callback\n  this is bound to the change event of the watcher. its required\n\n\t```js\n\tcallback(cur,prev)\n\t```\n\n  cur and prev are instances of fs.Stats\n\n- @returns\n  an instance of Watcher\n\n### Watcher methods\n\nWatcher.pause()\n\n- paused, changed and last state is kept for each file descriptor\n  - stops file descriptors from timing out.\n  - all events except error are paused.\n  - unlink, open, change etc will be fired in the correct order after resume. \n    no events will be missed but change events will be combined\n\n\nWatcher.resume()\n\n- resumed\n  - for each file descriptor pending events are fired in the corect order\n    open,change,unlink\n  - the change event has the stat from first change event while paused and the most recent so no change is missed.\n\n\nWatcher.paused\n\n - is paused\n - readonly please.\n\n### Watcher events\n\nWatcher.on(event name,call back);\n\n- change\n\t\tfs.Stats cur, fs.Stats prev\n- open\n\t\tfs.Stats cur,{fd:file descriptor,stat:fs.Stats cur}\n- unlink\n                fs.Stats cur,{fd:file descriptor,stat:fs.Stats cur}\n- timeout\n                fs.Stats cur,{fd:file descriptor,stat:fs.Stats cur}\n\n#### windows support problems\n\n- 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. \n- 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. \n- 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\n\n#### notes\n\nI noticed distinct differences in watchFile vs watch api\nfs.watchFile will issue events for a file that is currently referenced by a path\nfs.watch will take a path but issue events whenever that file descriptor is changed even after it's unlinked\n\nWe 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.\n",
  "readmeFilename": "readme.md",
  "bugs": {
    "url": "https://github.com/soldair/node-watchfd/issues"
  },
  "_id": "watchfd@0.0.13",
  "_from": "watchfd@~0.0.12"
}
