js-debug-assistant

Explain JavaScript and Node.js runtime errors in plain English, with actionable solutions and suggested fixes. Use it as a library or from the command line to speed up debugging and help less experienced developers understand what went wrong.

Features

• 100+ common error patterns for JavaScript, Node.js, browser, async, and network issues.
• Plain‑language explanations for confusing runtime and syntax errors.
• Concrete solution guidance and example fix snippets.
• Stack trace awareness – shows file, line, and column when available.
• Static file scanner to detect risky patterns before they throw.
• Works as both Node.js library and CLI tool.

Installation

npm install js-debug-assistant

For global CLI usage:

npm install -g js-debug-assistant

Library usage

Basic example:

import explainError from 'js-debug-assistant';

try {
  console.log(user.name);
} catch (err) {
  console.log(explainError(err));
}

Sample output:

❌ Error
Cannot read properties of undefined (reading 'name')

📍 Location
src/app.js:23

💡 Explanation
You attempted to access a property on a value that is undefined.

🛠 Solution
Ensure the variable is defined before accessing its properties, or add a null/undefined check.

✨ Suggested Fix

if (user != null) {
  console.log(user.name);
}

Getting structured data instead of formatted text

import explainError, { explain } from 'js-debug-assistant';

try {
  doSomething();
} catch (err) {
  const structured = explain(err); // { name, message, category, explanation, solution, fix, location }
  console.log(structured.category);
}

Or:

const structured = explainError(err, { raw: true });

CLI usage

After installing globally:

js-debug-assistant "Cannot read properties of undefined (reading 'name')"

This prints a formatted explanation in your terminal.

Scan a file for risky patterns

js-debug-assistant scan app.js

Example output:

Static analysis for /path/to/app.js
----------------------------------------
Line 12: Property accessed in console.log without a preceding null/undefined check. (console.log(variable.property))
Line 34: Found await, but could not detect an enclosing async function. (await outside async)

Help and version

js-debug-assistant --help
js-debug-assistant --version

Example project demo

Once dependencies are installed, run:

npm run demo

This executes examples/demo.js, which intentionally triggers a common error and prints the explanation.

Contributing

Contributions are welcome! Error patterns evolve constantly and the database is designed to be easy to extend.

• See CONTRIBUTING.md for details on:
  • Project setup.
  • Coding style and architecture.
  • How to add new error patterns or analyzers.

Please open an issue before submitting large changes so we can discuss direction and design.

License

MIT © Rahbar