Node.js Internals: How JavaScript Reaches the Processor

Why Understanding Node.js Internals Matters

You write JavaScript. You run node server.js. Requests come in. Responses go out. But what actually happens in between?

Most developers treat Node.js like a black box. They know “Node.js is single-threaded” (which is kinda true, but also kinda wrong). They know “async/await makes things fast” (sometimes). They know “the event loop is important” (definitely true).

But do they understand it?

This post is a deep dive into the machinery. By the end, you’ll know:

• How JavaScript becomes machine code (V8 engine)
• How Node.js enables server-side JavaScript (libuv, C++ bindings)
• How thousands of requests are handled in a single-threaded runtime
• Why the event loop works the way it does
• How microtasks, macrotasks, and animation frames interact
• Real performance implications of understanding (or misunderstanding) these concepts

This isn’t theoretical fluff. Understanding this changes how you write code, debug issues, and optimize performance.

Let’s go deep.

Part 1: The Journey From JavaScript to Machine Code

The Gap: JavaScript Isn’t Native to the Processor

Here’s a fundamental truth: processors don’t understand JavaScript. They understand machine code (binary instructions).

When you write:

1
let x = 2 + 2;
2
console.log(x);

The CPU has no idea what this means. It needs to be converted to machine code it can execute.

1
Actually executed:
2
MOV rax, 2       ; Move 2 into register rax
3
ADD rax, 2       ; Add 2 to rax
4
...

The Missing Link: JavaScript Engine

A JavaScript engine is the translator. It reads your JavaScript and converts it to machine code.

Examples of JavaScript engines:

• V8 – Used by Node.js and Chrome
• SpiderMonkey – Used by Firefox
• JavaScriptCore – Used by Safari
• QuickJS – Lightweight, embedded systems

The engine doesn’t care where the JavaScript runs. V8 can convert JavaScript to machine code anywhere—in a browser, on a server, on an IoT device.

Node.js: More Than Just V8

Here’s where most people get confused.

Misconception: “Node.js runs JavaScript”

Reality: V8 runs JavaScript. Node.js enables JavaScript to do server things.

V8 alone can execute JavaScript. But it can’t:

• Read files (fs.readFile)
• Create HTTP servers (http.createServer)
• Handle cryptography (crypto.hash)
• Listen on network sockets
• Manage memory efficiently for server workloads

These are system-level operations that require access to the operating system.

The Architecture: V8 + libuv + Node.js

1
┌─────────────────────────────────────┐
2
│         Your JavaScript Code        │
3
│     (fs.readFile, http.listen)      │
4
└──────────────┬──────────────────────┘
5
               │
6
               ▼
7
┌─────────────────────────────────────┐
8
│          Node.js (Runtime)          │
9
│  - Provides fs, http, crypto, etc   │
10
│  - Bridges JS to OS operations      │
11
│  - Manages bindings between V8 & OS │
12
└──────────────┬──────────────────────┘
13
               │
14
      ┌────────┴──────────┐
15
      │                   │
16
      ▼                   ▼
17
  ┌──────────┐      ┌──────────┐
18
  │   V8     │      │  libuv   │
19
  │(Execute) │      │(Schedule)│
20
  └──────────┘      └──────────┘
21
      │                   │
22
      └────────┬──────────┘
23
               │
24
               ▼
25
       ┌──────────────────┐
26
       │  Operating System│
27
       │  (Linux/macOS/   │
28
       │   Windows)       │
29
       └──────────────────┘

C++ Bindings: The Bridge

Node.js itself is written in both JavaScript and C++.

When you call fs.readFile():

1. JavaScript code calls the function
2. Node.js has a C++ binding that wraps the actual file reading
3. The C++ code uses OS system calls to read the file
4. Results are marshaled back to JavaScript types (V8 objects)

1
// What you write (JavaScript)
2
fs.readFile('file.txt', (err, data) => {
3
  console.log(data);
4
});
5

6
// What happens internally (C++)
7
// V8 converts JS objects to C++ objects
8
// OS performs the actual file I/O
9
// Results converted back to V8 objects
10
// Callback is queued for later execution

This is why Node.js can do “system” things—it’s not actually JavaScript doing them. It’s C++ calling OS APIs, and JavaScript is just orchestrating it.

Part 2: Threads and Processes (The Myth of “Single-Threaded”)

What Does “Single-Threaded” Actually Mean?

You’ve heard this: “Node.js is single-threaded.”

This is simultaneously true and misleading.

