JavaScript Event Loop Internals Full Guide

// THE EVENT LOOP ALGORITHM (simplified):
//
// while (true) {
//   1. Pick oldest task from the macrotask queue
//   2. Execute it completely (run-to-completion)
//   3. Execute ALL microtasks:
//      while (microtaskQueue.length > 0) {
//        execute(microtaskQueue.shift());
//      }
//   4. (Browser only) If it's time to render:
//      a. Run requestAnimationFrame callbacks
//      b. Layout, Paint, Composite
//   5. Go to step 1
// }
 
// MODEL IMPLEMENTATION
class EventLoop {
  #callStack = [];
  #macrotaskQueue = [];      // setTimeout, setInterval, I/O, UI events
  #microtaskQueue = [];      // Promise.then, queueMicrotask, MutationObserver
  #animationCallbacks = [];  // requestAnimationFrame (browser)
 
  // Schedule a macrotask
  scheduleMacrotask(callback, label) {
    this.#macrotaskQueue.push({ callback, label });
  }
 
  // Schedule a microtask
  scheduleMicrotask(callback, label) {
    this.#microtaskQueue.push({ callback, label });
  }
 
  // Run one tick of the event loop
  tick() {
    // Step 1: Pick one macrotask
    if (this.#macrotaskQueue.length > 0) {
      const task = this.#macrotaskQueue.shift();
      console.log(`[Macrotask] ${task.label}`);
      this.#execute(task.callback);
    }
 
    // Step 2: Drain all microtasks
    while (this.#microtaskQueue.length > 0) {
      const micro = this.#microtaskQueue.shift();
      console.log(`[Microtask] ${micro.label}`);
      this.#execute(micro.callback);
    }
 
    // Step 3: RAF callbacks (browser)
    const rafs = [...this.#animationCallbacks];
    this.#animationCallbacks.length = 0;
    for (const raf of rafs) {
      console.log(`[RAF] ${raf.label}`);
      this.#execute(raf.callback);
    }
  }
 
  #execute(fn) {
    this.#callStack.push(fn);
    try {
      fn(this); // Pass event loop reference for scheduling
    } finally {
      this.#callStack.pop();
    }
  }
 
  run(maxTicks = 100) {
    let ticks = 0;
    while (this.#hasPending() && ticks < maxTicks) {
      this.tick();
      ticks++;
    }
  }
 
  #hasPending() {
    return (
      this.#macrotaskQueue.length > 0 ||
      this.#microtaskQueue.length > 0 ||
      this.#animationCallbacks.length > 0
    );
  }
}

// MICROTASK SOURCES:
// 1. Promise.prototype.then / catch / finally callbacks
// 2. queueMicrotask(callback)
// 3. MutationObserver callbacks (browser)
// 4. process.nextTick (Node.js - even higher priority than microtasks)
 
// KEY RULE: All microtasks are drained before the next macrotask
// Microtasks scheduled DURING microtask execution run immediately
 
// EXECUTION ORDER DEMO
console.log("1: Script start");
 
setTimeout(() => console.log("2: setTimeout"), 0);
 
Promise.resolve()
  .then(() => {
    console.log("3: Promise 1");
    queueMicrotask(() => console.log("4: Nested microtask"));
  })
  .then(() => console.log("5: Promise 2"));
 
queueMicrotask(() => console.log("6: queueMicrotask"));
 
console.log("7: Script end");
 
// OUTPUT ORDER:
// 1: Script start         (synchronous - initial script execution)
// 7: Script end           (synchronous - same call stack)
// 3: Promise 1            (microtask - first .then)
// 6: queueMicrotask       (microtask - queued during sync phase)
// 4: Nested microtask     (microtask - queued during "Promise 1" microtask)
// 5: Promise 2            (microtask - chained .then)
// 2: setTimeout           (macrotask - runs after ALL microtasks)
 
// STARVATION WARNING
// If microtasks keep scheduling more microtasks, the macrotask queue
// is starved and the browser cannot render
 
// BAD: Infinite microtask loop
function microtaskStarvation() {
  let count = 0;
  function recurse() {
    count++;
    if (count < 1_000_000) {
      queueMicrotask(recurse); // Blocks macrotasks for millions of ticks
    }
  }
  queueMicrotask(recurse);
  // setTimeout callbacks will never fire
  // Browser will freeze (no rendering)
}
 
// SAFE: Use setTimeout to yield to macrotasks
function yieldingLoop(items, processItem) {
  let index = 0;
  const batchSize = 100;
 
  function processBatch() {
    const end = Math.min(index + batchSize, items.length);
    for (; index < end; index++) {
      processItem(items[index]);
    }
    if (index < items.length) {
      setTimeout(processBatch, 0); // Yield to event loop
    }
  }
 
  processBatch();
}

// Node.js uses libuv which implements a multi-phase event loop
// Each phase has its own FIFO queue of callbacks
 
