errorxplain 1.0.0

package/README.md

@@ -0,0 +1,28 @@
+# errorxplain
+
+Intelligent Error Explainer CLI & Middleware for backend developers.
+
+## Installation
+
+```bash
+npm install -g errorxplain
+```
+
+## CLI Usage
+
+```bash
+errorxplain watch ./logs
+errorxplain explain "ECONNREFUSED 127.0.0.1:5432"
+```
+
+## Middleware Usage (Express)
+
+```js
+import express from "express";
+import { errorExplainer } from "errorxplain/lib/middleware.js";
+
+const app = express();
+app.use(errorExplainer());
+```
+
+Author: Shashank Neupane

package/bin/errx.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { watchLogs, explainError } from "../lib/engine.js";
+
+const args = process.argv.slice(2);
+
+if (!args.length) {
+  console.log("Usage: errorxplain [watch|explain] <path|error>");
+  process.exit(0);
+}
+
+const command = args[0];
+
+if (command === "watch") {
+  const logPath = args[1] || "./logs";
+  watchLogs(logPath);
+} else if (command === "explain") {
+  const errorText = args.slice(1).join(" ");
+  const explanation = explainError(errorText);
+  console.log("\nError Explanation:\n", explanation, "\n");
+} else {
+  console.log("Invalid command. Usage: errorxplain [watch|explain] <path|error>");
+}

package/lib/engine.js

@@ -0,0 +1,88 @@
+import fs from "fs";
+import path from "path";
+
+let rules = [];
+
+// Path to JSON rules
+const rulesFile = path.resolve("./lib/rules/rules.json");
+
+// Track last read position for each log file
+const filePositions = {};
+
+// Load rules from JSON and convert patterns to RegExp
+function loadRules() {
+  try {
+    const rawRules = JSON.parse(fs.readFileSync(rulesFile, "utf8"));
+    rules = rawRules.map(r => ({ ...r, pattern: new RegExp(r.pattern) }));
+    console.log(`Loaded ${rules.length} error rules`);
+  } catch (err) {
+    console.error("Failed to load rules.json:", err.message);
+  }
+}
+
+// Initial load
+loadRules();
+
+// Hot-reload rules whenever rules.json changes
+fs.watchFile(rulesFile, { interval: 1000 }, () => {
+  console.log("Detected change in rules.json, reloading rules...");
+  loadRules();
+});
+
+// Explain a single error
+export function explainError(errorText) {
+  const match = rules.find(r => r.pattern.test(errorText));
+  if (match) return match;
+  return { meaning: "Unknown error", fix: "Search documentation or logs" };
+}
+
+// Watch logs in real-time
+export function watchLogs(logDir) {
+  // Ensure folder exists
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+    console.log(`Created missing logs folder at ${logDir}`);
+  }
+
+  console.log(`Watching logs at ${logDir}...`);
+
+  fs.watch(logDir, (eventType, filename) => {
+    if (!filename) return;
+
+    const filePath = path.join(logDir, filename);
+
+    // Initialize last position
+    if (!filePositions[filePath]) filePositions[filePath] = 0;
+
+    fs.stat(filePath, (err, stats) => {
+      if (err) return console.error("Stat error:", err.message);
+
+      const prevSize = filePositions[filePath];
+      const newSize = stats.size;
+
+      // Only read new content
+      if (newSize > prevSize) {
+        const stream = fs.createReadStream(filePath, {
+          start: prevSize,
+          end: newSize
+        });
+
+        let data = "";
+        stream.on("data", chunk => (data += chunk));
+        stream.on("end", () => {
+          filePositions[filePath] = newSize;
+
+          const lines = data.split("\n").filter(line => line.trim() !== "");
+          lines.forEach(line => {
+            const explanation = explainError(line);
+            if (explanation.meaning !== "Unknown error") {
+              console.log("\nDetected Error:\n", explanation, "\n");
+            }
+          });
+        });
+
+        stream.on("error", e => console.error("Stream error:", e.message));
+      }
+    });
+  });
+}

package/lib/middleware.js

@@ -0,0 +1,13 @@
+import { explainError } from "./engine.js";
+
+// Express middleware to catch errors and explain them
+export function errorExplainer() {
+  return (err, req, res, next) => {
+    const explanation = explainError(err.message);
+    res.status(500).json({
+      error: err.message,
+      meaning: explanation.meaning,
+      fix: explanation.fix
+    });
+  };
+}

package/lib/rules/rules.json

