npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

tail-follow

v1.5.0

Published

Stream a file in real time as it grows

Downloads

6

Readme

tail-follow

Stream a file in real time as it grows.

Synopsis

If you are familiar with UNIX's tail -f, you have a good idea what this module does. It provides a Readable stream interface to a file that emits new data appended to the file in real time. It can even do the equivalent of tail -F, to survive log rotation.

There are a lot of tail modules on npm, but this one differentiates itself by:

  • Being a Readable stream, so your data event listeners get Buffer objects instead of decoded strings split by lines.
  • Providing an API for retrieving positional data about where in file a chunk of data was read from.
  • Having a knob for controlling how much data to try to read from the file at a time, since the default of 16KB is too small for rapidly growing files.
  • Emitting a rename event when the underlying file is renamed or rotated.

API

var TailFollow = require("tail-follow")

Constructor TailFollow(path, [options])

Create new TailFollow instance, for the file at the given path. This is a Readable stream, so you should listen for the error event and data event. Or pipe() it to another stream.

The optional arguments object takes the same parameters as a Readable stream (encoding and highWaterMark), plus the following:

  • tailChunkSize: Sets the size in bytes of Buffer objects created when reading from the file. Too small of a value, you will spend too much CPU handling new chunks; too big of a value, and you will waste memory. The default is 16384.
  • surviveRotation: Set to true so that if the underlying file is renamed or deleted, data will continue to be read from a new file created at the same path. Think tail -F. The default is false.
  • objectMode: Setting to true enables object mode like on any other Readable stream, but has a few side effects. It enables position tracking so that you may call .positionForChunk() to determine where in the file a chunk of data was read from. If you have enabled decoding (via the encoding option), note that this will also cause your data events to emit String instances (as opposed to string primitives).
  • follow: Default true. Setting to false will cause the stream to close when it reaches the end of the file instead of continuing to follow it.
  • fileRenamePollingInterval: Default is null. Setting this to a number will cause TailFollow to poll for file rename events every given number of milliseconds instead of relying on fs.watch() rename events. Try this if your tail sometimes stops after a rotation.

Event rename

Emitted when the underlying file has been renamed. The first argument sent to the event handler is the old file path, the second is the new file path. Currently, this is limited to moves within the same directory, or within sibling directories of the file.

Method unfollow()

Stops following the file and ends the stream.

Method positionForChunk(chunk)

Returns the number of bytes from the beginning of the file that the chunk starts at. This must be the same object that was emitted to your data event handler. The stream must also be in objectMode. (See the documentation for the objectMode constructor option.)

Method setTailChunkSize(size)

See the documentation for the tailChunkSize constructor option above.

Method setSurviveRotation(bool)

See the documentation for the surviveRotation constructor option above.

Method setFileRenamePollingInterval(milliseconds)

See the documentation for the fileRenamePollingInterval constructor option above.

Property filePath

Convenience property to get the full path of the file that the instance is following.

Debugging

Run node with DEBUG=tail-follow.

Contributing

This module uses ES2015. To compile the source to ES5 (compatible with Node.js, io.js), run npm run compile.

Any changes in behavior need test coverage. To run the tests, run npm test.