Processes and Threads: Fundamentals

Process:

• Fundamental unit of execution on the OS
• Has its own memory space, registers, file descriptors
• Isolated from other processes
• Example: When you run node server.js, you create one process

Thread:

• Lightweight unit of execution within a process
• Shares memory with other threads in the same process
• Can run in parallel (on multi-core systems)
• Context switching between threads has lower overhead than between processes

CPU Cores:

• A machine with 8 cores can execute 8 threads simultaneously
• More threads exist than cores (OS scheduler handles this)
• Context switching between threads is fast (microseconds)

Node.js: Single Main Thread, But Not Really Single-Threaded

When you run:

node server.js

One primary thread is created—the one that executes your JavaScript code. This thread runs the V8 engine.

1
OS: "Node.js process spawned on Core 1"
2
V8 + Event Loop: Running on Core 1
3
JavaScript: Executing on Core 1

This is why it’s “single-threaded.”

But here’s the twist: OS operations are not single-threaded.

When you call an async operation like fs.readFile():

1
fs.readFile('large-file.txt', (err, data) => {
2
  console.log('File read complete');
3
});
4
console.log('File read requested');

Output:

1
File read requested
2
File read complete

What’s actually happening:

1. JavaScript calls fs.readFile()
2. Node.js delegates to the OS: “Please read this file”
3. OS reads the file on a different core (not blocked on your main thread)
4. OS signals back: “File is ready”
5. Callback is executed on the main thread

1
Time: 0ms   - Main thread: fs.readFile() called
2
Time: 0ms   - Node.js: "OS, read this file" (delegates to Core 2)
3
Time: 0ms   - Main thread: Continues executing (not blocked)
4
Time: 15ms  - Core 2: Finishes reading file
5
Time: 15ms  - Main thread: Executes callback (back on Core 1)

So is Node.js single-threaded?

• Your JavaScript code? Yes, runs on one thread.
• The underlying system? No, OS can parallelize I/O across multiple cores.
• The result? You get concurrency (handling many requests) without explicit multithreading.

Part 3: Thread Pools and CPU-Intensive Operations

The Thread Pool Problem

Some operations can’t be delegated to the OS easily. Example: password hashing with bcrypt.

1
const bcrypt = require('bcrypt');
2
const http = require('http');
3

4
http.createServer((req, res) => {
5
  bcrypt.hash('password123', 10).then((hash) => {
6
    res.writeHead(200, { 'Content-Type': 'text/plain' });
7
    res.write(hash);
8
    res.end();
9
  });
10
}).listen(3000);

Bcrypt needs to do heavy CPU computation (iteratively hashing many times). The OS can’t do this for you—you need to actually run the algorithm.

But you can’t do it on the main thread—it would block all requests.

Solution: Thread Pool

libuv’s Thread Pool

libuv (the library that manages concurrency in Node.js) maintains a thread pool.

By default, it has 4 threads. You can configure this:

UV_THREADPOOL_SIZE=8 node server.js

When you call bcrypt.hash():

1. Main thread receives request
2. Bcrypt (C++ binding) requests a thread from libuv’s pool
3. One of the 4 pool threads executes the hashing
4. Main thread continues handling other requests
5. When hashing completes, callback is queued
6. Main thread executes callback and sends response

1
Request 1 → bcrypt.hash() → Thread 1 (hashing password1)
2
Request 2 → bcrypt.hash() → Thread 2 (hashing password2)
3
Request 3 → bcrypt.hash() → Thread 3 (hashing password3)
4
Request 4 → bcrypt.hash() → Thread 4 (hashing password4)
5
Request 5 → bcrypt.hash() → WAIT (all threads busy)

Measuring Thread Pool Impact

Let’s benchmark. Create this server:

1
const http = require('http');
2
const bcrypt = require('bcrypt');
3

4
http.createServer((req, res) => {
5
  bcrypt.hash('codedamn-forever', 10).then((hash) => {
6
    res.writeHead(200, { 'Content-Type': 'text/plain' });
7
    res.write(hash);
8
    res.end();
9
  });
10
}).listen(3000);

Test with Apache Bench:

ab -n 1000 -c 100 http://localhost:3000/

Results with different UV_THREADPOOL_SIZE:

Why does it plateau at 4?

Because this machine has 4 CPU cores. Beyond 4 threads, you’re not gaining parallelism—you’re just context-switching, which wastes CPU cycles.

Optimal Thread Pool Size

