Tail

The zero dependency Node.js module for tailing a file

Made with ❤️ by Luca Grulla

1. TOC {:toc}

Installation

npm install tail

Use

Tail=require("tail").Tail;tail=newTail("fileToTail");tail.on("line",function(data){console.log(data);});tail.on("error",function(error){console.log("ERROR: ",error);});

If you want to stop tail:

tail.unwatch()

To start watching again:

tail.watch()

Configuration

The only mandatory parameter is the path to the file to tail.

varfileToTail="/path/to/fileToTail.txt";newTail(fileToTail)

If the file is missing or invalidTail constructor will throw an Exception and won't initialize.

try{newTail("missingFile.txt")}catch(ex){console.log(ex)}

Optional parameters can be passed via a hash:

varoptions={separator: /[\r]{0,1}\n/,fromBeginning: false,fsWatchOptions: {},follow: true,logger: console}newTail(fileToTail,options)

Constructor parameters

• separator: the line separator token (default: /[\r]{0,1}\n/ to handle linux/mac (9+)/windows). Pass null for binary files with no line separator.
• fsWatchOptions: the full set of options that can be passed to fs.watch as per node documentation (default: {}).
• fromBeginning: tail from the beginning of the file (default: false). If fromBeginning is true nLines will be ignored.
• follow: simulate tail -F option. In the case the file is moved/renamed/logrotated, if set to true will start tailing again after a 1 second delay; if set to false it will emit an error event (default: true).
• logger: a logger object(default: no logger). The passed logger should follow the following signature:
  • info([data][, ...])
  • error([data][, ...])
• nLines: tail from the last n lines. (default: undefined). Ignored if fromBeginning is set to true.
• useWatchFile: if set to true will force the use of fs.watchFile over delegating to the library the choice between fs.watch and fs.watchFile (default: false).
• encoding: the file encoding (default:utf-8).
• flushAtEOF: set to true to force flush of content when end of file is reached. Useful when there's no separator character at the end of the file (default: false).

Emitted events

Tail emits two events:

• line

tail.on("line",(data)=>{console.log(data)})

• error

tail.on("error",(err)=>{console.log(err)})

The error emitted is either the underlying exception or a descriptive string.

How to contribute

Node Tail code repo is here Tail is written in ES6. Pull Requests are welcome.

History

Tail was born as part of a data firehose. Read more about that project here. Tail originally was written in CoffeeScript. Since December 2020 it's pure ES6.

License

MIT. Please see License file for more details.