### Consume TailFile Data Events in Node.js

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

This example demonstrates how to instantiate `TailFile` and consume new log lines using the 'data' event. It also includes error handling for tailing-specific errors and general stream errors, and shows how to catch errors during the `start()` method call.

```js
const TailFile = require('@logdna/tail-file')

const tail = new TailFile('/path/to/your/logfile.txt', {encoding: 'utf8'})
  .on('data', (chunk) => {
    console.log(`Recieved a utf8 character chunk: ${chunk}`)
  })
  .on('tail_error', (err) => {
    console.error('TailFile had an error!', err)
  })
  .on('error', (err) => {
    console.error('A TailFile stream error was likely encountered', err)
  })
  .start()
  .catch((err) => {
    console.error('Cannot start.  Does the file exist?', err)
  })
```

--------------------------------

### Install TailFile Node.js Package

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

This command installs the `@logdna/tail-file` package using npm, making it available for use in Node.js projects. It's the standard way to add the library as a dependency.

```sh
npm install @logdna/tail-file
```

--------------------------------

### TailFile Constructor and Methods API

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

Provides a comprehensive API reference for the TailFile module, including its constructor for instantiation with various configuration options, and key methods like `start()` to begin file polling and `quit()` to gracefully terminate the tailing process.

```APIDOC
Constructor: new TailFile(filename[, options])
  filename <String> - The filename to tail. Poll errors do not happen until start is called.
  options <Object> - Optional
    pollFileIntervalMs <Number> - How often to poll filename for changes. Default: 1000ms
    pollFailureRetryMs <Number> - After a polling error (ENOENT?), how long to wait before retrying. Default: 200ms
    maxPollFailures <Number> - The number of times to retry a failed poll before exiting/erroring. Default: 10 times.
    readStreamOpts <Object> - Options to pass to the fs.createReadStream function. This is used for reading bytes that have been added to filename between every poll.
    startPos <Number> - An integer representing the inital read position in the file. Useful for reading from 0. Default: null (start tailing from EOF)
    Any additional key-value options get passed to the Readable superclass constructor of TailFile
  Throws: <TypeError>|<RangeError> if parameter validation fails
  Returns: TailFile, which is a Readable stream

tail.start()
  Returns: <Promise> - Resolves after the file is polled successfully
  Rejects: If filename is not found

tail.quit()
  Returns: <Promise> - Resolves after flush is called and streams are closed.
  Emits: close when the parent Readstream is ended.
```

--------------------------------

### TailFile Class API Reference

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

Comprehensive API documentation for the `TailFile` class, including its constructor, methods for starting and stopping the tailing process, and a list of events it emits. This class extends Node.js's `Readable` stream.

```APIDOC
TailFile Class:

Constructor: new TailFile(filename[, options])
  - Description: Instantiates a new TailFile object to begin tailing the specified file.
  - Parameters:
    - filename (string): The full path to the file to be tailed.
    - options (object, optional): Configuration options for the tailer.
      - encoding (string): The character encoding to use for data chunks (e.g., 'utf8', 'ascii'). Defaults to 'utf8'.
      - pollInterval (number): The interval in milliseconds at which to poll the file for changes. Defaults to 1000 (1 second).
      - startOffset (number): The byte offset from which to start reading the file. Defaults to 0 (beginning of file).
      - fromBeginning (boolean): If true, starts reading from the beginning of the file even if it's larger than the last known size. Defaults to false.
  - Returns: A new TailFile instance (a Readable stream).

Method: tail.start()
  - Description: Initiates the file tailing process. This method must be called to begin receiving data events. It returns a Promise that resolves when tailing successfully starts or rejects if the file cannot be accessed.
  - Parameters: None.
  - Returns: Promise<void>

Method: tail.quit()
  - Description: Stops the file tailing process and cleans up any open file handles or timers. This should be called for a clean shutdown.
  - Parameters: None.
  - Returns: void

Events:
  - Event: 'data' (chunk: Buffer | string)
    - Description: Emitted when new data is read from the tailed file. The chunk type depends on the encoding option.
  - Event: 'flush' (size: number)
    - Description: Emitted when the internal buffer is flushed, indicating that all pending data has been processed.
    - Parameters:
      - size (number): The number of bytes flushed.
  - Event: 'renamed' (filename: string)
    - Description: Emitted when the tailed file is detected to have been renamed. The new filename is provided.
    - Parameters:
      - filename (string): The new path of the renamed file.
  - Event: 'retry' (err: Error, interval: number)
    - Description: Emitted when an error occurs during file access and the system is retrying after a delay.
    - Parameters:
      - err (Error): The error that occurred.
      - interval (number): The time in milliseconds until the next retry attempt.
  - Event: 'tail_error' (err: Error)
    - Description: Emitted for errors specific to the tailing logic, such as file access issues or unexpected file system changes.
    - Parameters:
      - err (Error): The error object.
  - Event: 'truncated' (size: number)
    - Description: Emitted when the tailed file is detected to have been truncated (its size has decreased).
    - Parameters:
      - size (number): The new size of the truncated file.
  - Event: 'error' (err: Error)
    - Description: Emitted for general stream errors, typically indicating a problem with the underlying Readable stream.
    - Parameters:
      - err (Error): The error object.
```

--------------------------------

### Graceful Shutdown and Last Read Position Tracking with TailFile

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

Illustrates how to perform a clean shutdown of the `TailFile` instance using `quit()` and how to track the last read file position for resuming operations later. This example includes handling the `SIGINT` signal for graceful termination and persisting the file position.