Rule of thumb: Match thread pool size to logical CPU cores, maybe slightly higher (10-20%) for overhead.

1
const os = require('os');
2
const optimalThreadPoolSize = os.cpus().length;
3

4
process.env.UV_THREADPOOL_SIZE = optimalThreadPoolSize;

Important: Some CPUs have hyperthreading. A 4-core CPU with hyperthreading shows as 8 logical cores:

$ sysctl -n hw.ncpu
8  # 4 physical cores × 2 threads per core

In this case, you can slightly benefit from 6-8 threads (accounting for context switching overhead).

But never blindly increase it. More threads = more memory used, more context switching overhead. The benefits plateau quickly.

Part 4: The Event Loop (The Core of Node.js)

What Is the Event Loop?

The event loop is a loop that runs in Node.js, constantly asking: “Is there anything to do?”

It’s not mysterious magic. It’s just a loop:

1
// Pseudo-code: This is roughly what libuv does
2
while (eventLoop.waitForTask()) {
3
  // Execute all synchronous code
4
  // Execute ready callbacks
5
  // Wait for I/O
6
  // Check timers
7
  // Repeat
8
}

Phases of the Event Loop

The event loop has distinct phases. Each phase handles different types of tasks.

1
┌─────────────────────────────────────────────────────────────┐
2
│                     Event Loop Phases                       │
3
├─────────────────────────────────────────────────────────────┤
4
│                                                             │
5
│  ┌───────────────────────────────────────────────────────┐ │
6
│  │ 1. timers: Execute setInterval/setTimeout callbacks   │ │
7
│  └───────────────────────────────────────────────────────┘ │
8
│                           ↓                                │
9
│  ┌───────────────────────────────────────────────────────┐ │
10
│  │ 2. pending callbacks: Execute I/O callbacks           │ │
11
│  └───────────────────────────────────────────────────────┘ │
12
│                           ↓                                │
13
│  ┌───────────────────────────────────────────────────────┐ │
14
│  │ 3. idle, prepare: Internal use (skip this)            │ │
15
│  └───────────────────────────────────────────────────────┘ │
16
│                           ↓                                │
17
│  ┌───────────────────────────────────────────────────────┐ │
18
│  │ 4. poll: Wait for I/O events, execute I/O callbacks   │ │
19
│  └───────────────────────────────────────────────────────┘ │
20
│                           ↓                                │
21
│  ┌───────────────────────────────────────────────────────┐ │
22
│  │ 5. check: Execute setImmediate callbacks              │ │
23
│  └───────────────────────────────────────────────────────┘ │
24
│                           ↓                                │
25
│  ┌───────────────────────────────────────────────────────┐ │
26
│  │ 6. close: Execute close callbacks                      │ │
27
│  └───────────────────────────────────────────────────────┘ │
28
│                           ↓                                │
29
│              (Back to timers phase)                        │
30
│                                                             │
31
└─────────────────────────────────────────────────────────────┘

Phase 1: Timers

Execute callbacks scheduled with setTimeout() and setInterval() whose timers have expired.

1
setTimeout(() => console.log('Timeout expired'), 100);
2
// When 100ms have passed, callback is executed in timers phase

Phase 2: Pending Callbacks

Execute I/O callbacks that were deferred (system errors from previous cycles).

Phase 4: Poll (The Most Important)

This is where most of the action happens. The event loop:

1. Checks if there are any pending I/O operations (file reads, network requests, database queries)
2. If yes, waits for them to complete
3. As they complete, executes their callbacks

1
fs.readFile('file.txt', (err, data) => {
2
  console.log('File read complete');
3
});
4
// When file read completes, callback executes during poll phase

If there’s nothing to wait for, it moves to the next phase.

Phase 5: Check (setImmediate)

Execute callbacks scheduled with setImmediate(). These are higher priority than timers.

1
setImmediate(() => console.log('Immediate'));
2
// Executes during check phase

Phase 6: Close

Execute close callbacks for sockets, streams, etc.

Microtasks: The Hidden Phase

There’s actually a phase we haven’t mentioned—and it’s the most important: Microtask Phase.

Microtasks are not part of the event loop phases. They execute between every phase.

1
┌───────────────────────────────────────────┐
2
│ Phase 1: Timers                           │
3
└───────────────────────────────────────────┘
4
         ↓ (All microtasks execute here)
5
┌───────────────────────────────────────────┐
6
│ Phase 2: Pending Callbacks                │
7
└───────────────────────────────────────────┘
8
         ↓ (All microtasks execute here)
