Blocking vs Non-Blocking Code in Node.js

One fundamental concept separates great Node.js developers from frustrated ones: understanding blocking vs non-blocking code. Write blocking code, and your entire server freezes. Write non-blocking code, and it handles thousands of concurrent users.

What Is Blocking Code?

Blocking code stops execution until an operation completes.

const fs = require('fs');

console.log('Starting');
const data = fs.readFileSync('file.txt'); // Waits here
console.log('File read');
console.log(data);

While readFileSync reads the file, nothing else happens. Your code is frozen. If this is a server handling requests, every other request waits.

Execution timeline:

0ms: Start
0ms: Call readFileSync
100ms: File read, execution continues
100ms: Log file content

The server is blocked for 100ms. If you have 100 simultaneous requests, they queue up for 100ms each. Total wait time: 10,000ms (10 seconds).

What Is Non-Blocking Code?

Non-blocking code delegates work and continues immediately:

import fs from 'fs';

console.log('Starting');
fs.readFile('file.txt', (err, data) => {
  console.log('File read');
  console.log(data);
});
console.log('Continuing');

Output:

Starting
Continuing
File read
[file content]

The file read happens in the background. Your code continues immediately.

Execution timeline:

0ms: Start
0ms: Delegate file read
0ms: Log "Continuing"
100ms: File read completes, callback executes

The server never blocks. It can handle other requests while waiting.

Real-World Impact

Let's simulate a server handling three requests, each requiring a 1-second file read:

Blocking Code:

app.get('/data', (req, res) => {
  const data = fs.readFileSync('file.txt'); // Blocks for 1 second
  res.send(data);
});

Timeline:

0s: Request 1 arrives, starts reading
1s: Request 1 done, Response 1 sent
1s: Request 2 arrives (was waiting), starts reading
2s: Request 2 done, Response 2 sent
2s: Request 3 arrives (was waiting), starts reading
3s: Request 3 done, Response 3 sent

Total time for all users: 3 seconds. Avg user wait: 2 seconds.

Non-Blocking Code:

app.get('/data', (req, res) => {
  fs.readFile('file.txt', (err, data) => {
    res.send(data);
  });
});

Timeline:

0s: Request 1 arrives, delegates read, returns immediately
0s: Request 2 arrives, delegates read, returns immediately
0s: Request 3 arrives, delegates read, returns immediately
1s: All reads complete, all responses sent

Total time for all users: 1 second. Avg user wait: ~1 second.

Non-blocking is 3x faster with just 3 requests. With 100 requests, the difference is massive.

Blocking Operations in Node.js

Common operations that have synchronous (blocking) versions:

import fs from 'fs';

// Blocking
fs.readFileSync('file.txt');
fs.writeFileSync('file.txt', 'data');

// Non-blocking alternatives
fs.readFile('file.txt', (err, data) => {});
fs.writeFile('file.txt', 'data', (err) => {});

Database operations:

// Blocking (bad)
const result = db.querySync('SELECT * FROM users');

// Non-blocking (good)
db.query('SELECT * FROM users', (err, result) => {});

HTTP requests:

// Blocking (bad - if such a function existed)
const response = http.getSync('https://api.example.com/data');

// Non-blocking (good)
fetch('https://api.example.com/data')
  .then(res => res.json())
  .then(data => console.log(data));

Why Does Blocking Happen?

Some operations in Node.js are inherently slow:

• Reading from disk (slower than RAM)

• Network requests (very slow)

• Database queries (slow)

• Complex calculations (time-consuming)

Node.js can't speed these up. But it can handle them without blocking the thread by delegating to background workers.

The Event Loop Revisited

Understanding the event loop explains the difference:

import fs from 'fs';

console.log('1');
fs.readFile('file.txt', () => {
  console.log('2');
});
console.log('3');

Output:

1
3
2

Here's what happens:

1. JavaScript starts
   - Logs "1"
   - Delegates file read (tells worker thread)
   - Logs "3"
   - No more code

2. Event loop checks: Is anything ready?
   - File read not done yet, nothing to do

3. Event loop checks: Is anything ready?
   - File is ready! Execute callback
   - Logs "2"

The callback waits in a queue until the main thread is free.