// NODE.JS EVENT LOOP PHASES:
//
// ┌───────────────────────────┐
// │         timers             │  setTimeout, setInterval
// │  (execute expired timers)  │
// ├───────────────────────────┤
// │     pending callbacks      │  OS-level callbacks (TCP errors, etc.)
// │  (deferred I/O callbacks)  │
// ├───────────────────────────┤
// │       idle, prepare        │  Internal use only
// │                            │
// ├───────────────────────────┤
// │          poll              │  I/O callbacks (fs.read, net.connect, etc.)
// │  (retrieve new I/O events) │  Block here if nothing else is scheduled
// ├───────────────────────────┤
// │          check             │  setImmediate callbacks
// │                            │
// ├───────────────────────────┤
// │     close callbacks        │  socket.on('close', ...)
// │                            │
// └───────────────────────────┘
//        ↑                ↓
//        └────────────────┘
//
// Between EVERY phase: drain process.nextTick queue, then microtask queue
 
// PHASE DEMONSTRATION
const { performance: perf } = require("node:perf_hooks");
const fs = require("node:fs");
 
// Phase ordering example:
setImmediate(() => console.log("1: check phase (setImmediate)"));
 
setTimeout(() => console.log("2: timer phase (setTimeout 0)"), 0);
 
fs.readFile(__filename, () => {
  console.log("3: poll phase (I/O callback)");
 
  // Inside an I/O callback, setImmediate fires before setTimeout
  setImmediate(() => console.log("4: check phase (after I/O)"));
  setTimeout(() => console.log("5: timer phase (after I/O)"), 0);
});
 
process.nextTick(() => console.log("6: nextTick (before microtask)"));
Promise.resolve().then(() => console.log("7: microtask (promise)"));
 
// OUTPUT ORDER:
// 6: nextTick (before microtask)     -- nextTick always first
// 7: microtask (promise)              -- microtask after nextTick
// 2: timer phase (setTimeout 0)       -- OR 1 could be first (race)
// 1: check phase (setImmediate)       -- OR 2 could be first (race)
// 3: poll phase (I/O callback)        -- I/O completes
// 4: check phase (after I/O)          -- setImmediate in I/O is deterministic
// 5: timer phase (after I/O)          -- setTimeout in I/O fires next tick
 
// POLL PHASE BLOCKING
// When the event loop reaches the poll phase with:
// - No setImmediate scheduled
// - No expired timers
// It BLOCKS and waits for I/O events (epoll/kqueue/IOCP)
// This is how Node.js achieves low CPU usage while idle
 
// Example: "idle" Node.js process
// const server = http.createServer(handler);
// server.listen(3000);
// After startup, the event loop blocks in the poll phase
// waiting for incoming connections via epoll_wait()
// CPU usage: ~0% while idle

// TIMER PRECISION
// setTimeout(fn, 0) does NOT execute immediately
// Minimum delay is typically 1ms (clamped by the environment)
// Nested setTimeout calls (depth > 5) are clamped to 4ms minimum
 
// TIMER HEAP
// V8/Node.js stores timers in a min-heap sorted by expiration time
// The event loop checks the heap on each timer phase
 
class TimerHeap {
  #heap = [];
 
  schedule(callback, delayMs) {
    const timer = {
      callback,
      expiry: Date.now() + delayMs,
      id: Math.random().toString(36).slice(2)
    };
    this.#heap.push(timer);
    this.#bubbleUp(this.#heap.length - 1);
    return timer.id;
  }
 
