readeof 1.0.1 → 1.1.0

package/README.md

@@ -7,6 +7,8 @@ A high-performance, memory-efficient library to read large files backward (line-
 - Fast file reading from the end without loading entire file into memory
 - Memory efficient using configurable buffer sizes
 - Supports various encodings
+- Real-time file tailing (like `tail -f`) with streaming support
+- Automatic handling of file truncation/rotation
 
 ## Installation
 
@@ -42,7 +44,7 @@ console.log(recentLogs);
 import { readeof } from 'readeof';
 
 // Read file with latin1 encoding
-const content = await readeof('./data.txt', 20, 'latin1');
+const content = await readeof('./data.txt', 20, { encoding: 'latin1' });
 ```
 
 ### Custom Buffer Size
@@ -51,24 +53,62 @@ const content = await readeof('./data.txt', 20, 'latin1');
 import { readeof } from 'readeof';
 
 // Use 64KB buffer for very large files
-const content = await readeof('./huge-log.log', 100, 'utf8', 64 * 1024);
+const content = await readeof('./huge-log.log', 100, {
+  encoding: 'utf8',
+  bufferSize: 64 * 1024,
+});
 ```
 
-### Real-time Log Monitoring
+### Real-time Log Streaming (tail -f)
+
+Stream new lines as they are appended to the file. First reads the last N lines, then continues watching for new content.
 
 ```typescript
 import { readeof } from 'readeof';
 
-async function monitorLog(filePath: string) {
-  setInterval(async () => {
-    const latestLines = await readeof(filePath, 5);
-    console.clear();
-    console.log('=== Latest Logs ===');
-    console.log(latestLines);
-  }, 2000);
+// Stream with AbortController for manual control
+const controller = new AbortController();
+
+for await (const line of readeof('/var/log/app.log', 10, {
+  enabled: true,
+  signal: controller.signal,
+})) {
+  console.log(line);
+
+  // Stop streaming when needed
+  if (line.includes('SHUTDOWN')) {
+    controller.abort();
+  }
 }
+```
+
+### Streaming with Timeout
+
+```typescript
+import { readeof } from 'readeof';
 
-monitorLog('/var/log/application.log');
+// Stream for 30 seconds then stop automatically
+for await (const line of readeof('/var/log/app.log', 10, {
+  enabled: true,
+  signal: AbortSignal.timeout(30_000),
+})) {
+  console.log(line);
+}
+```
+
+### Streaming with Custom Poll Interval
+
+```typescript
+import { readeof } from 'readeof';
+
+// Check for new content every 500ms instead of default 1000ms
+for await (const line of readeof('/var/log/app.log', 10, {
+  enabled: true,
+  pollInterval: 500,
+  signal: AbortSignal.timeout(60_000),
+})) {
+  console.log(line);
+}
 ```
 
 ### Error Analysis
@@ -86,6 +126,40 @@ async function findRecentErrors(logPath: string) {
 }
 ```
 
+## API Reference
+
+### `readeof(filePath, maxLines, options?)`
+
+Reads the last N lines from a file efficiently.
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | `string` | Path to the file to read from |
+| `maxLines` | `number` | Total lines to read from the end of the file |
+| `options` | `ReadOptions \| StreamOptions` | Optional configuration options |
+
+#### ReadOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `encoding` | `BufferEncoding` | `'utf8'` | File encoding |
+| `bufferSize` | `number` | `16384` | Buffer size for reading (16KB) |
+
+#### StreamOptions (extends ReadOptions)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | - | Enable streaming mode |
+| `pollInterval` | `number` | `1000` | Polling interval in milliseconds |
+| `signal` | `AbortSignal` | - | Signal to stop streaming |
+
+#### Returns
+
+- **Without streaming**: `Promise<string>` - The last N lines as a single string
+- **With streaming**: `AsyncGenerator<string>` - Yields each line as it appears
+
 ## License
 
 See [LICENSE](LICENSE) file for details.

package/dist/index.d.ts

@@ -1,32 +1,76 @@
 /**
- * Reads the last N lines from a file efficiently.
- *
- * @param filePath - Path to the file to read from
- * @param maxLines - Total lines to read from the end of the file
- * @param encoding - File encoding (default: 'utf8')
- *                   Available encodings: https://nodejs.org/api/buffer.html#buffers-and-character-encodings
- * @param bufferSize - Buffer size to use when reading the file (default: 16KB)
- *                     A larger buffer size may improve performance for large files.
- * @returns A promise that resolves to a string containing the last N lines of the file
+ * Options for reading the file
  */
-export declare function readeof(
+export interface ReadOptions {
+    /**
+     * File encoding (default: 'utf8')
+     *
+     * Available encodings: https://nodejs.org/api/buffer.html#buffers-and-character-encodings
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Buffer size to use when reading the file (default: 16KB)
+     *
+     * A larger buffer size may improve performance for large files.
+     */
+    bufferSize?: number;
+}
 /**
- * Path to the file to read from
+ * Options for streaming/tailing the file
  */
-filePath: string, 
+export interface StreamOptions extends ReadOptions {
+    /**
+     * Enable streaming mode to tail the file after reading last N lines
+     */
+    enabled: boolean;
+    /**
+     * Polling interval in milliseconds (default: 1000)
+     */
+    pollInterval?: number;
+    /**
+     * AbortSignal to stop tailing
+     */
+    signal?: AbortSignal;
+}
 /**
- * Total lines to read from the end of the file
- */
-maxLines: number, 
-/**
- * File encoding (default: 'utf8')
+ * Reads the last N lines from a file efficiently.
+ * Can optionally continue streaming new lines as they are appended.
  *
- * Available encodings: https://nodejs.org/api/buffer.html#buffers-and-character-encodings
- */
-encoding?: BufferEncoding, 
-/**
- * Buffer size to use when reading the file (default: 16KB)
+ * @param filePath - Path to the file to read from
+ * @param maxLines - Total lines to read from the end of the file
+ * @param options - Optional options for reading/streaming
+ * @returns A promise that resolves to a string, or an async generator if streaming is enabled
+ *
+ * @example
+ * ```typescript
+ * // Read last 10 lines
+ * const lines = await readeof('/var/log/app.log', 10);
+ *
+ * // Read last 10 lines with custom encoding
+ * const lines = await readeof('/var/log/app.log', 10, { encoding: 'utf8' });
+ *
+ * // Read last 10 lines and continue streaming
+ * const controller = new AbortController();
+ * for await (const line of readeof('/var/log/app.log', 10, {
+ *   enabled: true,
+ *   signal: controller.signal
+ * })) {
+ *   console.log(line);
+ * }
  *
- * A larger buffer size may improve performance for large files.
+ * // Read last 10 lines and continue streaming with 30s timeout
+ * for await (const line of readeof('/var/log/app.log', 10, {
+ *   enabled: true,
+ *   signal: AbortSignal.timeout(30_000),
+ * })) {
+ *   console.log(line);
+ * }
+ * ```
  */
-bufferSize?: number): Promise<string>;
+export declare function readeof(filePath: string, maxLines: number, options: StreamOptions & {
+    enabled: true;
+}): AsyncGenerator<string, void, unknown>;
+export declare function readeof(filePath: string, maxLines: number, options?: StreamOptions & {
+    enabled: false;
+}): Promise<string>;
+export declare function readeof(filePath: string, maxLines: number, options?: ReadOptions): Promise<string>;

package/dist/index.js

@@ -33,7 +33,15 @@ __export(exports_src, {
 });
 module.exports = __toCommonJS(exports_src);
 var import_promises = require("node:fs/promises");
-async function readeof(filePath, maxLines, encoding = "utf8", bufferSize = 16 * 1024) {
+function readeof(filePath, maxLines, options) {
+  const encoding = options?.encoding ?? "utf8";
+  const bufferSize = options?.bufferSize ?? 16 * 1024;
+  if (options?.enabled) {
+    return readeofStream(filePath, maxLines, encoding, bufferSize, options);
+  }
+  return readeofOnce(filePath, maxLines, encoding, bufferSize);
+}
+async function readeofOnce(filePath, maxLines, encoding, bufferSize) {
   if (maxLines <= 0)
     return "";
   let fileHandle = null;
@@ -78,3 +86,103 @@ async function readeof(filePath, maxLines, encoding = "utf8", bufferSize = 16 *
     }
   }
 }
+async function* readeofStream(filePath, maxLines, encoding, bufferSize, options) {
+  const { pollInterval = 1000, signal } = options;
+  let fileHandle = null;
+  let position = 0;
+  let remainder = "";
+  try {
+    fileHandle = await import_promises.open(filePath, "r");
+    const stat = await fileHandle.stat();
+    if (stat.size > 0 && maxLines > 0) {
+      const buffer = Buffer.alloc(bufferSize);
+      let linesFound = 0;
+      let searchPosition = stat.size;
+      let startReadPos = stat.size;
+      while (searchPosition > 0 && linesFound < maxLines) {
+        const readLength = Math.min(bufferSize, searchPosition);
+        searchPosition -= readLength;
+        const result = await fileHandle.read(buffer, 0, readLength, searchPosition);
+        const bytesRead = result.bytesRead;
+        for (let i = bytesRead - 1;i >= 0; i--) {
+          if (buffer[i] === 10) {
+            if (searchPosition + i !== stat.size - 1 || linesFound > 0) {
+              linesFound++;
+            }
+            if (linesFound >= maxLines) {
+              startReadPos = searchPosition + i + 1;
+              break;
+            }
+          }
+        }
+      }
+      if (linesFound < maxLines) {
+        startReadPos = 0;
+      }
+      const lengthToRead = stat.size - startReadPos;
+      const resultBuffer = Buffer.alloc(lengthToRead);
+      await fileHandle.read(resultBuffer, 0, lengthToRead, startReadPos);
+      const content = resultBuffer.toString(encoding);
+      const lines = content.split(`
+`);
+      for (const line of lines) {
+        if (line.length > 0) {
+          yield line;
+        }
+      }
+    }
+    position = stat.size;
+    const streamBuffer = Buffer.alloc(bufferSize);
+    while (!signal?.aborted) {
+      try {
+        const currentStat = await fileHandle.stat();
+        if (currentStat.size < position) {
+          position = 0;
+          remainder = "";
+        }
+        if (currentStat.size > position) {
+          const bytesToRead = Math.min(bufferSize, currentStat.size - position);
+          const { bytesRead } = await fileHandle.read(streamBuffer, 0, bytesToRead, position);
+          if (bytesRead > 0) {
+            position += bytesRead;
+            const chunk = streamBuffer.subarray(0, bytesRead).toString(encoding);
+            const content = remainder + chunk;
+            const lines = content.split(`
+`);
+            remainder = lines.pop() ?? "";
+            for (const line of lines) {
+              if (line.length > 0) {
+                yield line;
+              }
+            }
+          }
+        }
+        await new Promise((resolve, reject) => {
+          const timeout = setTimeout(resolve, pollInterval);
+          signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            reject(new Error("Aborted"));
+          }, { once: true });
+        });
+      } catch (error) {
+        if (signal?.aborted)
+          break;
+        try {
+          await fileHandle.close();
+          fileHandle = await import_promises.open(filePath, "r");
+          position = 0;
+          remainder = "";
+        } catch {
+          throw error;
+        }
+      }
+    }
+    if (remainder.length > 0) {
+      yield remainder;
+    }
+  } finally {
+    if (fileHandle) {
+      await fileHandle.close();
+    }
+  }
+}

package/dist/index.mjs

@@ -1,6 +1,14 @@
 // src/index.ts
 import { open } from "node:fs/promises";
-async function readeof(filePath, maxLines, encoding = "utf8", bufferSize = 16 * 1024) {
+function readeof(filePath, maxLines, options) {
+  const encoding = options?.encoding ?? "utf8";
+  const bufferSize = options?.bufferSize ?? 16 * 1024;
+  if (options?.enabled) {
+    return readeofStream(filePath, maxLines, encoding, bufferSize, options);
+  }
+  return readeofOnce(filePath, maxLines, encoding, bufferSize);
+}
+async function readeofOnce(filePath, maxLines, encoding, bufferSize) {
   if (maxLines <= 0)
     return "";
   let fileHandle = null;
@@ -45,6 +53,106 @@ async function readeof(filePath, maxLines, encoding = "utf8", bufferSize = 16 *
     }
   }
 }
+async function* readeofStream(filePath, maxLines, encoding, bufferSize, options) {
+  const { pollInterval = 1000, signal } = options;
+  let fileHandle = null;
+  let position = 0;
+  let remainder = "";
+  try {
+    fileHandle = await open(filePath, "r");
+    const stat = await fileHandle.stat();
+    if (stat.size > 0 && maxLines > 0) {
+      const buffer = Buffer.alloc(bufferSize);
+      let linesFound = 0;
+      let searchPosition = stat.size;
+      let startReadPos = stat.size;
+      while (searchPosition > 0 && linesFound < maxLines) {
+        const readLength = Math.min(bufferSize, searchPosition);
+        searchPosition -= readLength;
+        const result = await fileHandle.read(buffer, 0, readLength, searchPosition);
+        const bytesRead = result.bytesRead;
+        for (let i = bytesRead - 1;i >= 0; i--) {
+          if (buffer[i] === 10) {
+            if (searchPosition + i !== stat.size - 1 || linesFound > 0) {
+              linesFound++;
+            }
+            if (linesFound >= maxLines) {
+              startReadPos = searchPosition + i + 1;
+              break;
+            }
+          }
+        }
+      }
+      if (linesFound < maxLines) {
+        startReadPos = 0;
+      }
+      const lengthToRead = stat.size - startReadPos;
+      const resultBuffer = Buffer.alloc(lengthToRead);
+      await fileHandle.read(resultBuffer, 0, lengthToRead, startReadPos);
+      const content = resultBuffer.toString(encoding);
+      const lines = content.split(`
+`);
+      for (const line of lines) {
+        if (line.length > 0) {
+          yield line;
+        }
+      }
+    }
+    position = stat.size;
+    const streamBuffer = Buffer.alloc(bufferSize);
+    while (!signal?.aborted) {
+      try {
+        const currentStat = await fileHandle.stat();
+        if (currentStat.size < position) {
+          position = 0;
+          remainder = "";
+        }
+        if (currentStat.size > position) {
+          const bytesToRead = Math.min(bufferSize, currentStat.size - position);
+          const { bytesRead } = await fileHandle.read(streamBuffer, 0, bytesToRead, position);
+          if (bytesRead > 0) {
+            position += bytesRead;
+            const chunk = streamBuffer.subarray(0, bytesRead).toString(encoding);
+            const content = remainder + chunk;
+            const lines = content.split(`
+`);
+            remainder = lines.pop() ?? "";
+            for (const line of lines) {
+              if (line.length > 0) {
+                yield line;
+              }
+            }
+          }
+        }
+        await new Promise((resolve, reject) => {
+          const timeout = setTimeout(resolve, pollInterval);
+          signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            reject(new Error("Aborted"));
+          }, { once: true });
+        });
+      } catch (error) {
+        if (signal?.aborted)
+          break;
+        try {
+          await fileHandle.close();
+          fileHandle = await open(filePath, "r");
+          position = 0;
+          remainder = "";
+        } catch {
+          throw error;
+        }
+      }
+    }
+    if (remainder.length > 0) {
+      yield remainder;
+    }
+  } finally {
+    if (fileHandle) {
+      await fileHandle.close();
+    }
+  }
+}
 export {
   readeof
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "readeof",
   "description": "A high-performance, memory-efficient library to read large files backward (line-by-line). Optimized for Node.js and Bun log parsing.",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",