intellerror 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DarshanBattula
+
+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,164 @@
+# 🧠 IntellError
+
+**Transform ugly JavaScript/Node.js stack traces into clean, readable, and actionable output. Designed for humans, not robots.**
+
+[![npm version](https://img.shields.io/npm/v/intellerror.svg)](https://www.npmjs.com/package/intellerror)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/darshan1005/IntellError)
+
+## ✨ Why IntellError?
+
+Standard error logs are noisy, cluttered with `node_modules`, and lack context. **IntellError** gives you the "Why" and "How to Fix" instantly.
+
+- ❌ **Clean Stack Traces**: Auto-hides Node.js internals and collapses `node_modules` noise.
+- 📍 **Smart Highlighting**: Identifies exactly where the error occurred in *your* code.
+- 💡 **Actionable Suggestions**: 50+ built-in rules for React, Express, Node.js, and Browser APIs.
+- 📸 **Code Snapshots**: Sees 3 lines of source code directly in your terminal (Node.js only).
+- 🔍 **One-Click Troubleshooting**: Instant search links for Google, StackOverflow, and GitHub.
+- 🌓 **Intelligent Warnings**: Not just for errors! Also formats `console.warn()` with suggestions.
+- 🌐 **Universal Styling**: Beautiful ANSI colors for Terminal and native `%c` CSS for Browsers.
+- 📢 **Team Integration**: Push critical dev errors directly to **Slack** or **Discord** webhooks.
+
+---
+
+## 🚀 Quick Start (Zero-Config)
+
+You can set up `IntellError` globally to catch all unhandled issues across your entire project with just one line.
+
+### For Browser (React, Vite, Next.js)
+Add this at the very top of your entry file (e.g., `main.tsx` or `index.tsx`):
+
+```typescript
+import 'intellerror/register';
+```
+
+### For Node.js (CLI)
+Run your application with the register hook:
+
+```bash
+# ESM (Node.js 20+)
+node --import intellerror/register index.js
+
+# CommonJS
+node -r intellerror/register index.js
+```
+
+---
+
+## ⚙️ Configuration & Customization
+
+Fine-tune the output or add your own project-specific intelligence.
+
+```typescript
+import { setupConfig, registerRule } from 'intellerror';
+
+setupConfig({
+  showNodeModules: false,    // Hide noise?
+  showNodeInternals: false,  // Hide node internals?
+  suggestionsEnabled: true,  // Show the "💡 Suggestions"?
+  interceptWarnings: true,   // Also format console.warn?
+  showSearchLinks: true,     // Show troubleshooting links?
+  webhookUrl: 'https://...'  // Push to Slack/Discord?
+});
+
+// Add your own "Thinking" to the engine
+registerRule({
+  match: (err) => err.message.includes("AUTH_FAILED"),
+  message: "Authentication failure detected.",
+  fix: "Ensure your .env contains a valid API_KEY.",
+  description: "The request was rejected by the server due to invalid credentials."
+});
+```
+
+---
+
+## 📖 Manual Usage
+
+If you prefer to format specific errors manually in your `try-catch` blocks:
+
+### Terminal / Node.js
+```typescript
+import { formatError, formatWarning } from 'intellerror';
+
+try {
+  // your code...
+} catch (err) {
+  console.log(formatError(err)); 
+}
+```
+
+### Browser Console (React/Vite)
+```typescript
+import { formatErrorBrowser } from 'intellerror';
+
+try {
+  // your React code...
+} catch (err) {
+  // Note: MUST use the spread operator (...) for CSS styling
+  console.log(...formatErrorBrowser(err));
+}
+```
+
+---
+
+## 🚅 Framework Integration
+
+### Express Middleware
+```typescript
+import express from 'express';
+import { errorFormatter } from 'intellerror';
+
+const app = express();
+// ... routes ...
+
+// Add at the very end of your middleware stack
+app.use(errorFormatter());
+```
+
+---
+
+## 🎮 Demos & Examples
+
+We've included several ready-to-run examples in the `examples/` directory:
+
+- **Basic Error**: `npm run example:basic`
+- **Async Errors**: `npm run example:async`
+- **Custom Errors**: `npm run example:custom`
+- **Run All**: `npm run examples:all`
+
+### Run Unit Tests
+```bash
+npm run test:unit
+```
+
+---
+
+## Example Output (Terminal)
+
+```text
+  TypeError  Cannot read properties of undefined (reading 'name')
+
+📍 Location:
+src/index.ts:12:15   ← YOUR CODE
+
+ > 11 |   const user = await fetchUser();
+ > 12 |   console.log(user.name);
+ > 13 | }
+
+💡 Suggestions:
+• Accessing property on undefined object.
+  Fix: Use optional chaining like 'obj?.prop' or ensure the object is initialized.
+
+🔍 Troubleshoot:
+• Google: https://google.com/...
+• GitHub: https://github.com/...
+
+📦 Stack:
+→ src/index.ts:12:15
+→ src/server.ts:45:10
+(4 node internals and 2 node_modules hidden)
+```
+
+## 📄 License
+
+ISC © [darshan1005](https://github.com/darshan1005)

package/dist/formatter/index.d.ts

@@ -0,0 +1 @@
+export declare function formatError(error: Error | unknown): string;

package/dist/index.cjs

@@ -0,0 +1,174 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  errorFormatter: () => errorFormatter,
+  formatError: () => formatError,
+  parseStack: () => parseStack
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/formatter/index.ts
+var import_chalk = __toESM(require("chalk"), 1);
+
+// src/parser/index.ts
+var stackTraceParser = __toESM(require("stacktrace-parser"), 1);
+function parseStack(error) {
+  if (!error.stack) return [];
+  const parsed = stackTraceParser.parse(error.stack);
+  return parsed.map((frame) => {
+    const file = frame.file || "";
+    const isNodeInternal = file.startsWith("node:") || file.startsWith("internal/") || !file.includes("/") && !file.includes("\\");
+    const isNodeModule = file.includes("node_modules");
+    return {
+      file: frame.file,
+      methodName: frame.methodName || "<unknown>",
+      lineNumber: frame.lineNumber,
+      column: frame.column,
+      isNodeInternal: Boolean(isNodeInternal),
+      isNodeModule: Boolean(isNodeModule)
+    };
+  });
+}
+
+// src/suggestions/rules.ts
+var rules = [
+  {
+    match: (err) => err.message.includes("Cannot read properties of undefined (reading '") || err.message.includes("is not defined"),
+    message: "Accessing property on undefined/not defined object.",
+    fix: "User optional chaining like 'obj?.prop' or ensure the object is initialized.",
+    description: "You are trying to read a property from a variable that currently holds an undefined value."
+  },
+  {
+    match: (err) => err instanceof SyntaxError && err.message.includes("Unexpected token"),
+    message: "JSON Parsing or Code Syntax error.",
+    fix: "Check your JSON string for trailing commas, proper quotes, or syntax issues in your code.",
+    description: "The engine encountered something it didn't expect while parsing."
+  },
+  {
+    match: (err) => err.message.includes("is not a function"),
+    message: "Attempted to call a non-function value.",
+    fix: "Ensure that you're calling a property that is actually a function.",
+    description: "You probably tried to execute something that is a string, number, or object as if it were a function."
+  }
+];
+
+// src/suggestions/index.ts
+function getSuggestions(error) {
+  return rules.filter((rule) => rule.match(error));
+}
+
+// src/formatter/index.ts
+function formatError(error) {
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+  const stackFrames = parseStack(error);
+  const userFrame = stackFrames.find((frame) => !frame.isNodeInternal && !frame.isNodeModule);
+  const errorType = error.constructor.name || "Error";
+  const typeLabel = import_chalk.default.bgRed.white(` ${errorType} `);
+  let output = `
+${typeLabel} ${import_chalk.default.red(error.message)}
+
+`;
+  if (userFrame && userFrame.file) {
+    output += `${import_chalk.default.bold("\u{1F4CD} Location:")}
+`;
+    output += `${import_chalk.default.cyan(userFrame.file)}:${import_chalk.default.yellow(userFrame.lineNumber)}:${import_chalk.default.yellow(userFrame.column)}   ${import_chalk.default.gray("\u2190 YOUR CODE")}
+
+`;
+  }
+  const suggestions = getSuggestions(error);
+  if (suggestions.length > 0) {
+    output += `${import_chalk.default.bold("\u{1F4A1} Suggestions:")}
+`;
+    for (const suggestion of suggestions) {
+      output += `\u2022 ${import_chalk.default.green(suggestion.message)}
+`;
+      if (suggestion.fix) {
+        output += `  ${import_chalk.default.dim("Fix: " + suggestion.fix)}
+`;
+      }
+    }
+    output += `
+`;
+  }
+  output += `${import_chalk.default.bold("\u{1F4E6} Stack:")}
+`;
+  let hiddenInternalsCount = 0;
+  let hiddenModulesCount = 0;
+  for (const frame of stackFrames) {
+    if (frame.isNodeInternal) {
+      hiddenInternalsCount++;
+      continue;
+    }
+    if (frame.isNodeModule) {
+      hiddenModulesCount++;
+      continue;
+    }
+    const fileStr = frame.file ? `${import_chalk.default.cyan(frame.file)}:${import_chalk.default.yellow(frame.lineNumber)}:${import_chalk.default.yellow(frame.column)}` : import_chalk.default.gray("<unknown>");
+    output += `\u2192 ${fileStr}
+`;
+  }
+  if (hiddenModulesCount > 0 || hiddenInternalsCount > 0) {
+    const hiddenMessages = [];
+    if (hiddenModulesCount > 0) hiddenMessages.push(`${hiddenModulesCount} node_modules`);
+    if (hiddenInternalsCount > 0) hiddenMessages.push(`${hiddenInternalsCount} node internals`);
+    output += import_chalk.default.dim(`(${hiddenMessages.join(" and ")} hidden)
+`);
+  }
+  return output;
+}
+
+// src/middleware/index.ts
+function errorFormatter() {
+  return (err, _req, res, _next) => {
+    const formatted = formatError(err);
+    console.error(formatted);
+    if (!res.headersSent) {
+      res.status(err.status || 500).json({
+        error: {
+          name: err.name,
+          message: err.message
+          // We don't send the full formatted error to the client for security, 
+          // but we provide the basic info.
+        }
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  errorFormatter,
+  formatError,
+  parseStack
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/formatter/index.ts","../src/parser/index.ts","../src/suggestions/rules.ts","../src/suggestions/index.ts","../src/middleware/index.ts"],"sourcesContent":["export { formatError } from './formatter/index.js';\nexport { parseStack } from './parser/index.js';\nexport { errorFormatter } from './middleware/index.js';\n","import chalk from 'chalk';\nimport { parseStack } from '../parser/index.js';\nimport { getSuggestions } from '../suggestions/index.js';\n\nexport function formatError(error: Error | unknown): string {\n  if (!(error instanceof Error)) {\n    return String(error);\n  }\n\n  const stackFrames = parseStack(error);\n  \n  // Find first user frame that is not node internal or node_modules\n  const userFrame = stackFrames.find(frame => !frame.isNodeInternal && !frame.isNodeModule);\n\n  const errorType = error.constructor.name || 'Error';\n  const typeLabel = chalk.bgRed.white(` ${errorType} `);\n  let output = `\\n${typeLabel} ${chalk.red(error.message)}\\n\\n`;\n\n  if (userFrame && userFrame.file) {\n    output += `${chalk.bold('📍 Location:')}\\n`;\n    output += `${chalk.cyan(userFrame.file)}:${chalk.yellow(userFrame.lineNumber)}:${chalk.yellow(userFrame.column)}   ${chalk.gray('← YOUR CODE')}\\n\\n`;\n  }\n\n  const suggestions = getSuggestions(error);\n  if (suggestions.length > 0) {\n    output += `${chalk.bold('💡 Suggestions:')}\\n`;\n    for (const suggestion of suggestions) {\n      output += `• ${chalk.green(suggestion.message)}\\n`;\n      if (suggestion.fix) {\n          output += `  ${chalk.dim('Fix: ' + suggestion.fix)}\\n`;\n      }\n    }\n    output += `\\n`;\n  }\n\n  output += `${chalk.bold('📦 Stack:')}\\n`;\n  \n  let hiddenInternalsCount = 0;\n  let hiddenModulesCount = 0;\n\n  for (const frame of stackFrames) {\n    if (frame.isNodeInternal) {\n      hiddenInternalsCount++;\n      continue;\n    }\n    \n    if (frame.isNodeModule) {\n      hiddenModulesCount++;\n      continue; \n    }\n    \n    const fileStr = frame.file \n      ? `${chalk.cyan(frame.file)}:${chalk.yellow(frame.lineNumber)}:${chalk.yellow(frame.column)}` \n      : chalk.gray('<unknown>');\n      \n    output += `→ ${fileStr}\\n`;\n  }\n\n  if (hiddenModulesCount > 0 || hiddenInternalsCount > 0) {\n    const hiddenMessages = [];\n    if (hiddenModulesCount > 0) hiddenMessages.push(`${hiddenModulesCount} node_modules`);\n    if (hiddenInternalsCount > 0) hiddenMessages.push(`${hiddenInternalsCount} node internals`);\n    output += chalk.dim(`(${hiddenMessages.join(' and ')} hidden)\\n`);\n  }\n\n  return output;\n}\n","import * as stackTraceParser from 'stacktrace-parser';\n\nexport interface ParsedStackFrame {\n  file: string | null;\n  methodName: string;\n  lineNumber: number | null;\n  column: number | null;\n  isNodeInternal: boolean;\n  isNodeModule: boolean;\n}\n\nexport function parseStack(error: Error): ParsedStackFrame[] {\n  if (!error.stack) return [];\n  \n  const parsed = stackTraceParser.parse(error.stack);\n  \n  return parsed.map(frame => {\n    const file = frame.file || '';\n    \n    // Check if it's a built-in node module or internal\n    // e.g. node:internal/... or just internal/... or events.js\n    const isNodeInternal = \n      file.startsWith('node:') || \n      file.startsWith('internal/') ||\n      !file.includes('/') && !file.includes('\\\\'); // typically a core module if no path separators\n      \n    const isNodeModule = file.includes('node_modules');\n\n    return {\n      file: frame.file,\n      methodName: frame.methodName || '<unknown>',\n      lineNumber: frame.lineNumber,\n      column: frame.column,\n      isNodeInternal: Boolean(isNodeInternal),\n      isNodeModule: Boolean(isNodeModule)\n    };\n  });\n}\n","export interface SuggesionRule {\n  match: (error: Error) => boolean;\n  message: string;\n  fix?: string;\n  description?: string;\n}\n\nexport const rules: SuggesionRule[] = [\n  {\n    match: (err) => err.message.includes(\"Cannot read properties of undefined (reading '\") || err.message.includes(\"is not defined\"),\n    message: \"Accessing property on undefined/not defined object.\",\n    fix: \"User optional chaining like 'obj?.prop' or ensure the object is initialized.\",\n    description: \"You are trying to read a property from a variable that currently holds an undefined value.\"\n  },\n  {\n      match: (err) => err instanceof SyntaxError && err.message.includes(\"Unexpected token\"),\n      message: \"JSON Parsing or Code Syntax error.\",\n      fix: \"Check your JSON string for trailing commas, proper quotes, or syntax issues in your code.\",\n      description: \"The engine encountered something it didn't expect while parsing.\"\n  },\n  {\n      match: (err) => err.message.includes(\"is not a function\"),\n      message: \"Attempted to call a non-function value.\",\n      fix: \"Ensure that you're calling a property that is actually a function.\",\n      description: \"You probably tried to execute something that is a string, number, or object as if it were a function.\"\n  }\n];\n","import { rules, SuggesionRule } from './rules.js';\n\nexport function getSuggestions(error: Error): SuggesionRule[] {\n    return rules.filter(rule => rule.match(error));\n}\n","import { formatError } from '../formatter/index.js';\nimport type { Request, Response, NextFunction } from 'express';\n\nexport function errorFormatter() {\n  return (err: any, _req: Request, res: Response, _next: NextFunction) => {\n    const formatted = formatError(err);\n    \n    // Log to console with nice formatting\n    console.error(formatted);\n\n    // If headers not sent, send a standard error response\n    if (!res.headersSent) {\n      res.status(err.status || 500).json({\n        error: {\n          name: err.name,\n          message: err.message,\n          // We don't send the full formatted error to the client for security, \n          // but we provide the basic info.\n        },\n      });\n    }\n  };\n}\n"],"mappings":"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","names":["chalk"]}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { formatError } from './formatter/index.js';
+export { parseStack } from './parser/index.js';
+export { errorFormatter } from './middleware/index.js';

package/dist/index.js

@@ -0,0 +1,135 @@
+// src/formatter/index.ts
+import chalk from "chalk";
+
+// src/parser/index.ts
+import * as stackTraceParser from "stacktrace-parser";
+function parseStack(error) {
+  if (!error.stack) return [];
+  const parsed = stackTraceParser.parse(error.stack);
+  return parsed.map((frame) => {
+    const file = frame.file || "";
+    const isNodeInternal = file.startsWith("node:") || file.startsWith("internal/") || !file.includes("/") && !file.includes("\\");
+    const isNodeModule = file.includes("node_modules");
+    return {
+      file: frame.file,
+      methodName: frame.methodName || "<unknown>",
+      lineNumber: frame.lineNumber,
+      column: frame.column,
+      isNodeInternal: Boolean(isNodeInternal),
+      isNodeModule: Boolean(isNodeModule)
+    };
+  });
+}
+
+// src/suggestions/rules.ts
+var rules = [
+  {
+    match: (err) => err.message.includes("Cannot read properties of undefined (reading '") || err.message.includes("is not defined"),
+    message: "Accessing property on undefined/not defined object.",
+    fix: "User optional chaining like 'obj?.prop' or ensure the object is initialized.",
+    description: "You are trying to read a property from a variable that currently holds an undefined value."
+  },
+  {
+    match: (err) => err instanceof SyntaxError && err.message.includes("Unexpected token"),
+    message: "JSON Parsing or Code Syntax error.",
+    fix: "Check your JSON string for trailing commas, proper quotes, or syntax issues in your code.",
+    description: "The engine encountered something it didn't expect while parsing."
+  },
+  {
+    match: (err) => err.message.includes("is not a function"),
+    message: "Attempted to call a non-function value.",
+    fix: "Ensure that you're calling a property that is actually a function.",
+    description: "You probably tried to execute something that is a string, number, or object as if it were a function."
+  }
+];
+
+// src/suggestions/index.ts
+function getSuggestions(error) {
+  return rules.filter((rule) => rule.match(error));
+}
+
+// src/formatter/index.ts
+function formatError(error) {
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+  const stackFrames = parseStack(error);
+  const userFrame = stackFrames.find((frame) => !frame.isNodeInternal && !frame.isNodeModule);
+  const errorType = error.constructor.name || "Error";
+  const typeLabel = chalk.bgRed.white(` ${errorType} `);
+  let output = `
+${typeLabel} ${chalk.red(error.message)}
+
+`;
+  if (userFrame && userFrame.file) {
+    output += `${chalk.bold("\u{1F4CD} Location:")}
+`;
+    output += `${chalk.cyan(userFrame.file)}:${chalk.yellow(userFrame.lineNumber)}:${chalk.yellow(userFrame.column)}   ${chalk.gray("\u2190 YOUR CODE")}
+
+`;
+  }
+  const suggestions = getSuggestions(error);
+  if (suggestions.length > 0) {
+    output += `${chalk.bold("\u{1F4A1} Suggestions:")}
+`;
+    for (const suggestion of suggestions) {
+      output += `\u2022 ${chalk.green(suggestion.message)}
+`;
+      if (suggestion.fix) {
+        output += `  ${chalk.dim("Fix: " + suggestion.fix)}
+`;
+      }
+    }
+    output += `
+`;
+  }
+  output += `${chalk.bold("\u{1F4E6} Stack:")}
+`;
+  let hiddenInternalsCount = 0;
+  let hiddenModulesCount = 0;
+  for (const frame of stackFrames) {
+    if (frame.isNodeInternal) {
+      hiddenInternalsCount++;
+      continue;
+    }
+    if (frame.isNodeModule) {
+      hiddenModulesCount++;
+      continue;
+    }
+    const fileStr = frame.file ? `${chalk.cyan(frame.file)}:${chalk.yellow(frame.lineNumber)}:${chalk.yellow(frame.column)}` : chalk.gray("<unknown>");
+    output += `\u2192 ${fileStr}
+`;
+  }
+  if (hiddenModulesCount > 0 || hiddenInternalsCount > 0) {
+    const hiddenMessages = [];
+    if (hiddenModulesCount > 0) hiddenMessages.push(`${hiddenModulesCount} node_modules`);
+    if (hiddenInternalsCount > 0) hiddenMessages.push(`${hiddenInternalsCount} node internals`);
+    output += chalk.dim(`(${hiddenMessages.join(" and ")} hidden)
+`);
+  }
+  return output;
+}
+
+// src/middleware/index.ts
+function errorFormatter() {
+  return (err, _req, res, _next) => {
+    const formatted = formatError(err);
+    console.error(formatted);
+    if (!res.headersSent) {
+      res.status(err.status || 500).json({
+        error: {
+          name: err.name,
+          message: err.message
+          // We don't send the full formatted error to the client for security, 
+          // but we provide the basic info.
+        }
+      });
+    }
+  };
+}
+export {
+  errorFormatter,
+  formatError,
+  parseStack
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/formatter/index.ts","../src/parser/index.ts","../src/suggestions/rules.ts","../src/suggestions/index.ts","../src/middleware/index.ts"],"sourcesContent":["import chalk from 'chalk';\nimport { parseStack } from '../parser/index.js';\nimport { getSuggestions } from '../suggestions/index.js';\n\nexport function formatError(error: Error | unknown): string {\n  if (!(error instanceof Error)) {\n    return String(error);\n  }\n\n  const stackFrames = parseStack(error);\n  \n  // Find first user frame that is not node internal or node_modules\n  const userFrame = stackFrames.find(frame => !frame.isNodeInternal && !frame.isNodeModule);\n\n  const errorType = error.constructor.name || 'Error';\n  const typeLabel = chalk.bgRed.white(` ${errorType} `);\n  let output = `\\n${typeLabel} ${chalk.red(error.message)}\\n\\n`;\n\n  if (userFrame && userFrame.file) {\n    output += `${chalk.bold('📍 Location:')}\\n`;\n    output += `${chalk.cyan(userFrame.file)}:${chalk.yellow(userFrame.lineNumber)}:${chalk.yellow(userFrame.column)}   ${chalk.gray('← YOUR CODE')}\\n\\n`;\n  }\n\n  const suggestions = getSuggestions(error);\n  if (suggestions.length > 0) {\n    output += `${chalk.bold('💡 Suggestions:')}\\n`;\n    for (const suggestion of suggestions) {\n      output += `• ${chalk.green(suggestion.message)}\\n`;\n      if (suggestion.fix) {\n          output += `  ${chalk.dim('Fix: ' + suggestion.fix)}\\n`;\n      }\n    }\n    output += `\\n`;\n  }\n\n  output += `${chalk.bold('📦 Stack:')}\\n`;\n  \n  let hiddenInternalsCount = 0;\n  let hiddenModulesCount = 0;\n\n  for (const frame of stackFrames) {\n    if (frame.isNodeInternal) {\n      hiddenInternalsCount++;\n      continue;\n    }\n    \n    if (frame.isNodeModule) {\n      hiddenModulesCount++;\n      continue; \n    }\n    \n    const fileStr = frame.file \n      ? `${chalk.cyan(frame.file)}:${chalk.yellow(frame.lineNumber)}:${chalk.yellow(frame.column)}` \n      : chalk.gray('<unknown>');\n      \n    output += `→ ${fileStr}\\n`;\n  }\n\n  if (hiddenModulesCount > 0 || hiddenInternalsCount > 0) {\n    const hiddenMessages = [];\n    if (hiddenModulesCount > 0) hiddenMessages.push(`${hiddenModulesCount} node_modules`);\n    if (hiddenInternalsCount > 0) hiddenMessages.push(`${hiddenInternalsCount} node internals`);\n    output += chalk.dim(`(${hiddenMessages.join(' and ')} hidden)\\n`);\n  }\n\n  return output;\n}\n","import * as stackTraceParser from 'stacktrace-parser';\n\nexport interface ParsedStackFrame {\n  file: string | null;\n  methodName: string;\n  lineNumber: number | null;\n  column: number | null;\n  isNodeInternal: boolean;\n  isNodeModule: boolean;\n}\n\nexport function parseStack(error: Error): ParsedStackFrame[] {\n  if (!error.stack) return [];\n  \n  const parsed = stackTraceParser.parse(error.stack);\n  \n  return parsed.map(frame => {\n    const file = frame.file || '';\n    \n    // Check if it's a built-in node module or internal\n    // e.g. node:internal/... or just internal/... or events.js\n    const isNodeInternal = \n      file.startsWith('node:') || \n      file.startsWith('internal/') ||\n      !file.includes('/') && !file.includes('\\\\'); // typically a core module if no path separators\n      \n    const isNodeModule = file.includes('node_modules');\n\n    return {\n      file: frame.file,\n      methodName: frame.methodName || '<unknown>',\n      lineNumber: frame.lineNumber,\n      column: frame.column,\n      isNodeInternal: Boolean(isNodeInternal),\n      isNodeModule: Boolean(isNodeModule)\n    };\n  });\n}\n","export interface SuggesionRule {\n  match: (error: Error) => boolean;\n  message: string;\n  fix?: string;\n  description?: string;\n}\n\nexport const rules: SuggesionRule[] = [\n  {\n    match: (err) => err.message.includes(\"Cannot read properties of undefined (reading '\") || err.message.includes(\"is not defined\"),\n    message: \"Accessing property on undefined/not defined object.\",\n    fix: \"User optional chaining like 'obj?.prop' or ensure the object is initialized.\",\n    description: \"You are trying to read a property from a variable that currently holds an undefined value.\"\n  },\n  {\n      match: (err) => err instanceof SyntaxError && err.message.includes(\"Unexpected token\"),\n      message: \"JSON Parsing or Code Syntax error.\",\n      fix: \"Check your JSON string for trailing commas, proper quotes, or syntax issues in your code.\",\n      description: \"The engine encountered something it didn't expect while parsing.\"\n  },\n  {\n      match: (err) => err.message.includes(\"is not a function\"),\n      message: \"Attempted to call a non-function value.\",\n      fix: \"Ensure that you're calling a property that is actually a function.\",\n      description: \"You probably tried to execute something that is a string, number, or object as if it were a function.\"\n  }\n];\n","import { rules, SuggesionRule } from './rules.js';\n\nexport function getSuggestions(error: Error): SuggesionRule[] {\n    return rules.filter(rule => rule.match(error));\n}\n","import { formatError } from '../formatter/index.js';\nimport type { Request, Response, NextFunction } from 'express';\n\nexport function errorFormatter() {\n  return (err: any, _req: Request, res: Response, _next: NextFunction) => {\n    const formatted = formatError(err);\n    \n    // Log to console with nice formatting\n    console.error(formatted);\n\n    // If headers not sent, send a standard error response\n    if (!res.headersSent) {\n      res.status(err.status || 500).json({\n        error: {\n          name: err.name,\n          message: err.message,\n          // We don't send the full formatted error to the client for security, \n          // but we provide the basic info.\n        },\n      });\n    }\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/middleware/index.d.ts

@@ -0,0 +1,2 @@
+import type { Request, Response, NextFunction } from 'express';
+export declare function errorFormatter(): (err: any, _req: Request, res: Response, _next: NextFunction) => void;

package/dist/parser/index.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedStackFrame {
+    file: string | null;
+    methodName: string;
+    lineNumber: number | null;
+    column: number | null;
+    isNodeInternal: boolean;
+    isNodeModule: boolean;
+}
+export declare function parseStack(error: Error): ParsedStackFrame[];