⟳ JS Event Loop Visualizer

An interactive, browser-based visualizer for JavaScript's Event Loop — fully self-contained with no backend required.

---

🧠 What Is This?

JavaScript's Event Loop is one of the most important — and most misunderstood — concepts in the language. This tool lets you write any JavaScript code and watch, step by step, exactly how the engine processes it:

• Which functions get pushed onto the Call Stack
• Which Promise callbacks land in the Microtask Queue
• Which setTimeout callbacks wait in the Macro Task Queue
• What gets printed to the Console and when
• The precise order every event fires

Everything runs entirely in your browser. There is no server, no API call, no build step needed to use it.

---

✨ Features

Feature	Description
🎞 Step-by-step playback	Use ◀ ▶ buttons to walk through execution one event at a time
⏯ Auto-play with speed control	Play at 0.5×, 1×, 2×, or 4× speed
📊 4-panel live visualization	Call Stack, Microtask Queue, Task Queue, and Console update in real time
📜 Event Log	Full list of every runtime event — click any row to jump to that moment
✏️ Live code editor	Write your own code with line numbers and syntax-friendly layout
📦 5 built-in examples	Curated examples covering key Event Loop concepts
🔵 Promise tracking	Tracks new Promise, .then(), .resolve(), microtask enqueue/dequeue
⏱ setTimeout tracking	Tracks setTimeout registration and callback execution order
🧩 Self-contained engine	No Node.js backend — the entire tracer runs inside the browser

---

🚀 Getting Started

Prerequisites

• Node.js 16+
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/paaarth/js-event-loop-visualizer.git

# Navigate into the project
cd js-event-loop-visualizer

# Install dependencies
npm install

# Start the development server
npm start

The app will open at http://localhost:3000.

Build for Production

npm run build

---

🗂 Project Structure

js-event-loop-visualizer/
├── src/
│   ├── EventLoopVisualizer.jsx   # Main component — entire app lives here
│   └── index.js                  # React entry point
├── public/
│   └── index.html
├── package.json
└── README.md

The entire visualizer — engine, UI, and styles — is contained in a single component file (EventLoopVisualizer.jsx) with no external UI library dependencies.

---

⚙️ How It Works

This project reimplements the concept from js-visualizer-9000-server entirely in the browser. Instead of sending code to a Node.js backend, three pure-JS modules handle everything client-side:

1. instrumentCode(src) — Code Instrumenter

A character-by-character source parser that locates every named function foo() {} declaration and wraps its body with __enter("foo") and __exit("foo") tracking calls using try/finally, so execution entry and exit are always captured — even when exceptions are thrown.

// Your code:
function greet() {
  console.log("Hello");
}

// After instrumentation:
function greet() {
  __enter("greet"); try {
    console.log("Hello");
  } finally { __exit("greet"); }
}

2. MockPromise — Custom Promise Implementation

A hand-written Promise class that mirrors the native Promise API (.then(), .catch(), .finally(), Promise.resolve()) but emits structured events into an array as it runs:

• InitPromise — a new Promise was created
• ResolvePromise — a Promise was resolved
• EnqueueMicrotask — a .then() callback was queued
• DequeueMicrotask — a microtask callback was invoked

3. traceCode(userCode) — Runtime Tracer

Runs the instrumented code via new Function(...) with all global APIs shadowed by mocks:

Global	Mock Behavior
console.log	Emits ConsoleLog event
setTimeout	Registers callback in a local macro queue, emits InitTimeout
Promise	Uses MockPromise class above
__enter / __exit	Emits EnterFunction / ExitFunction events

After the synchronous code finishes, the tracer manually flushes the microtask queue, then processes the macro task queue in order — exactly as a real JS engine would.

4. deriveState(events, stepIndex) — State Deriver

Replays the recorded events from index 0 to N to compute a snapshot of the visualizer state at any moment: what's on the stack, what's in each queue, what's been logged.

---

📖 Built-in Examples

#	Name	Concepts Covered
1	Basic Event Loop	Call Stack, setTimeout, Promise.resolve, execution order
2	Microtask vs Macrotask	Why microtasks always run before the next macrotask
3	Promise Chain	Sequential .then() chaining and microtask scheduling
4	Multiple Timeouts	How multiple setTimeout calls are ordered in the task queue
5	Promise Inside Timeout	Microtasks spawned from within a macrotask callback

---

🎨 Design

• Theme: Dark terminal aesthetic with neon accents
• Fonts: Chakra Petch (UI) + Inconsolata (code/mono)
• Color coding:
  • 🔵 Cyan #22d3ee — Call Stack / function calls
  • 🟣 Violet #a78bfa — Microtask Queue / Promises
  • 🟠 Orange #fb923c — Task Queue / setTimeout
  • 🟢 Green #4ade80 — Console output

---

🧪 Supported Code Patterns

Pattern	Supported
Named function declarations	✅
console.log / .warn / .error	✅
setTimeout(fn, delay)	✅
Promise.resolve().then(fn)	✅
new Promise((res, rej) => ...)	✅
Promise chaining (.then().then())	✅
async/await	❌ (planned)
Arrow functions (anonymous)	⚠️ Tracked as "callback"

---

🙌 Acknowledgements

Inspired by JS Visualizer 9000 by Andrew Dillon (Hopding). This project reimplements the event tracing engine entirely in the browser as a standalone React component.

---

📄 License

MIT — free to use, modify, and distribute.