Async/Await: Cleaner Syntax

While callbacks are non-blocking, async/await is cleaner:

import fs from 'fs/promises';

// Using callbacks (non-blocking)
fs.readFile('file.txt', (err, data) => {
  console.log(data);
});

// Using async/await (still non-blocking!)
const data = await fs.readFile('file.txt');
console.log(data);

Async/await looks like synchronous code but it's non-blocking. When you await a slow operation, the function pauses, but the thread continues handling other requests.

Practical Examples

Bad: Synchronous (blocking)

import express from 'express';
import fs from 'fs';

const app = express();

app.get('/read-file', (req, res) => {
  const data = fs.readFileSync('large-file.txt'); // Blocks entire server
  res.send(data);
});

app.listen(3000);

Good: Asynchronous (non-blocking)

import express from 'express';
import fs from 'fs/promises';

const app = express();

app.get('/read-file', async (req, res) => {
  try {
    const data = await fs.readFile('large-file.txt');
    res.send(data);
  } catch (error) {
    res.status(500).send('Error reading file');
  }
});

app.listen(3000);

Bad: Database operations (blocking)

app.get('/users', (req, res) => {
  const users = db.querySync('SELECT * FROM users'); // Blocks server
  res.json(users);
});

Good: Database operations (non-blocking)

app.get('/users', async (req, res) => {
  const users = await db.query('SELECT * FROM users');
  res.json(users);
});

Mixing Blocking and Non-Blocking

If even one route is blocking, it can impact others:

import express from 'express';
import fs from 'fs';
import fs_async from 'fs/promises';

const app = express();

// This route blocks the entire server
app.get('/slow', (req, res) => {
  const data = fs.readFileSync('huge-file.txt'); // BLOCKS
  res.send(data);
});

// This route is fast but blocked by /slow
app.get('/fast', (req, res) => {
  res.send('Fast response');
});

// If someone calls /slow, requests to /fast must wait!

One blocking operation can bring down your entire server.

CPU-Intensive Code

Even pure JavaScript computations can block:

// Blocks the thread for 5 seconds
function expensiveCalculation() {
  let result = 0;
  for (let i = 0; i < 1_000_000_000; i++) {
    result += Math.sqrt(i);
  }
  return result;
}

app.get('/calculate', (req, res) => {
  const result = expensiveCalculation(); // Blocks thread
  res.json({ result });
});

For CPU-intensive work, use worker threads:

import { Worker } from 'worker_threads';
import path from 'path';

app.get('/calculate', (req, res) => {
  const worker = new Worker('./worker.js');
  worker.on('message', (result) => {
    res.json({ result });
  });
});

Common Mistakes

Mistake 1: Using readFileSync in a server

// Wrong - blocks entire server
app.get('/data', (req, res) => {
  const data = fs.readFileSync('file.txt');
  res.send(data);
});

// Right - non-blocking
app.get('/data', async (req, res) => {
  const data = await fs.readFile('file.txt');
  res.send(data);
});

Mistake 2: Not awaiting async operations

// Wrong - doesn't wait for query
app.get('/users', async (req, res) => {
  const users = db.query('SELECT * FROM users');
  res.json(users); // users is undefined
});

// Right - waits for query
app.get('/users', async (req, res) => {
  const users = await db.query('SELECT * FROM users');
  res.json(users);
});

Mistake 3: Blocking in middleware

// Wrong - blocking middleware
app.use((req, res, next) => {
  const user = db.querySync('SELECT * FROM users WHERE id=1');
  req.user = user;
  next();
});

// Right - non-blocking middleware
app.use(async (req, res, next) => {
  req.user = await db.query('SELECT * FROM users WHERE id=1');
  next();
});

Key Takeaways

• Blocking code stops execution until operations complete

• Non-blocking code delegates work and continues immediately

• In a server, one blocking operation can block all other requests

• Node.js provides non-blocking alternatives to synchronous functions

• Use async/await for cleaner non-blocking code

• Avoid .Sync methods (readFileSync, etc.) in servers

• Even one blocking route can cripple server performance

• CPU-intensive tasks should use worker threads

Embracing non-blocking code is what separates Node.js code that barely works from code that scales massively. Master this concept, and you've mastered Node.js.