  cancel(id) {
    const idx = this.#heap.findIndex((t) => t.id === id);
    if (idx !== -1) {
      this.#heap[idx] = this.#heap[this.#heap.length - 1];
      this.#heap.pop();
      if (idx < this.#heap.length) this.#siftDown(idx);
    }
  }
 
  processExpired() {
    const now = Date.now();
    const expired = [];
    while (this.#heap.length > 0 && this.#heap[0].expiry <= now) {
      expired.push(this.#heap[0]);
      this.#heap[0] = this.#heap[this.#heap.length - 1];
      this.#heap.pop();
      if (this.#heap.length > 0) this.#siftDown(0);
    }
    for (const timer of expired) {
      timer.callback();
    }
    return expired.length;
  }
 
  nextExpiry() {
    return this.#heap.length > 0 ? this.#heap[0].expiry : Infinity;
  }
 
  #bubbleUp(i) {
    while (i > 0) {
      const parent = Math.floor((i - 1) / 2);
      if (this.#heap[i].expiry >= this.#heap[parent].expiry) break;
      [this.#heap[i], this.#heap[parent]] = [this.#heap[parent], this.#heap[i]];
      i = parent;
    }
  }
 
  #siftDown(i) {
    const n = this.#heap.length;
    while (true) {
      let smallest = i;
      const left = 2 * i + 1;
      const right = 2 * i + 2;
      if (left < n && this.#heap[left].expiry < this.#heap[smallest].expiry) {
        smallest = left;
      }
      if (right < n && this.#heap[right].expiry < this.#heap[smallest].expiry) {
        smallest = right;
      }
      if (smallest === i) break;
      [this.#heap[i], this.#heap[smallest]] = [this.#heap[smallest], this.#heap[i]];
      i = smallest;
    }
  }
}
 
// setTimeout vs setImmediate vs process.nextTick
//
// | API              | Queue              | Priority  | Use Case                    |
// |-------------------|--------------------|-----------|-----------------------------|
// | process.nextTick  | nextTick queue     | Highest   | Before any I/O or microtask |
// | queueMicrotask    | microtask queue    | High      | After nextTick, before I/O  |
// | Promise.then      | microtask queue    | High      | Async results               |
// | setTimeout(fn, 0) | timer phase queue  | Normal    | Defer to next loop tick     |
// | setImmediate      | check phase queue  | Normal    | After I/O poll phase        |
// | requestAnimFrame  | RAF queue (browser)| Pre-paint | Visual updates              |

// In browsers, the event loop interleaves with the rendering pipeline:
//
// ┌─────────────────────────────────────────────┐
// │ 1. Execute macrotask                         │
// │ 2. Drain microtask queue                     │
// │ 3. If ~16ms since last paint:                │
// │    a. Run requestAnimationFrame callbacks    │
// │    b. Recalculate styles                     │
// │    c. Layout (reflow)                        │
// │    d. Paint                                  │
// │    e. Composite                              │
// │ 4. If idle time remains in frame:            │
// │    a. Run requestIdleCallback                │
// └─────────────────────────────────────────────┘
 
// FRAME BUDGET
// At 60fps, each frame has ~16.67ms
// Your JS code should complete in ~10ms to leave time for rendering
 
// ANIMATING WITH THE EVENT LOOP
function animateElement(element, targetX, duration) {
  const startX = element.offsetLeft;
  const distance = targetX - startX;
  const startTime = performance.now();
 
  function frame(currentTime) {
    const elapsed = currentTime - startTime;
    const progress = Math.min(elapsed / duration, 1);
 
    // Easing function (ease-out cubic)
    const eased = 1 - Math.pow(1 - progress, 3);
    element.style.transform = `translateX(${distance * eased}px)`;
 
    if (progress < 1) {
      requestAnimationFrame(frame);
    }
  }
 
  requestAnimationFrame(frame);
}
 
// LONG TASK DETECTION
// A "long task" is anything blocking the main thread for >50ms
// Long tasks cause janky UI, delayed input handling
 
// Using PerformanceObserver to detect long tasks:
function monitorLongTasks() {
  const observer = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      console.warn(`Long task detected: ${entry.duration.toFixed(1)}ms`, {
        name: entry.name,
        startTime: entry.startTime,
        attribution: entry.attribution
      });
    }
  });
  observer.observe({ type: "longtask", buffered: true });
  return observer;
}
 
// YIELDING TO THE BROWSER
// Modern API: scheduler.yield() (Chrome 129+)
async function processLargeDataset(data) {
  const results = [];
 
  for (let i = 0; i < data.length; i++) {
    results.push(expensiveComputation(data[i]));
 
    // Yield every 50 items to let the browser render
    if (i % 50 === 49) {
      if ("scheduler" in globalThis && scheduler.yield) {
        await scheduler.yield(); // Priority-aware yielding
      } else {
        await new Promise((r) => setTimeout(r, 0)); // Fallback
      }
    }
  }
 
  return results;
}
 
function expensiveComputation(item) {
  // Simulate heavy work
  let result = 0;
  for (let i = 0; i < 10000; i++) {
    result += Math.sqrt(item * i);
  }
  return result;
}

// PRIORITY SCHEDULING with the Scheduler API (browser)
// Uses scheduler.postTask() for priority-aware task scheduling
 
async function priorityDemo() {
  // High priority: User-visible, input-related
  scheduler.postTask(
    () => console.log("user-blocking task"),
    { priority: "user-blocking" }
  );
 
  // Normal priority: Default tasks
  scheduler.postTask(
    () => console.log("user-visible task"),
    { priority: "user-visible" }
  );
 
  // Low priority: Background work
  scheduler.postTask(
    () => console.log("background task"),
    { priority: "background" }
  );
}
 
// COOPERATIVE SCHEDULING IN NODE.JS
// Break CPU-intensive work into chunks with setImmediate
function processChunked(data, chunkSize, callback) {
  let index = 0;
  const results = [];
 
  function processChunk() {
    const end = Math.min(index + chunkSize, data.length);
    for (; index < end; index++) {
      results.push(transform(data[index]));
    }
 
    if (index < data.length) {
      // setImmediate lets I/O callbacks run between chunks
      setImmediate(processChunk);
    } else {
      callback(results);
    }
  }
 
  processChunk();
}
 
function transform(item) {
  return item * 2;
}
 
// WORKER THREADS for true parallelism
// The event loop is single-threaded by design
// For CPU-bound work, offload to Worker Threads (Node.js) or
// Web Workers (browser)
 
// Node.js Worker example:
// const { Worker, isMainThread, parentPort } = require('worker_threads');
//
// if (isMainThread) {
//   const worker = new Worker(__filename);
//   worker.postMessage({ data: largeArray });
//   worker.on('message', (result) => {
//     console.log('Result from worker:', result);
//   });
// } else {
//   parentPort.on('message', (msg) => {
//     const result = heavyComputation(msg.data);
//     parentPort.postMessage(result);
//   });
// }