Readstream-watcher NPM

ReadStream-Watcher

We got that fs.ReadStream, we got that FSWatcher, we got that combination fs.ReadStream and FSWatcher. (If the joke is lost on you, see this video.)

Installation

npm install [--save] readstream-watcher

Usage

A simple example, which prints the file's contents (entirely, unlike tail -f or similar) once every time the file changes.

var createReadStreamWatcher = require('readstream-watcher');

function printWaitLoop() {
  createReadStreamWatcher('./some-file')
    .once('change', function () {
      this.close();
      this.unpipe(process.stdout);
      printWaitLoop();
    })
    .pipe(process.stdout);
}

printWaitLoop();

ReadStreamWatcher interface

As it turns out, there are a lot of undocumented methods on ReadStream and FSWatcher instances. As a result, and to avoid confusing collisions, only a subset of their API is supported:

Property	Origin	Description
`path`	`ReadStream`	The path to the file the stream is reading from.
`pipe(destination, [options])`	`ReadStream`	Writes all the data to the supplied destination.
`read([size])`	`ReadStream`	Returns `size` bytes of available data, returning `null` otherwise.
`close()`	`FSWatcher`	Stop watching for changes on the given `FSWatcher`. No changes are made to the stream.

Event	Origin	Description
`open`	`ReadStream`	Emitted when the ReadStream's file is opened with the now-open file descriptor.
`close`	`ReadStream`	Emitted when the stream and any of its underlying resources have been closed.
`data`	`ReadStream`	Emitted when data is available, setting the stream into flowing mode.
`end`	`ReadStream`	Emitted when there will be no more data to read.
`readable`	`ReadStream`	Emitted when a chunk of data can be read from the stream.
`change`	`FSWatcher`	Emitted when something changes in the watched file.
`error`	`ReadStream/FSWatcher`	Emitted when an error occurs, passing along that `Error` instance.

Finally, the constructor itself, returned when require-ing the module, accepts two arguments: the filename to watch, and options to pass into both the ReadStream and the FSWatcher. The supported options, then, are the sum of those two constructors. The most common options are:

Option	Origin	Description
`encoding`	`ReadStream`	If specified, data read will be in the specified format in lieu of Buffers. Defaults to `null`.
`persistent`	`FSWatcher`	If `true`, the process should continue to run as long as files are being watched. Defaults to `true`.

Relevant Links

@infinitebrahmanuniverse/nolb-reads @everything-registry/sub-chunk-2629

1.0.0

10 years ago