9
┌───────────────────────────────────────────┐
10
│ Phase 4: Poll                             │
11
└───────────────────────────────────────────┘
12
         ↓ (All microtasks execute here)
13
... and so on

What are microtasks?

• Promises (.then(), .catch())
• queueMicrotask()
• MutationObserver (browser)
• process.nextTick() (Node.js special)

Example:

1
setTimeout(() => console.log('Timer'), 0);
2
Promise.resolve().then(() => console.log('Promise'));
3

4
// Output:
5
// Promise
6
// Timer

Why? Promise goes to microtask queue. Timer goes to macrotask queue. Microtasks execute first.

Part 5: Understanding Execution Order (The Complete Picture)

Let’s trace through a complex example to see exactly what happens and in what order.

Example: Multiple Operations

1
console.log('1: Synchronous start');
2

3
setTimeout(() => {
4
  console.log('2: setTimeout 1');
5
  Promise.resolve().then(() => console.log('3: Promise inside setTimeout'));
6
}, 0);
7

8
Promise.resolve()
9
  .then(() => {
10
    console.log('4: Promise 1');
11
    setTimeout(() => console.log('5: setTimeout inside Promise'), 0);
12
  })
13
  .then(() => console.log('6: Promise 2'));
14

15
console.log('7: Synchronous end');

Expected output:

1
1: Synchronous start
2
7: Synchronous end
3
4: Promise 1
4
6: Promise 2
5
2: setTimeout 1
6
3: Promise inside setTimeout
7
5: setTimeout inside Promise

Let’s trace it:

1. Synchronous code runs first

   • Logs “1: Synchronous start”
   • setTimeout is scheduled → goes to timer queue
   • Promise.resolve().then() is scheduled → goes to microtask queue
   • Logs “7: Synchronous end”

2. Event loop: Microtask phase (before any event loop phases)

   • Executes first Promise → logs “4: Promise 1”
   • Schedules setTimeout inside Promise → goes to timer queue
   • Executes second Promise → logs “6: Promise 2”

3. Event loop: Timers phase (first phase)

   • Executes first setTimeout → logs “2: setTimeout 1”
   • Schedules Promise inside setTimeout → goes to microtask queue

4. Event loop: Microtask phase again (between phases)

   • Executes Promise inside setTimeout → logs “3: Promise inside setTimeout”

5. Event loop: Timers phase again (cycles back)

   • Executes setTimeout scheduled from Promise → logs “5: setTimeout inside Promise”

The Rule: Execution Order

Remember this simple rule:

Sync → Microtasks → Timer → Microtasks → I/O → Microtasks → …

Or more formally:

1
1. Execute all synchronous code in the call stack
2
2. Call stack is empty → check microtask queue (exhaust it completely)
3
3. Move to next event loop phase (timers, poll, etc.)
4
4. After each phase → check microtask queue again (exhaust it)
5
5. Repeat until all queues are empty

Real-World Complexity: The RAF Queue

In browsers, there’s another queue: Animation Frame Queue (via requestAnimationFrame).

It executes differently in Node.js vs browsers:

Browser:

1
Microtasks → Timers → Microtasks → RAF (at screen refresh, ~60Hz) → Repaint

Node.js:

