feat: add TailFileStream (#1)

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        node-version: [18, 20]
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - name: Install
+      run: |
+        npm install
+
+    - name: Test
+      run: |
+        npm test

.gitignore

@@ -128,3 +128,9 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+# lock files
+bun.lockb
+package-lock.json
+pnpm-lock.yaml
+yarn.lock

.npmrc

@@ -0,0 +1 @@
+package-lock=false

README.md

@@ -1 +1,98 @@
-# tail-file-stream
+# tail-file-stream
+
+__tail-file-stream__ is a library that provides a streaming interface for reading a file that can be appended.
+It implements the Node.js fs.ReadStream functionality and watches the file for changes.
+When the file is appended, the stream emits a 'data' event with the new data.
+
+- [Install](#install)
+- [Usage](#usage)
+- [API](#api)
+  - [createReadStream(path, [options])](#createreadstreampath-options)
+  - [TailFileStream](#tailfilestream)
+- [License](#license)
+
+<a name="install"></a>
+
+## Install
+
+```
+npm i tail-file-stream --save
+```
+
+<a name="usage"></a>
+
+## Usage
+
+```js
+const { createReadStream } = require('tail-file-stream')
+
+const stream = createReadStream('./foo.txt')
+
+stream.on('data', (chunk) => {
+  // Emits when has new data
+})
+stream.on('eof', () => {
+  // Emits when reaches the end of the file
+})
+stream.on('end', () => {
+  // Emits when stream ends
+})
+
+setTimeout(() => {
+  // Stop watching the file
+  stream.unwatch()
+}, 10000)
+
+```
+
+<a name="api"></a>
+
+## API
+
+<a name="create-read-stream"></a>
+
+#### createReadStream(path, [options])
+
+Creates a new `TailFileStream` instance.
+
+- `path` `<string>` The file path to be read.
+- `options` `<Object>` Options for the stream.
+  - `flags` `<string>` See [support of file system](https://nodejs.org/docs/latest/api/fs.html#file-system-flags) flags. Default: `'r'`.
+  - `mode` `<number>` Default: `0o666`.
+  - `start` `<number>` The byte offset to start reading from. Default: `0`.
+  - `end` `<number>` The byte offset to stop reading. Default: `Infinity`.
+  - `highWaterMark` `<number>` The maximum number of bytes to store in the internal buffer. Default: `64 * 1024`.
+  - `autoWatch` `<boolean>` If `true`, the file will be watched for changes from the beginning. Default: `true`.
+  - `persistent` `<boolean>` Indicates whether the process should continue to run as long as files are being watched. Default: `true`.
+- Returns: `TailFileStream` The stream instance.
+
+#### TailFileStream
+
+The `TailFileStream` class extends the Node.js [Readable](https://nodejs.org/docs/latest/api/stream.html#class-streamreadable) stream.
+
+`TailFileStream` emits the following events:
+
+- `close` - Emits when the file is closed.
+- `eof` - Emits when reaches the end of the file.
+- `open` - Emits when the file is opened.
+- `ready` - Emits when the file is ready to be read.
+
+`TailFileStream` has the following properties:
+
+- `bytesRead` `<number>` The number of bytes read from the file.
+- `path` `<string>` The file path.
+- `pending` `<boolean>` This property is true if the underlying file has not been opened yet, i.e. before the 'ready' event is emitted.
+- `watching` `<boolean>` Indicates whether the file is being watched.
+- `waiting` `<boolean>` Indicates whether the stream is waiting for file changes.
+
+`TailFileStream` has the following methods:
+
+- `watch()` - Starts watching the file for changes.
+- `unwatch()` - Stops watching the file. If the stream is waiting for file changes, it will be closed.
+If the stream is reading, the data will be read until the end of the file and then it will be closed.
+
+<a name="license"></a>
+
+## License
+
+MIT

index.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="node" />
+
+import { Readable } from 'node:stream';
+
+declare class TailFileStream extends Readable {
+  constructor(path: string, options?: TailFileStreamOptions);
+  readonly pending: boolean;
+  readonly watching: boolean;
+  readonly waiting: boolean;
+  close(cb?: (err?: NodeJS.ErrnoException) => void): void;
+  watch(): void;
+  unwatch(): void;
+}
+
+interface TailFileStreamOptions {
+  highWaterMark?: number;
+  flags?: string;
+  mode?: number;
+  start?: number;
+  end?: number;
+  autoWatch?: boolean;
+  persistent?: boolean;
+}
+
+declare function createReadStream(path: string, options?: TailFileStreamOptions): TailFileStream;
+
+export { TailFileStream, TailFileStreamOptions, createReadStream };

index.js

@@ -0,0 +1,210 @@
+/*
+Copyright Platformatic. All rights reserved.
+Copyright Node.js contributors. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+*/
+
+'use strict'
+
+const { Readable, finished } = require('node:stream')
+const fs = require('node:fs')
+
+const ioDone = Symbol('ioDone')
+
+class TailFileStream extends Readable {
+  #watching = false
+  #waiting = false
+  #performingIO = false
+
+  #start
+  #end
+  #pos
+  #flags
+  #mode
+  #fd
+
+  #autoWatch
+  #persistent
+
+  constructor (path, options = {}) {
+    if (options.highWaterMark === undefined) {
+      options.highWaterMark = 64 * 1024
+    }
+
+    super(options)
+
+    this.path = path
+    this.#flags = options.flags ?? 'r'
+    this.#mode = options.mode ?? 0o666
+
+    this.#start = options.start ?? 0
+    this.#end = options.end ?? Infinity
+    this.#pos = this.#start
+    this.bytesRead = 0
+
+    this.#autoWatch = options.autoWatch ?? true
+    this.#persistent = options.persistent ?? true
+
+    this.#fd = null
+    this.watcher = null
+  }
+
+  get pending () {
+    return this.#fd === null
+  }
+
+  get watching () {
+    return this.#watching
+  }
+
+  get waiting () {
+    return this.#waiting
+  }
+
+  _construct (cb) {
+    if (this.#autoWatch) {
+      this.watch()
+    }
+
+    fs.open(this.path, this.#flags, this.#mode, (err, fd) => {
+      if (err) {
+        cb(err)
+      } else {
+        this.#fd = fd
+        cb()
+        process.nextTick(() => {
+          this.emit('open', this.#fd)
+          this.emit('ready')
+        })
+      }
+    })
+  }
+
+  _read (n) {
+    n = Math.min(this.#end - this.#pos + 1, n)
+
+    if (n <= 0) {
+      this.push(null)
+      return
+    }
+
+    const buf = Buffer.allocUnsafeSlow(n)
+
+    this.#performingIO = true
+    fs.read(this.#fd, buf, 0, n, this.#pos, (err, bytesRead, buf) => {
+      this.#performingIO = false
+
+      /* c8 ignore next 4 */
+      if (this.destroyed) {
+        this.emit(ioDone, err)
+        return
+      }
+
+      if (err) {
+        this.emit('error', err)
+        this.destroy(err)
+        return
+      }
+
+      if (bytesRead === 0) {
+        if (this.#watching) {
+          this.#waiting = true
+          this.watcher.once('change', () => {
+            this.#waiting = false
+            this._read(n)
+          })
+        } else {
+          this.push(null)
+        }
+        this.emit('eof')
+        return
+      }
+
+      this.#pos += bytesRead
+      this.bytesRead += bytesRead
+
+      if (bytesRead !== buf.length) {
+        const dst = Buffer.allocUnsafeSlow(bytesRead)
+        buf.copy(dst, 0, 0, bytesRead)
+        buf = dst
+      }
+
+      this.push(buf)
+    })
+  }
+
+  watch () {
+    this.#watching = true
+
+    if (!this.watcher) {
+      this.watcher = fs.watch(this.path, {
+        persistent: this.#persistent
+      })
+    }
+  }
+
+  unwatch () {
+    this.#autoWatch = false
+    this.#watching = false
+
+    if (this.watcher) {
+      this.watcher.close()
+      this.watcher = null
+    }
+
+    if (this.#waiting) {
+      this.#waiting = false
+      this.push(null)
+    }
+  }
+
+  _destroy (err, cb) {
+    this.unwatch()
+
+    /* c8 ignore next 3 */
+    if (this.#performingIO) {
+      this.once(ioDone, (er) => this.#close(err || er, cb))
+    } else {
+      this.#close(err, cb)
+    }
+  }
+
+  close (cb) {
+    if (typeof cb === 'function') finished(this, cb)
+    this.destroy()
+  }
+
+  #close (err, cb) {
+    if (this.#fd) {
+      fs.close(this.#fd, (er) => cb(er || err))
+      this.#fd = null
+    } else {
+      cb(err)
+    }
+  }
+}
+
+function createReadStream (path, options) {
+  return new TailFileStream(path, options)
+}
+
+module.exports = {
+  createReadStream
+}