readeof 0.0.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashary Vermaysha
+
+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.

package/README.md

@@ -0,0 +1,95 @@
+# ReadEOF
+
+A high-performance, memory-efficient library to read large files backward (line-by-line). Zero dependencies.
+
+## Features
+
+- Fast file reading from the end without loading entire file into memory
+- Memory efficient using configurable buffer sizes
+- Supports various encodings
+
+## Installation
+
+```bash
+npm install readeof
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { readeof } from 'readeof';
+
+// Read last 10 lines from log file
+const lastLines = await readeof('/var/log/app.log', 10);
+console.log(lastLines);
+```
+
+### Reading Recent Logs
+
+```typescript
+import { readeof } from 'readeof';
+
+// Read last 50 lines for debugging
+const recentLogs = await readeof('./app.log', 50);
+console.log(recentLogs);
+```
+
+### Custom Encoding
+
+```typescript
+import { readeof } from 'readeof';
+
+// Read file with latin1 encoding
+const content = await readeof('./data.txt', 20, 'latin1');
+```
+
+### Custom Buffer Size
+
+```typescript
+import { readeof } from 'readeof';
+
+// Use 64KB buffer for very large files
+const content = await readeof('./huge-log.log', 100, 'utf8', 64 * 1024);
+```
+
+### Real-time Log Monitoring
+
+```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);
+}
+
+monitorLog('/var/log/application.log');
+```
+
+### Error Analysis
+
+```typescript
+import { readeof } from 'readeof';
+
+async function findRecentErrors(logPath: string) {
+  const recentLogs = await readeof(logPath, 1000);
+  const errors = recentLogs
+    .split('\n')
+    .filter(line => line.includes('ERROR'));
+  
+  console.log(`Found ${errors.length} errors in last 1000 lines`);
+}
+```
+
+## License
+
+See [LICENSE](LICENSE) file for details.
+
+## Author
+
+Ashary Vermaysha (<vermaysha@gmail.com>)

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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
+ */
+export declare function readeof(
+/**
+ * Path to the file to read from
+ */
+filePath: string, 
+/**
+ * Total lines to read from the end of the file
+ */
+maxLines: number, 
+/**
+ * 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): Promise<string>;

package/dist/index.js

@@ -0,0 +1,81 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  readeof: () => readeof
+});
+module.exports = __toCommonJS(exports_src);
+var import_promises = require("node:fs/promises");
+async function readeof(filePath, maxLines, encoding = "utf8", bufferSize = 16 * 1024) {
+  if (maxLines <= 0)
+    return "";
+  let fileHandle = null;
+  try {
+    fileHandle = await import_promises.open(filePath, "r");
+    const stat = await fileHandle.stat();
+    if (stat.size === 0)
+      return "";
+    const buffer = Buffer.alloc(bufferSize);
+    let linesFound = 0;
+    let position = stat.size;
+    let startReadPos = stat.size;
+    while (position > 0 && linesFound < maxLines) {
+      const readLength = Math.min(bufferSize, position);
+      position -= readLength;
+      const result = await fileHandle.read(buffer, 0, readLength, position);
+      const bytesRead = result.bytesRead;
+      for (let i = bytesRead - 1;i >= 0; i--) {
+        if (buffer[i] === 10) {
+          if (position + i !== stat.size - 1 || linesFound > 0) {
+            linesFound++;
+          }
+          if (linesFound >= maxLines) {
+            startReadPos = position + 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);
+    return resultBuffer.toString(encoding);
+  } catch (error) {
+    throw error;
+  } finally {
+    console.log("Closing file handle");
+    if (fileHandle) {
+      await fileHandle.close();
+    }
+  }
+}

package/dist/index.mjs

@@ -0,0 +1,51 @@
+// src/index.ts
+import { open } from "node:fs/promises";
+async function readeof(filePath, maxLines, encoding = "utf8", bufferSize = 16 * 1024) {
+  if (maxLines <= 0)
+    return "";
+  let fileHandle = null;
+  try {
+    fileHandle = await open(filePath, "r");
+    const stat = await fileHandle.stat();
+    if (stat.size === 0)
+      return "";
+    const buffer = Buffer.alloc(bufferSize);
+    let linesFound = 0;
+    let position = stat.size;
+    let startReadPos = stat.size;
+    while (position > 0 && linesFound < maxLines) {
+      const readLength = Math.min(bufferSize, position);
+      position -= readLength;
+      const result = await fileHandle.read(buffer, 0, readLength, position);
+      const bytesRead = result.bytesRead;
+      for (let i = bytesRead - 1;i >= 0; i--) {
+        if (buffer[i] === 10) {
+          if (position + i !== stat.size - 1 || linesFound > 0) {
+            linesFound++;
+          }
+          if (linesFound >= maxLines) {
+            startReadPos = position + 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);
+    return resultBuffer.toString(encoding);
+  } catch (error) {
+    throw error;
+  } finally {
+    console.log("Closing file handle");
+    if (fileHandle) {
+      await fileHandle.close();
+    }
+  }
+}
+export {
+  readeof
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "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": "0.0.1-beta.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "bundle": "bun run ./scripts/build.ts && tsc ./src/index.ts --declaration --emitDeclarationOnly --outDir dist",
+    "benchmark": "bun run ./scripts/benchmark.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "mitata": "^1.0.34"
+  },
+  "keywords": [
+    "file-system",
+    "reverse",
+    "backward",
+    "tail",
+    "read-reverse",
+    "line-reader",
+    "log-parser",
+    "large-files",
+    "read-last-lines"
+  ],
+  "author": {
+    "name": "Ashary Vermaysha",
+    "email": "vermaysha@gmail.com",
+    "url": "https://github.com/vermaysha"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vermaysha/readeof.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vermaysha/readeof/issues"
+  },
+  "homepage": "https://github.com/vermaysha/readeof#readme"
+}