@@ -0,0 +1,287 @@
+[
+  {
+    "pattern": "ECONNREFUSED",
+    "meaning": "Connection refused by target service",
+    "fix": "Start the service or check service address/port"
+  },
+  {
+    "pattern": "ETIMEDOUT",
+    "meaning": "Connection attempt timed out",
+    "fix": "Check network or increase timeout settings"
+  },
+  {
+    "pattern": "ECONNRESET",
+    "meaning": "Connection reset by peer",
+    "fix": "Retry connection or check remote service availability"
+  },
+  {
+    "pattern": "EADDRINUSE",
+    "meaning": "Address/port already in use",
+    "fix": "Use a different port or stop the process occupying it"
+  },
+  {
+    "pattern": "ENOENT",
+    "meaning": "No such file or directory",
+    "fix": "Ensure file/directory exists and path is correct"
+  },
+  {
+    "pattern": "EACCES",
+    "meaning": "Permission denied",
+    "fix": "Check file/directory permissions or use elevated access"
+  },
+  {
+    "pattern": "EPERM",
+    "meaning": "Operation not permitted",
+    "fix": "Adjust permissions or run with correct user privileges"
+  },
+  {
+    "pattern": "ENOTDIR",
+    "meaning": "Expected directory but found file",
+    "fix": "Use correct path or create required directory"
+  },
+  {
+    "pattern": "EISDIR",
+    "meaning": "Expected file but found directory",
+    "fix": "Use correct file path instead of directory"
+  },
+  {
+    "pattern": "ReferenceError",
+    "meaning": "Variable or reference not defined",
+    "fix": "Ensure variable is declared before use"
+  },
+  {
+    "pattern": "SyntaxError",
+    "meaning": "Code has invalid syntax",
+    "fix": "Fix code syntax errors before running"
+  },
+  {
+    "pattern": "TypeError",
+    "meaning": "Invalid type or undefined value used",
+    "fix": "Check variable types and null/undefined values"
+  },
+  {
+    "pattern": "RangeError",
+    "meaning": "Value out of allowed range",
+    "fix": "Check numeric values or loops for invalid limits"
+  },
+  {
+    "pattern": "URIError",
+    "meaning": "Incorrect use of encode/decode URI",
+    "fix": "Validate and encode URI parameters properly"
+  },
+  {
+    "pattern": "EvalError",
+    "meaning": "Issue with eval() function",
+    "fix": "Avoid using eval; use safer alternatives"
+  },
+  {
+    "pattern": "AggregateError",
+    "meaning": "Multiple errors aggregated",
+    "fix": "Inspect each error in the Aggregated error list"
+  },
+  {
+    "pattern": "ERR_MODULE_NOT_FOUND",
+    "meaning": "Module import failed",
+    "fix": "Check module name and installation"
+  },
+  {
+    "pattern": "ERR_NAPI_INVALID_DATAVIEW_ARGS",
+    "meaning": "Invalid DataView arguments",
+    "fix": "Verify DataView usage and parameters"
+  },
+  {
+    "pattern": "ECONNABORTED",
+    "meaning": "Connection aborted prematurely",
+    "fix": "Ensure response body is sent after write operations"
+  },
+  {
+    "pattern": "EHOSTUNREACH",
+    "meaning": "No route to host",
+    "fix": "Check network route and firewall settings"
+  },
+  {
+    "pattern": "ENOTFOUND",
+    "meaning": "DNS lookup failed or host not found",
+    "fix": "Verify hostname and network settings"
+  },
+  {
+    "pattern": "ERR_MULTIPLE_CALLBACK",
+    "meaning": "Callback called more than once",
+    "fix": "Ensure callback is called only once"
+  },
+  {
+    "pattern": "EPIPE",
+    "meaning": "Broken pipe or write on closed stream",
+    "fix": "Check stream states and request/response handling"
+  },
+  {
+    "pattern": "UnhandledPromiseRejection",
+    "meaning": "Promise rejected without a catch",
+    "fix": "Handle promise errors with .catch() or try/catch"
+  },
+  {
+    "pattern": "MemoryError",
+    "meaning": "Out of memory or heap exceeded",
+    "fix": "Optimize memory usage or increase limits"
+  },
+  {
+    "pattern": "ERR_ASSERTION",
+    "meaning": "Assertion failed",
+    "fix": "Check assertion conditions"
+  },
+  {
+    "pattern": "ValidationError",
+    "meaning": "Data validation failed",
+    "fix": "Validate inputs before processing"
+  },
+  {
+    "pattern": "MongoNetworkError",
+    "meaning": "MongoDB network connection issue",
+    "fix": "Check MongoDB service and network"
+  },
+  {
+    "pattern": "SequelizeConnectionError",
+    "meaning": "Database connection failed",
+    "fix": "Check DB credentials and server status"
+  },
+  {
+    "pattern": "SyntaxError: Unexpected token",
+    "meaning": "Invalid JSON or syntax",
+    "fix": "Fix JSON formatting or code syntax"
+  },
+  {
+    "pattern": "AxiosError",
+    "meaning": "HTTP request failed",
+    "fix": "Check URL, network, and request parameters"
+  },
+  {
+    "pattern": "TypeError: Cannot read property",
+    "meaning": "Attempted to access property of undefined",
+    "fix": "Check object initialization before use"
+  },
+  {
+    "pattern": "RangeError: Maximum call stack size exceeded",
+    "meaning": "Infinite recursion or deep nesting",
+    "fix": "Refactor recursive calls or loops"
+  },
+  {
+    "pattern": "EAI_AGAIN",
+    "meaning": "Temporary DNS failure",
+    "fix": "Retry DNS lookup or check network"
+  },
+  {
+    "pattern": "Heap out of memory",
+    "meaning": "Memory usage exceeded V8 heap limit",
+    "fix": "Increase memory limit or optimize code"
+  },
+  {
+    "pattern": "ERR_INVALID_ARG_TYPE",
+    "meaning": "Invalid argument type passed",
+    "fix": "Check function parameters"
+  },
+  {
+    "pattern": "ERR_HTTP_HEADERS_SENT",
+    "meaning": "Response headers already sent",
+    "fix": "Avoid sending multiple responses"
+  },
+  {
+    "pattern": "ERR_STREAM_DESTROYED",
+    "meaning": "Stream destroyed unexpectedly",
+    "fix": "Check stream lifecycle and error handling"
+  },
+  {
+    "pattern": "ERR_CHILD_PROCESS_STDIO_MAXBUFFER",
+    "meaning": "Child process output exceeded buffer limit",
+    "fix": "Increase maxBuffer or handle output incrementally"
+  },
+  {
+    "pattern": "ERR_HTTP_INVALID_HEADER_VALUE",
+    "meaning": "Invalid HTTP header value",
+    "fix": "Check header formatting and value types"
+  },
+  {
+    "pattern": "ERR_HTTP_INVALID_METHOD",
+    "meaning": "HTTP method invalid",
+    "fix": "Use valid HTTP methods: GET, POST, PUT, DELETE, etc."
+  },
+  {
+    "pattern": "ERR_HTTP_INVALID_STATUS_CODE",
+    "meaning": "HTTP status code is invalid",
+    "fix": "Use valid status codes (100–599)"
+  },
+  {
+    "pattern": "ERR_HTTP_INVALID_HEADER_NAME",
+    "meaning": "Invalid HTTP header name",
+    "fix": "Use valid header names"
+  },
+  {
+    "pattern": "ERR_HTTP2_STREAM_ERROR",
+    "meaning": "HTTP2 stream encountered an error",
+    "fix": "Check HTTP2 request/response handling"
+  },
+  {
+    "pattern": "ERR_HTTP2_SESSION_ERROR",
+    "meaning": "Error in HTTP2 session",
+    "fix": "Reset or recreate session"
+  },
+  {
+    "pattern": "ERR_TLS_CERT_ALTNAME_INVALID",
+    "meaning": "TLS certificate does not match hostname",
+    "fix": "Use correct certificate or ignore hostname check for testing"
+  },
+  {
+    "pattern": "ERR_TLS_HANDSHAKE",
+    "meaning": "TLS handshake failed",
+    "fix": "Check certificates and network"
+  },
+  {
+    "pattern": "ERR_STREAM_WRITE_AFTER_END",
+    "meaning": "Attempted to write to a stream after it ended",
+    "fix": "Ensure write happens before ending stream"
+  },
+  {
+    "pattern": "ERR_STREAM_ALREADY_FINISHED",
+    "meaning": "Stream already finished",
+    "fix": "Do not write or end again"
+  },
+  {
+    "pattern": "ERR_STREAM_CANNOT_PIPE",
+    "meaning": "Cannot pipe stream",
+    "fix": "Ensure source and destination are streams"
+  },
+  {
+    "pattern": "ERR_INVALID_OPT_VALUE",
+    "meaning": "Invalid option value provided",
+    "fix": "Check configuration or API option values"
+  },
+  {
+    "pattern": "ERR_REQUIRE_ESM",
+    "meaning": "Module must be imported using ESM syntax",
+    "fix": "Use import syntax or convert to ESM"
+  },
+  {
+    "pattern": "ERR_UNHANDLED_REJECTION",
+    "meaning": "Promise rejected without catch",
+    "fix": "Add catch() or try/catch around async code"
+  },
+  {
+    "pattern": "ERR_BUFFER_OUT_OF_BOUNDS",
+    "meaning": "Buffer access outside bounds",
+    "fix": "Validate buffer size and index"
+  },
+  {
+    "pattern": "ERR_INVALID_CHARACTER",
+    "meaning": "Unexpected character encountered",
+    "fix": "Check JSON, URL, or input encoding"
+  },
+  {
+    "pattern": "ERR_CHILD_PROCESS_KILLED",
+    "meaning": "Child process terminated unexpectedly",
+    "fix": "Check process lifecycle and signals"
+  },
+  {
+    "pattern": "UnhandledPromiseRejectionWarning",
+    "meaning": "Promise rejection not handled",
+    "fix": "Add catch handlers for promises"
+  }
+]

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "errorxplain",
+  "version": "1.0.0",
+  "description": "Intelligent Error Explainer CLI & Middleware for backend developers",
+  "main": "lib/engine.js",
+  "bin": {
+    "errorxplain": "./bin/errx.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node bin/errx.js"
+  },
+  "keywords": [
+    "error",
+    "debug",
+    "cli",
+    "middleware",
+    "backend",
+    "developer-tools",
+    "error-explainer",
+    "error-debugger",
+    "errorxplain"
+  ],
+  "author": "Shashank Neupane",
+  "license": "MIT",
+  "dependencies": {
+    "read-last-lines": "^1.8.0"
+  }
+}