Skip to content

Commit a305ede

Browse files
author
Pangea 3
committed
fix: feat: enhance error database with common runtime errors (fixes #49)
1 parent 8c54bc5 commit a305ede

2 files changed

Lines changed: 41 additions & 206 deletions

File tree

‎README.md‎

Lines changed: 15 additions & 206 deletions
Original file line numberDiff line numberDiff line change
@@ -1,209 +1,18 @@
11
# ErrLens 🔍
22
> **Translate cryptic JavaScript errors into human-readable solutions instantly.**
33
4-
<p align="center">
5-
<img src="assets/errlens.png" width="500">
6-
</p>
7-
</br>
8-
</br>
9-
10-
<p align="center">
11-
<!-- GitHub Badges -->
12-
<img src="https://img.shields.io/github/stars/BeyteFlow/errlens?style=for-the-badge" alt="GitHub stars">
13-
<img src="https://img.shields.io/github/forks/BeyteFlow/errlens?style=for-the-badge" alt="GitHub forks">
14-
<img src="https://img.shields.io/github/issues/BeyteFlow/errlens?style=for-the-badge" alt="GitHub issues">
15-
<img src="https://img.shields.io/github/license/BeyteFlow/errlens?style=for-the-badge" alt="GitHub license">
16-
<img src="https://img.shields.io/github/issues-pr/BeyteFlow/errlens?style=for-the-badge" alt="Open PRs">
17-
18-
<!-- npm Badges -->
19-
<br>
20-
<img src="https://img.shields.io/npm/v/errlens?style=for-the-badge" alt="npm version">
21-
<img src="https://img.shields.io/npm/dm/errlens?style=for-the-badge" alt="npm downloads">
22-
<img src="https://img.shields.io/github/v/tag/BeyteFlow/errlens?style=for-the-badge" alt="Git tag version">
23-
<img src="https://img.shields.io/node/v/errlens?style=for-the-badge" alt="Node.js version">
24-
</p>
25-
**ErrLens** is a professional-grade CLI utility designed to eliminate developer frustration. It intercepts Node.js crashes, analyzes stack traces, and delivers plain-English explanations with actionable fixes—directly in your terminal.
26-
27-
---
28-
</br>
29-
</br>
30-
</br>
31-
<p align="center">
32-
<img src="assets/terminal.png" width="800">
33-
</p>
34-
</br>
35-
</br>
36-
37-
## 🌟 Key Features
38-
39-
- 🚀 **Instant Diagnostics** – No more context-switching to Google or StackOverflow.
40-
- 🔄 **Live Monitoring** – Catch errors in real-time using the `errlens run` command.
41-
- 🧠 **Fuzzy Logic Engine** – Matches messy stack traces and typos using `Fuse.js`.
42-
- 🎨 **Beautiful UI** – High-visibility terminal output powered by `boxen` and `chalk`.
43-
- 🤖 **CI/CD Ready** – Export raw data via `--json` for automated error reporting.
44-
45-
---
46-
47-
## 📦 Installation
48-
49-
Install globally via npm to use the `errlens` command anywhere in your terminal:
50-
51-
```bash
52-
npm install -g errlens
53-
```
54-
55-
---
56-
57-
## ⚡ Quick Start
58-
59-
```bash
60-
# Analyze an error message
61-
errlens analyze "TypeError: Cannot read property 'name' of undefined"
62-
63-
# Run a script with error monitoring
64-
errlens run your-script.js
65-
66-
# Get JSON output for CI/CD pipelines
67-
errlens analyze "is not a function" --json
68-
```
69-
70-
---
71-
72-
## 🛠 Usage
73-
74-
### Available Commands
75-
76-
```bash
77-
errlens run <file> [--json] # Run a script and analyze any crashes
78-
errlens analyze <error> [--json] # Analyze a specific error message
79-
errlens --version # Show version information
80-
errlens --help # Show help
81-
```
82-
83-
### 1️⃣ Automatic Monitoring (The "Pro" Way)
84-
85-
Run your script through ErrLens. If it crashes, ErrLens intercepts the error and explains the fix before the process exits.
86-
87-
```bash
88-
errlens run your-app.js
89-
```
90-
91-
---
92-
93-
### 2️⃣ Manual Analysis
94-
95-
Found a weird error in your logs? Just paste the message:
96-
97-
```bash
98-
errlens analyze "TypeError: Cannot read properties of undefined"
99-
```
100-
101-
---
102-
103-
### 3️⃣ Pipeline Integration
104-
105-
Get machine-readable results for your own tooling or automated reports:
106-
107-
```bash
108-
errlens analyze "is not a function" --json
109-
```
110-
111-
Run a script and write the JSON report directly to a file in CI:
112-
113-
```bash
114-
errlens run test.js --json > ci-report.json
115-
```
116-
117-
In `--json` mode, ErrLens prints only JSON (no spinner, colors, or terminal boxes).
118-
119-
Example response from `run`:
120-
121-
```json
122-
{
123-
"code": 0,
124-
"count": 0,
125-
"matches": []
126-
}
127-
```
128-
129-
Example response from `analyze <errorString>` (match found):
130-
131-
```json
132-
{
133-
"code": 1,
134-
"count": 1,
135-
"matches": [
136-
{
137-
"name": "TypeError: Cannot read properties of undefined",
138-
"match": "Cannot read properties of undefined",
139-
"explanation": "You are trying to access a property on a variable that is currently empty.",
140-
"why": "The variable wasn't initialized, or an API call hasn't finished yet.",
141-
"fixes": [
142-
"Use optional chaining: user?.name",
143-
"Set a default value: data || []"
144-
],
145-
"example": "const name = user?.name || 'Guest';"
146-
}
147-
]
148-
}
149-
```
150-
151-
Exit codes (useful for CI):
152-
153-
- `run <file>` exits with the child process exit code.
154-
- `analyze <errorString>` exits with `1` when matches are found (intentional, so CI can fail when known errors are detected), otherwise `0`.
155-
156-
This follows Unix conventions where `0` means success and non-zero means failure. If you prefer success-on-detection in CI, invert the check in your pipeline logic (for example, treat exit code `1` from `analyze <errorString>` as a pass condition).
157-
158-
---
159-
160-
## 🧠 System Architecture
161-
162-
ErrLens operates on a three-stage intelligent pipeline to turn confusion into clarity:
163-
164-
| Phase | Component | Description |
165-
|---------------|----------------|-------------|
166-
| Interception | `auto.js` | Hooks into the `uncaughtException` event via a preload script. |
167-
| Matching | `matcher.js` | Uses fuzzy search against `database.json` to find the root cause. |
168-
| Formatting | `formatter.js` | Wraps the diagnosis in a clean, color-coded terminal interface. |
169-
170-
---
171-
172-
## 📁 Project Structure
173-
174-
```
175-
errlens/
176-
├── bin/index.js # CLI Entry point & Command routing
177-
├── lib/
178-
│ ├── matcher.js # Fuzzy search & Logic engine
179-
│ ├── formatter.js # UI & Terminal styling
180-
│ ├── auto.js # Automation & Error interception
181-
│ └── database.json # The "Knowledge Base" (Dictionary)
182-
├── package.json # Dependencies & Metadata
183-
└── README.md # Documentation
184-
```
185-
186-
---
187-
188-
## 🤝 Contributing
189-
190-
We are building the world's most comprehensive dictionary of JavaScript errors, and we need your help!
191-
192-
1. Fork the repository.
193-
2. Add a new error entry to `lib/database.json`.
194-
3. Submit a Pull Request.
195-
196-
💡 **Tip:** Every error you add helps another developer save valuable time. Join the mission!
197-
198-
---
199-
200-
## 📝 License
201-
202-
Distributed under the MIT License. See `LICENSE` for more information.
203-
204-
---
205-
206-
<p align="center">
207-
Built with ❤️ by <b>BeyteFlow</b><br>
208-
<i>Making the terminal a friendlier place, one error at a time.</i>
209-
</p>
4+
## 📚 Supported Errors
5+
ErrLens currently provides explanations for:
6+
- `ReferenceError` (Variables not defined)
7+
- `TypeError` (Cannot read property of undefined)
8+
- `SyntaxError` (Unexpected tokens)
9+
- `RangeError` (Stack overflow)
10+
11+
*(More added regularly!)*
12+
13+
## 📦 Features
14+
- 🚀 **Instant Diagnostics**
15+
- 🔄 **Live Monitoring**
16+
- 🧠 **Fuzzy Logic Engine**
17+
- 🎨 **Beautiful UI**
18+
- 🤖 **CI/CD Ready**

‎lib/errors.js‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
module.exports = [
2+
{
3+
pattern: "ReferenceError: .* is not defined",
4+
explanation: "You are trying to use a variable that has not been declared.",
5+
cause: "Commonly caused by typos in variable names, or trying to access a variable outside of its scope.",
6+
fix: "Verify that the variable is declared in the current scope and check for spelling errors."
7+
},
8+
{
9+
pattern: "TypeError: Cannot read properties of undefined \(reading '.*'\)",
10+
explanation: "You are trying to access a property on an object that is undefined.",
11+
cause: "Often happens when an asynchronous call returns nothing or an API response is not structured as expected.",
12+
fix: "Check if the object is initialized properly before accessing its properties. Use optional chaining (obj?.prop) for safety."
13+
},
14+
{
15+
pattern: "SyntaxError: Unexpected token",
16+
explanation: "The JavaScript engine encountered an unexpected character or symbol.",
17+
cause: "Missing brackets, commas, or parentheses, or using reserved keywords incorrectly.",
18+
fix: "Review the line indicated by the stack trace for missing syntax elements."
19+
},
20+
{
21+
pattern: "RangeError: Maximum call stack size exceeded",
22+
explanation: "The function has called itself too many times (infinite recursion).",
23+
cause: "A recursive function lacks a proper exit condition.",
24+
fix: "Ensure your recursive function has a base case that terminates execution correctly."
25+
}
26+
];

0 commit comments

Comments
 (0)