1
Microtasks → Timers → Microtasks → I/O → Microtasks → ...
2
(No repaint phase, so RAF doesn't exist)

In Node.js, setImmediate acts similar to browser’s requestAnimationFrame in concept (check phase), but RAF-specific behavior doesn’t apply.

Part 6: Practical Examples and Tracing

Example 1: The Classic Interview Question

1
console.log('start');
2

3
setTimeout(() => {
4
  console.log('setTimeout');
5
}, 0);
6

7
Promise.resolve()
8
  .then(() => {
9
    console.log('promise');
10
  });
11

12
console.log('end');

Output:

1
start
2
end
3
promise
4
setTimeout

Why?

1. Sync code runs: “start”, “end”
2. Microtasks: Promise.then() → “promise”
3. Timers: setTimeout → “setTimeout”

Example 2: Nested Promises and Timers

1
Promise.resolve()
2
  .then(() => {
3
    console.log('Promise 1');
4
    setTimeout(() => console.log('Timer in Promise'), 0);
5
  })
6
  .then(() => {
7
    console.log('Promise 2');
8
  });
9

10
setTimeout(() => {
11
  console.log('Timer 1');
12
  Promise.resolve().then(() => console.log('Promise in Timer'));
13
}, 0);
14

15
setTimeout(() => console.log('Timer 2'), 0);
16

17
console.log('Sync');

Output:

1
Sync
2
Promise 1
3
Promise 2
4
Timer 1
5
Promise in Timer
6
Timer 2
7
Timer in Promise

Trace:

1. Sync: “Sync”
2. Microtasks: “Promise 1”, “Promise 2”
3. Timers (first): “Timer 1”
4. Microtasks: “Promise in Timer”
5. Timers (second): “Timer 2”
6. Timers (third, from Promise): “Timer in Promise”

Example 3: Understanding Microtask Queue Exhaustion

1
Promise.resolve().then(() => {
2
  console.log('M1');
3
  Promise.resolve().then(() => console.log('M1.1'));
4
});
5

6
Promise.resolve().then(() => {
7
  console.log('M2');
8
  Promise.resolve().then(() => console.log('M2.1'));
9
});
10

11
setTimeout(() => console.log('T1'), 0);

Output:

1
M1
2
M2
3
M1.1
4
M2.1
5
T1

Why? The microtask queue is exhausted completely before moving to timers:

1. M1 executes, schedules M1.1
2. M2 executes, schedules M2.1
3. M1.1 executes
4. M2.1 executes
5. Now microtask queue is empty → move to timers
6. T1 executes

Part 7: The Event Loop in the Browser

Node.js internals are similar to browsers, but with key differences.

Browser Event Loop

1
┌──────────────────────────────────────────┐
2
│ Synchronous Code (Call Stack)           │
3
└──────────────────────────────────────────┘
4
         ↓
5
┌──────────────────────────────────────────┐
6
│ Microtask Queue (Promises, queueMicro)  │
7
└──────────────────────────────────────────┘
8
         ↓
9
┌──────────────────────────────────────────┐
10
│ Macrotask/Task Queue (setTimeout, etc)   │
11
└──────────────────────────────────────────┘
12
         ↓
13
┌──────────────────────────────────────────┐
14
│ Animation Frame Queue (requestAnimFrame) │
15
└──────────────────────────────────────────┘
16
         ↓
17
┌──────────────────────────────────────────┐
18
│ Repaint & Layout                         │
19
└──────────────────────────────────────────┘

In the browser, requestAnimationFrame has special treatment—it’s guaranteed to run before the next repaint (typically 60 times per second for a 60Hz screen).

Node.js vs Browser: Key Differences

Example: RAF is Slower Than setTimeout in Browsers

In a browser:

1
<div id="counter1"></div>
2
<div id="counter2"></div>
3

4
<script>
5
let count1 = 0, count2 = 0;
6

7
function countWithSetTimeout() {
8
  count1++;
9
  document.getElementById('counter1').textContent = count1;
10

11
  if (count1 < 1000) {
12
    setTimeout(countWithSetTimeout, 0);
13
  }
14
}
15

16
function countWithRAF() {
17
  count2++;
18
  document.getElementById('counter2').textContent = count2;
19

20
  if (count2 < 1000) {
21
    requestAnimationFrame(countWithRAF);
22
  }
23
}
24

25
countWithSetTimeout();
26
countWithRAF();
27
</script>

Result: setTimeout counter reaches 1000 much faster than RAF counter.

Why? setTimeout can execute many times per frame (every event loop cycle), but RAF only executes once per frame (~16.67ms at 60Hz).

This is why RAF is for animations (you don’t want to animate faster than the display can show), but setTimeout is for rapid callbacks.

Part 8: Common Pitfalls and How to Avoid Them

Pitfall 1: Blocking the Event Loop

1
const http = require('http');
2

3
http.createServer((req, res) => {
4
  // Heavy computation
5
  let sum = 0;
6
  for (let i = 0; i < 1000000000; i++) {
7
    sum += i;
8
  }
9

10
  res.writeHead(200);
11
  res.end('Done');
12
}).listen(3000);

Problem: While the loop executes, no other requests can be processed. They queue up.

Solution 1: Break it into chunks with setImmediate

1
http.createServer((req, res) => {
2
  let sum = 0;
3
  let i = 0;
4
  const target = 1000000000;
5

6
  function compute() {
7
    const chunkSize = 10000000;
8
    const end = Math.min(i + chunkSize, target);
9

10
    for (; i < end; i++) {
11
      sum += i;
12
    }
13

14
    if (i < target) {
15
      setImmediate(compute); // Yield to event loop
16
    } else {
17
      res.writeHead(200);
18
      res.end(`Sum: ${sum}`);
19
    }
20
  }
21

22
  compute();
23
}).listen(3000);

Solution 2: Use Worker Threads

1
const { Worker } = require('worker_threads');
2

3
http.createServer((req, res) => {
4
  const worker = new Worker('./compute.js');
5

6
  worker.on('message', (sum) => {
7
    res.writeHead(200);
8
    res.end(`Sum: ${sum}`);
9
  });
10
}).listen(3000);

Pitfall 2: Microtask Starvation

1
function starveMacrotasks() {
2
  Promise.resolve().then(() => {
3
    console.log('Microtask');
4
    starveMacrotasks(); // Queue another promise
5
  });
6
}
7

8
starveMacrotasks();
9

10
setTimeout(() => console.log('Macrotask (never logs!)'), 0);

Problem: Promises keep getting queued faster than the event loop can process timers. The setTimeout callback never runs.

Solution: Be aware that microtasks have priority. Avoid infinite promise chains.

Pitfall 3: Misunderstanding setTimeout(0)

1
setTimeout(() => console.log('This is NOT immediate'), 0);

Common misconception: “This runs immediately after the current code.”

Reality: It’s scheduled for the next timers phase, which might be 10-100ms later depending on:

• How many microtasks are pending
• How many other timers are scheduled
• System load

setTimeout uses the browser/Node’s timer implementation, which isn’t precise for small delays.

Solution: Use process.nextTick() if you need something after the current operation:

1
process.nextTick(() => console.log('Runs after current operation'));

Or use setImmediate() if you need to defer to the next event loop iteration:

1
setImmediate(() => console.log('Runs in check phase'));

Pitfall 4: Not Handling Backpressure in Streams

1
const fs = require('fs');
2

3
const readable = fs.createReadStream('huge-file.txt');
4
const writable = fs.createWriteStream('output.txt');
5

6
readable.on('data', (chunk) => {
7
  writable.write(chunk);
8
});

Problem: If the readable stream is faster than the writable stream, chunks queue up in memory. This can crash your process.

Solution: Use pipe() which handles backpressure automatically

1
readable.pipe(writable);

Or manually handle backpressure:

1
readable.on('data', (chunk) => {
2
  const canContinue = writable.write(chunk);
3

4
  if (!canContinue) {
5
    readable.pause(); // Stop reading
6
  }
7
});
8

9
writable.on('drain', () => {
10
  readable.resume(); // Resume reading
11
});

Part 9: Performance Implications

Real-World Impact: Throughput

Let’s measure how event loop understanding impacts actual performance.

Scenario: HTTP server that hashes passwords

1
const http = require('http');
2
const bcrypt = require('bcrypt');
3

4
http.createServer((req, res) => {
5
  bcrypt.hash('password', 10).then((hash) => {
6
    res.writeHead(200);
7
    res.end(hash);
8
  });
9
}).listen(3000);

With UV_THREADPOOL_SIZE=4 (default on 4-core machine):

• Throughput: ~3600 requests/second
• Average latency: ~25ms

With blocking code instead:

1
http.createServer((req, res) => {
2
  // Simulating CPU-heavy work
3
  let sum = 0;
4
  for (let i = 0; i < 100000000; i++) {
5
    sum += i;
6
  }
7

8
  res.writeHead(200);
9
  res.end('Done');
10
}).listen(3000);

Result:

• Throughput: ~50 requests/second (72x slower!)
• Average latency: ~1000ms

Lesson: Understanding how to properly delegate work (to thread pools, to the OS, to worker threads) is critical for performance.

Latency Distribution Matters

Looking at average throughput isn’t enough. Latency distribution matters:

p95 = 95th percentile means 95% of requests are that fast or faster.

With blocking code, even 95% of users get a terrible experience (1000ms latency).

This is why understanding the event loop and async patterns is essential. Your users notice p95 latency way more than average latency.

Part 10: Debugging Event Loop Issues

Tool 1: process.cpuUsage()

Detect if the event loop is blocked:

1
const http = require('http');
2

3
setInterval(() => {
4
  const usage = process.cpuUsage();
5
  console.log(`User CPU: ${usage.user}μs, System CPU: ${usage.system}μs`);
6
}, 1000);
7

8
http.createServer((req, res) => {
9
  // Simulate work
10
  let sum = 0;
11
  for (let i = 0; i < 100000000; i++) {
12
    sum += i;
13
  }
14

15
  res.end('Done');
16
}).listen(3000);

If CPU usage stays high but you’re not doing explicit work, the event loop is blocked.

Tool 2: Node’s —inspect Flag

node --inspect server.js

Open chrome://inspect in Chrome DevTools. You can see:

• Timeline of event loop execution
• Where time is being spent
• Which callbacks are slow

Tool 3: Custom Event Loop Lag Monitoring

1
const lagThreshold = 100; // ms
2
let lastCheck = Date.now();
3

4
setInterval(() => {
5
  const now = Date.now();
6
  const lag = now - lastCheck - 100; // Expected 100ms interval
7

8
  if (lag > lagThreshold) {
9
    console.warn(`Event loop lag detected: ${lag}ms`);
10
  }
11

12
  lastCheck = now;
13
}, 100);

This detects if the event loop is delayed (lag) beyond expected intervals.

Tool 4: Flamegraph Analysis

Use tools like 0x or clinic.js:

npm install -g 0x

0x server.js
# Test your server...
# Ctrl+C to stop
# Opens an interactive flamegraph

Shows exactly where CPU time is spent.

Part 11: Node.js Internals vs JavaScript in Browsers

The Fundamental Difference

Browser:

1
Window Object → Browser APIs (DOM, fetch, setTimeout) → V8 Engine

Node.js:

1
Global Object → Node APIs (fs, http, crypto) → V8 Engine

Both use V8, but different APIs are available.

1
// Browser
2
console.log(typeof window); // 'object'
3
console.log(typeof document); // 'object'
4

5
// Node.js
6
console.log(typeof window); // 'undefined'
7
console.log(typeof document); // 'undefined'
8
console.log(typeof module); // 'object'

How APIs are Implemented

Browser: JavaScript handles some DOM APIs, but relies on the browser’s C++ engine for the actual DOM tree.

Node.js: Node.js handles some logic (JavaScript), but relies on C++ bindings to the OS for I/O.

Both follow the same pattern:

1
High-level API (JS) → Binding Layer (C++) → Lower-level system (Browser DOM / OS)

Node.js Module System vs ES6 Modules

Node.js traditionally uses CommonJS:

1
const fs = require('fs');
2
module.exports = { ... };

This is different from browser ES6 modules:

1
import fs from 'fs';
2
export { ... };

Node.js now supports both, but they have different module resolution algorithms.

Key difference: CommonJS is synchronous. Require a module, it executes immediately. ES6 modules are asynchronous.

Part 12: The C++ Layer: Why It Matters

Why Some Things Are Faster in C++

1
// JavaScript: Fast, but not fastest
2
const result = [1, 2, 3, 4, 5].map(x => x * 2);
3

4
// C++: Faster for large datasets
5
// Native code compiled to machine code directly
6
// No type checking overhead
7
// Direct memory management

For operations like:

• JSON parsing (large files)
• Cryptographic hashing
• Image processing
• Database queries

C++ is often significantly faster.

V8 Data Types in C++

When JavaScript interacts with C++, values are converted:

1
// JavaScript
2
let obj = { name: 'John', age: 30 };
3
callCppFunction(obj);
4

5
// C++
6
void callCppFunction(const v8::Local<v8::Object>& obj) {
7
  v8::String::Utf8Value name(isolate, obj->Get(context, key).ToLocalChecked());
8
  int age = obj->Get(context, key2).ToLocalChecked()->Int32Value(context).FromJust();
9
}

This conversion has overhead. For simple operations, it might be slower than pure JavaScript.

Writing Native Modules

Developers can write native modules to speed up critical paths:

1
// example.cc (C++)
2
#include <node.h>
3
using namespace v8;
4

5
void Add(const FunctionCallbackInfo<Value>& args) {
6
  Isolate* isolate = args.GetIsolate();
7

8
  double a = args[0]->NumberValue(isolate->GetCurrentContext()).FromJust();
9
  double b = args[1]->NumberValue(isolate->GetCurrentContext()).FromJust();
10

11
  Local<Number> sum = Number::New(isolate, a + b);
12
  args.GetReturnValue().Set(sum);
13
}
14

15
void init(Local<Object> exports) {
16
  NODE_SET_METHOD(exports, "add", Add);
17
}
18

19
NODE_MODULE(example, init);

Compiled to a .node binary and imported:

1
const addon = require('./build/Release/example.node');
2
console.log(addon.add(5, 3)); // 8

This is used by libraries like bcrypt, node-sass, sharp (image processing).

Part 13: The Future: Deno, Bun, and Alternatives

Node.js isn’t the only JavaScript runtime. There are alternatives with different design choices.

Deno

Created by Node.js’s original author, Deno rethinks JavaScript runtime design:

1
// Deno: More secure, different module system
2
import { serve } from "https://deno.land/std@0.208.0/http/server.ts";
3

4
serve(() => new Response("Hello"), { port: 3000 });

Key differences:

• Uses TypeScript by default
• URL-based module imports (no node_modules)
• Permissions model (ask for file access, network access, etc.)
• Simpler codebase than Node.js

Bun

A newer runtime focused on performance:

1
// Bun: Fast bundler and runtime
2
Bun.serve({
3
  fetch() {
4
    return new Response("Hello");
5
  },
6
});

Key advantages:

• Faster startup time
• Integrated bundler
• Native support for TypeScript, JSX
• Drop-in Node.js compatibility (for most code)

Comparing Runtimes

For production systems, Node.js remains the most stable choice. But the alternatives show where the ecosystem might evolve.

Conclusion: Putting It All Together

Let’s recap the journey from your JavaScript code to machine code:

1
┌─────────────────────────────────────────────────────────────┐
2
│                   Your JavaScript Code                      │
3
│              const x = await fs.readFile(...)               │
4
└──────────────────────────┬──────────────────────────────────┘
5
                           │
6
                           ▼
7
        ┌──────────────────────────────────────┐
8
        │      Node.js Runtime Environment    │
9
        │  - C++ bindings to OS APIs          │
10
        │  - Event loop management            │
11
        │  - libuv for concurrency            │
12
        └──────────────────────────────────────┘
13
                           │
14
         ┌─────────────────┼─────────────────┐
15
         │                 │                 │
16
         ▼                 ▼                 ▼
17
      ┌──────┐        ┌──────────┐      ┌─────────┐
18
      │  V8  │        │  libuv   │      │ Thread  │
19
      │(JS→  │        │(Schedules│      │ Pool    │
20
      │ Code)│        │ Tasks)   │      │(Heavy   │
21
      └──────┘        └──────────┘      │ Work)   │
22
                                        └─────────┘
23
         │                 │                 │
24
         └─────────────────┼─────────────────┘
25
                           │
26
                           ▼
27
                ┌──────────────────────┐
28
                │  Operating System    │
29
                │  - File I/O          │
30
                │  - Network I/O       │
31
                │  - Process/Threads   │
32
                └──────────────────────┘
33
                           │
34
                           ▼
35
                      ┌─────────┐
36
                      │  CPU    │
37
                      │(Machine │
38
                      │ Code)   │
39
                      └─────────┘

Key Insights:

1. V8 converts JavaScript to machine code, but it’s just one piece of the puzzle

2. Node.js is the orchestrator—it provides OS APIs and coordinates async execution

3. libuv manages concurrency—the thread pool, the event loop, timers, and I/O

4. The event loop is the heartbeat—phases determine when callbacks execute

5. Microtasks have priority—promises execute before timers

6. Thread pools scale with CPU cores—matching CPU cores to thread pool size for optimal throughput

7. Blocking is your enemy—the event loop is single-threaded for JavaScript, so CPU-heavy work must be delegated

8. Understanding this matters—it directly impacts whether your application is fast, responsive, and scalable

When You Find Yourself Debugging Performance Issues

Ask these questions:

1. Is the event loop blocked? Check with flamegraphs or lag monitoring
2. Is the thread pool saturated? Monitor UV_THREADPOOL_SIZE
3. Are promises starving timers? Look for excessive microtask queueing
4. Is there backpressure in streams? Check for memory leaks from buffering
5. Is the work CPU-bound or I/O-bound? CPU-bound needs worker threads; I/O-bound benefits from async

These questions will guide you to the answer 90% of the time.

Further Reading

• Official libuv Documentation: http://docs.libuv.org/
• Jake Archibald on Event Loop: https://www.youtube.com/watch?v=cCOL7MC4Pl0 (browser, but concepts apply)
• Node.js Source Code: https://github.com/nodejs/node
• Clinic.js for Profiling: https://clinicjs.org/
• Understanding Event Loop Lag: https://nodejs.org/en/docs/guides/blocking-vs-non-blocking/

Got questions? Found something wrong? Drop me a mail—I’d love to hear what resonates and what needs clarification.