```javascript
const TailFile = require('@logdna/tail-file')
let position // Can be used to resume the last position from a new instance

const tail = new TailFile('./somelog.txt')

process.on('SIGINT', () => {
  tail.quit()
    .then(() => {
      console.log(`The last read file position was: ${position}`)
    })
    .catch((err) => {
      process.nextTick(() => {
        console.error('Error during TailFile shutdown', err)
      })
    })
})

tail
  .on('flush', ({lastReadPosition}) => {
    position = lastReadPosition
  })
  .on('data', (chunk) => {
    console.log(chunk.toString())
  })
  .start()
  .catch((err) => {
    console.error('Cannot start.  Does the file exist?', err)
    throw err
  })
```

--------------------------------

### Pipe TailFile Output to a Stream in Node.js

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

This example illustrates a more common and realistic usage pattern where `TailFile`'s output (a Readable stream) is piped to another transform stream, `split2`, to process data line by line. It highlights that data flow only begins after piping and includes robust error handling.

```js
const TailFile = require('@logdna/tail-file')
const split2 = require('split2') // A common and efficient line splitter

const tail = new TailFile('/path/to/your/logfile.txt')
tail
  .on('tail_error', (err) => {
    console.error('TailFile had an error!', err)
    throw err
  })
  .start()
  .catch((err) => {
    console.error('Cannot start.  Does the file exist?', err)
    throw err
  })

// Data won't start flowing until piping

tail
  .pipe(split2())
  .on('data', (line) => {
    console.log(line)
  })
```

--------------------------------

### Tail a File and Process Lines with Node.js readline

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

Demonstrates how to use the `@logdna/tail-file` library with Node.js's built-in `readline` module to process log file lines as they are appended. This approach provides a line-by-line interface for incoming data and includes basic error handling for file tailing.

```javascript
const readline = require('readline')
const TailFile = require('@logdna/tail-file')

async function startTail() {
  const tail = new TailFile('./somelog.txt')
    .on('tail_error', (err) => {
      console.error('TailFile had an error!', err)
    })

  try {
    await tail.start()
    const linesplitter = readline.createInterface({
      input: tail
    })

    linesplitter.on('line', (line) => {
      console.log(line)
    })
  } catch (err) {
    console.error('Cannot start.  Does the file exist?', err)
  }
}

startTail().catch((err) => {
  process.nextTick(() => {
    throw err
  })
})
```

--------------------------------

### TailFile Custom Events API Reference

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

Detailed documentation for custom events emitted by the `@logdna/tail-file` library, which extends Node.js's `Readable` stream. This section describes the purpose, parameters, and typical use cases for the `flush`, `renamed`, `retry`, and `tail_error` events.

```APIDOC
TailFile Custom Events:

Event: 'flush'
  - Parameters:
    - lastReadPosition: <Number> - The current file position at the time of flush.
  - Description: Emitted when the underlying stream has finished being read. This event is primarily used during shutdown to ensure all data is exhausted. Users can listen for this event to persist the `lastReadPosition` for resuming tailing later without missing or duplicating lines.

Event: 'renamed'
  - Parameters:
    - message: <String> - Static message: 'The file was renamed or rolled. Tailing resumed from the beginning.'
    - filename: <String> - The name of the file being tailed.
    - when: <Date> - The date and time when the event occurred.
  - Description: Emitted when a file with the same name is detected but has a different inode than the previously tailed file. This commonly occurs during log rotation, and tailing automatically resumes from the beginning of the new file.

Event: 'retry'
  - Parameters:
    - message: <String> - Static message: 'File disappeared. Retrying.'
    - filename: <String> - The name of the file being tailed.
    - attempts: <Number> - The current number of attempts to re-access the file.
    - when: <Date> - The date and time when the event occurred.
  - Description: Emitted for informational purposes when a tailed file disappears and `TailFile` attempts to re-poll it up to `maxPollFailures`. This can happen if log rolling occurs manually or at a timing that causes the file to be temporarily unavailable.

Event: 'tail_error'
  - Parameters:
    - message: <String> - The error message generated by TailFile.
    - code: <String> - Static value: 'ETAIL'.
    - meta: <Object> - Additional metadata for context.
      - actual: <Error> - The original error that was thrown (e.g., from the underlying stream).
  - Description: Emitted when an error specific to `TailFile` occurs that would otherwise cause the main `Readable` stream to end. This allows `TailFile` to report internal errors without terminating the primary stream.
```

--------------------------------

### TailFile Standard Readable Stream Events

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

Explains that TailFile implements a Node.js Readable stream, thus emitting standard stream events like 'close' (on exit) and 'data' (for consumed bytes), adhering to Node.js stream conventions.

```APIDOC
Event: (Any Readable event)
TailFile implements a Readable stream, so it may also emit these events. The most common ones are `close` (when `TailFile` exits), or `data` events from the stream.
```

--------------------------------

### TailFile 'truncated' Event Definition

Source: https://github.com/logdna/tail-file-node/blob/main/README.md

Defines the structure and purpose of the 'truncated' event emitted by the TailFile module when a tailed file is shortened or truncated, indicating that tailing has resumed from the beginning.

```APIDOC
Event: 'truncated'
  <Object>
    message <String> - Static message: 'The file was truncated. Tailing resumed from the beginning.'
    filename <String> - The filename that's being tailed
    when <Date> - The date/time when the event happened
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.