Node.js Memory Management

Understanding memory management helps build efficient Node.js applications. Here's what you need to know.

Memory Structure#

// V8 Memory Layout
/*
Heap:
├── New Space (Young Generation)
│   ├── Semi-space 1 (From)
│   └── Semi-space 2 (To)
└── Old Space (Old Generation)
    ├── Old Pointer Space
    ├── Old Data Space
    ├── Large Object Space
    ├── Code Space
    └── Map Space
*/

// Check memory usage
const used = process.memoryUsage();
console.log({
  rss: `${Math.round(used.rss / 1024 / 1024)}MB`,
  heapTotal: `${Math.round(used.heapTotal / 1024 / 1024)}MB`,
  heapUsed: `${Math.round(used.heapUsed / 1024 / 1024)}MB`,
  external: `${Math.round(used.external / 1024 / 1024)}MB`,
  arrayBuffers: `${Math.round(used.arrayBuffers / 1024 / 1024)}MB`,
});

// rss: Resident Set Size - total memory allocated
// heapTotal: V8's total heap size
// heapUsed: V8's used heap
// external: Memory used by C++ objects bound to JS
// arrayBuffers: Memory for ArrayBuffers and SharedArrayBuffers

Heap Configuration#

# Increase heap size (default ~1.5GB on 64-bit)
node --max-old-space-size=4096 app.js

# Set new space size
node --max-semi-space-size=64 app.js

# View V8 options
node --v8-options | grep -i heap

# Common flags
node --expose-gc                 # Expose global.gc()
node --trace-gc                  # Log GC events
node --max-old-space-size=8192  # 8GB heap

Garbage Collection#

// GC in V8
/*
Scavenge (Minor GC):
- Cleans New Space
- Fast, frequent
- Promotes surviving objects to Old Space

Mark-Sweep-Compact (Major GC):
- Cleans Old Space
- Slower, less frequent
- Can cause pauses
*/

// Force garbage collection (if --expose-gc)
if (global.gc) {
  global.gc();
}

// Monitor GC
const v8 = require('v8');

// Get heap statistics
const heapStats = v8.getHeapStatistics();
console.log({
  totalHeapSize: `${Math.round(heapStats.total_heap_size / 1024 / 1024)}MB`,
  usedHeapSize: `${Math.round(heapStats.used_heap_size / 1024 / 1024)}MB`,
  heapSizeLimit: `${Math.round(heapStats.heap_size_limit / 1024 / 1024)}MB`,
  mallocedMemory: `${Math.round(heapStats.malloced_memory / 1024 / 1024)}MB`,
});

// GC events via perf_hooks
const { PerformanceObserver } = require('perf_hooks');

const obs = new PerformanceObserver((list) => {
  const entry = list.getEntries()[0];
  console.log(`GC: ${entry.kind} - ${entry.duration.toFixed(2)}ms`);
});

obs.observe({ entryTypes: ['gc'] });

Memory Leaks#

// Common leak: Global variables
global.leakedData = []; // Never cleaned up

function processRequest(data) {
  global.leakedData.push(data); // Grows forever
}

// Common leak: Closures
function createLeak() {
  const largeData = new Array(1000000).fill('x');

  return function() {
    // largeData is retained even if not used
    console.log('Closure');
  };
}

const leaked = createLeak();

// Common leak: Event listeners
const EventEmitter = require('events');
const emitter = new EventEmitter();

function addListeners() {
  // Adding listener without removing
  emitter.on('event', () => {
    // Handler
  });
}

// Call repeatedly = memory leak
setInterval(addListeners, 1000);

// Fix: Remove listeners
function addListenersFixed() {
  const handler = () => {
    // Handler
    emitter.off('event', handler);
  };
  emitter.on('event', handler);
}

// Common leak: Timers
function leakyTimer() {
  const data = new Array(1000000).fill('x');

  setInterval(() => {
    console.log(data.length);
  }, 1000);
}

// Fix: Clear timers
function fixedTimer() {
  const data = new Array(1000000).fill('x');

  const interval = setInterval(() => {
    console.log(data.length);
  }, 1000);

  // Clear when done
  setTimeout(() => clearInterval(interval), 5000);
}

Detecting Leaks#

// Method 1: Monitor heap growth
let lastHeapUsed = 0;

setInterval(() => {
  const { heapUsed } = process.memoryUsage();
  const diff = heapUsed - lastHeapUsed;

  if (diff > 0) {
    console.log(`Heap grew by ${Math.round(diff / 1024)}KB`);
  }

  lastHeapUsed = heapUsed;
}, 5000);

// Method 2: Heap snapshots
const v8 = require('v8');
const fs = require('fs');

function takeHeapSnapshot() {
  const filename = `heap-${Date.now()}.heapsnapshot`;
  const snapshotStream = v8.writeHeapSnapshot(filename);
  console.log(`Heap snapshot written to ${snapshotStream}`);
}

// Take snapshots at different times
takeHeapSnapshot(); // Initial
setTimeout(takeHeapSnapshot, 60000); // After 1 minute

// Method 3: Using clinic.js
// npm install -g clinic
// clinic doctor -- node app.js
// clinic heapprofile -- node app.js

