dumbug

The Zero-Config JavaScript Runtime Visualizer.

dumbug automates the process of debugging by instrumenting your code on the fly. It injects logging execution paths, variable states, and timing metrics without you having to write a single console.log.

It handles ES Modules, CommonJS, Async/Await flows, and Recursive calls with beautiful, indented, and colored output.

Features

• Zero Setup: Runs directly via npx. No config files required.
• Visual Call Stack: Auto-indents logs based on call depth.
• Async Aware: Correctly tracks await points, measuring the duration of promises and maintaining indentation when execution resumes.
• Data Inspection: Automatically color-codes and formats arguments and return values.
• Granular Control: Use JSDoc-style annotations to trace specific files, functions, lines, or variables.
• Line-by-Line Tracing: Option to log every single line of code executed within a function.
• Variable Snapshots: Dump all local variables at any specific point in time.

Get Started

Method 1: The Quickest Way (npx)

Run any Node.js script immediately without installing anything:

npx dumbug path/to/script.js

Method 2: Global Installation

Install it globally to use the dumbug command anywhere:

npm install -g dumbug

dumbug server.js

Method 3: Local Dependency

Add it to your project for your team to use:

npm install --save-dev dumbug

Then add to your package.json scripts:

"scripts": {
  "debug": "dumbug src/index.js"
}

Annotations Guide

Control exactly what gets traced using simple comments.

1. File-Level Tracing

Add this to the top of any file to trace every function inside it.

/** @debug-file */

export function calculate(a, b) {
  return a + b;
}

2. Function-Level Tracing

Trace specific functions without enabling the whole file.

/** @debug-function */
function complexAlgo(data) {
  // Only this function entry/exit will be logged
  return process(data);
}

3. Step-by-Step Tracing

Log every executed line of code inside a function. Great for debugging control flow loops and conditionals.

/** @debug-function-step */
function loopTest() {
  for (let i = 0; i < 3; i++) {
    if (i === 1) continue;
    doWork(i);
  }
}

Output:

  entered loopTest() [file.js:10]
    step: for(let i=0; i<3; i++) [file.js:12]
    step: if(i===1) continue; [file.js:13]
    step: doWork(i); [file.js:14]
  exited loopTest returned undefined

4. Variable Dumping

Dump all locally visible variables (arguments, let, const, var) at a specific line. Objects are expanded (up to 128 chars) for easier reading.

function processUser(id) {
  const user = { name: "Alice", meta: { admin: true } };
  const active = true;

  // @debug-vars
  
  return user;
}

Output:

  local variables [file.js:5]
    active = true
    id = 42
    user = {"name":"Alice","meta":{"admin":true}}

5. Class Tracing

Trace all methods within a class.

/** @debug-class */
class UserService {
  constructor() { ... }
  find() { ... }
  delete() { ... }
}

The Output Format

dumbug uses a color-coded format to make logs readable:

• Indentation: Represents the call stack depth.
• Light Blue: Function names and executed code snippets.
• Light Green: Return values and variable values.
• Dimmed Gray: File paths, line numbers, and execution timing (5ms).
• Orange: Thrown errors.

Example Output

entered main() [app.js:10]
  entered getUser(1) [services/user.js:5]
    #a1b2c awaiting db.find({id: 1}) [services/user.js:6]
    ----------------------------------------
    #a1b2c resumed getUser (15ms) [services/user.js:6]
  exited getUser returned {"id":1,"name":"Alice"} (16ms) [services/user.js:7]
  local variables [app.js:12]
    user = {"id":1,"name":"Alice"}
exited main returned undefined (20ms) [app.js:15]

How it Works

dumbug is a runtime instrumentation tool. When you run dumbug script.js:

1. It spawns a Node.js child process.
2. It hooks into Node's module loading system (via import loaders and require extensions).
3. As files are loaded, it intercepts the source code.
4. It uses Babel to parse the code into an AST (Abstract Syntax Tree).
5. It inserts console.log statements with ANSI colors at entry points, exit points, await expressions, and annotation markers.
6. The modified code is executed by Node.js.

This means you are debugging the actual code behavior without manually cluttering your source files with logs.

Limitations

• Performance: Because every function call involves logging to stdout, execution will be slower. Do not use this in production.
• Source Maps: Currently, line numbers point to the original source location, but stack traces from errors might slightly differ due to code injection.