Memory-Efficient Patterns#

// Use streams for large data
const fs = require('fs');

// Bad: Load entire file
function processFileBad(path) {
  const content = fs.readFileSync(path, 'utf8');
  return content.split('\n').length;
}

// Good: Stream file
async function processFileGood(path) {
  const stream = fs.createReadStream(path);
  let lines = 0;

  for await (const chunk of stream) {
    lines += chunk.toString().split('\n').length - 1;
  }

  return lines;
}

// Object pooling
class ObjectPool {
  constructor(createFn, size = 10) {
    this.createFn = createFn;
    this.pool = Array.from({ length: size }, createFn);
  }

  acquire() {
    return this.pool.pop() || this.createFn();
  }

  release(obj) {
    // Reset object state
    this.pool.push(obj);
  }
}

const bufferPool = new ObjectPool(
  () => Buffer.alloc(1024),
  100
);

// WeakMap for metadata
const metadata = new WeakMap();

function processObject(obj) {
  metadata.set(obj, { processed: true });
}
// When obj is GC'd, metadata is also cleaned

// Avoid creating objects in loops
// Bad
function processBad(items) {
  return items.map(item => ({
    id: item.id,
    name: item.name,
  }));
}

// Good: Reuse objects when possible
function processGood(items, output = []) {
  output.length = items.length;

  for (let i = 0; i < items.length; i++) {
    if (!output[i]) output[i] = {};
    output[i].id = items[i].id;
    output[i].name = items[i].name;
  }

  return output;
}

Buffer Management#

// Buffer allocation
// Buffer.alloc - Zero-filled, safe
const safe = Buffer.alloc(1024);

// Buffer.allocUnsafe - May contain old data, faster
const unsafe = Buffer.allocUnsafe(1024);

// Buffer.allocUnsafeSlow - No pooling
const slow = Buffer.allocUnsafeSlow(1024);

// Buffer pooling
const POOL_SIZE = 8 * 1024; // 8KB
const pool = Buffer.allocUnsafe(POOL_SIZE);
let offset = 0;

function getBuffer(size) {
  if (offset + size > POOL_SIZE) {
    offset = 0;
  }

  const buffer = pool.slice(offset, offset + size);
  offset += size;
  return buffer;
}

// Release large buffers
function processLargeBuffer(size) {
  let buffer = Buffer.alloc(size);

  // Process buffer...

  buffer = null; // Allow GC
  global.gc?.(); // Force GC if available
}

Monitoring in Production#

// Memory monitoring class
class MemoryMonitor {
  constructor(options = {}) {
    this.threshold = options.threshold || 0.9;
    this.interval = options.interval || 30000;
    this.onWarning = options.onWarning || console.warn;
  }

  start() {
    this.intervalId = setInterval(() => {
      this.check();
    }, this.interval);
  }

  stop() {
    clearInterval(this.intervalId);
  }

  check() {
    const { heapUsed, heapTotal } = process.memoryUsage();
    const usage = heapUsed / heapTotal;

    if (usage > this.threshold) {
      this.onWarning({
        message: 'High memory usage',
        usage: `${(usage * 100).toFixed(1)}%`,
        heapUsed: `${Math.round(heapUsed / 1024 / 1024)}MB`,
        heapTotal: `${Math.round(heapTotal / 1024 / 1024)}MB`,
      });
    }

    return { usage, heapUsed, heapTotal };
  }
}

// Usage
const monitor = new MemoryMonitor({
  threshold: 0.85,
  interval: 60000,
  onWarning: (data) => {
    console.error('Memory warning:', data);
    // Alert monitoring system
  },
});

monitor.start();

// Graceful shutdown on OOM
process.on('warning', (warning) => {
  if (warning.name === 'MaxListenersExceededWarning') {
    console.error('Possible memory leak:', warning);
  }
});

Heap Dump Analysis#

// Generate heap dump
const v8 = require('v8');

// Write snapshot to file
v8.writeHeapSnapshot();

// Or using heapdump module
const heapdump = require('heapdump');

heapdump.writeSnapshot((err, filename) => {
  console.log('Heap dump written to', filename);
});

// Trigger dump on SIGUSR2
process.on('SIGUSR2', () => {
  heapdump.writeSnapshot();
});

// Analyze in Chrome DevTools:
// 1. Open DevTools
// 2. Go to Memory tab
// 3. Load snapshot
// 4. Compare snapshots to find leaks

Best Practices#

Prevention:
✓ Clear references when done
✓ Remove event listeners
✓ Clear timers and intervals
✓ Use WeakMap/WeakSet for caches

Monitoring:
✓ Track memory usage over time
✓ Set up alerts for high usage
✓ Take periodic heap snapshots
✓ Monitor GC frequency

Optimization:
✓ Use streams for large data
✓ Pool frequently created objects
✓ Avoid closures capturing large data
✓ Process data in chunks

Node.js memory management relies on V8's garbage collector. Prevent leaks by cleaning up references, use streams for large data, and monitor memory usage in production. Regular heap snapshots help identify leaks before they cause issues.