set-blocking

set-blocking is a Node.js utility that controls terminal stdio and stderr blocking behavior to prevent output truncation. It addresses a specific Node.js bug (#6456) where terminal output can be truncated on newer versions of Node.js (0.12+) when process.exit() is called.

Package Information

• Package Name: set-blocking
• Package Type: npm
• Language: JavaScript
• Installation: npm install set-blocking

Core Imports

const setBlocking = require('set-blocking');

Basic Usage

const setBlocking = require('set-blocking');

// Enable blocking mode to prevent output truncation
setBlocking(true);

// Your application logic here
console.log('This output will not be truncated');
console.error('Stderr output will also be complete');

// Typically called before process.exit()
process.exit(0);

Architecture

set-blocking works by directly manipulating Node.js internal stream handles:

• Stream Targeting: Operates on process.stdout and process.stderr streams
• Handle Access: Accesses the internal _handle property of each stream
• TTY Detection: Only affects TTY (terminal) streams via stream.isTTY check
• Blocking Control: Calls the native setBlocking() method on stream handles
• Graceful Degradation: Silently ignores streams without blocking support
• Process-wide Effect: Changes affect all subsequent output in the current process

Capabilities

Set Blocking Mode

Controls the blocking behavior of stdout and stderr streams to ensure complete terminal output.

/**
 * Sets blocking mode for stdout and stderr streams
 * @param {boolean} blocking - true to enable blocking mode, false to disable
 * @returns {undefined} - void function with no return value
 */
function setBlocking(blocking);

Parameters:

• blocking (boolean): Whether to enable (true) or disable (false) blocking mode for stdout and stderr streams

Behavior:

• Iterates through process.stdout and process.stderr streams
• For each stream, checks if it has a _handle, is a TTY, and supports setBlocking
• Calls stream._handle.setBlocking(blocking) when conditions are met
• Silently handles cases where conditions are not met (no errors thrown)

Usage Examples:

const setBlocking = require('set-blocking');

// Enable blocking mode before outputting large amounts of data
setBlocking(true);
for (let i = 0; i < 10000; i++) {
  console.log(`Line ${i}: Some important data that must not be truncated`);
}

// Disable blocking mode (optional - rarely needed)
setBlocking(false);

Important Considerations:

• Global Side Effects: This function affects all subsequent output to stdout and stderr in the current process. Use with caution in libraries.
• TTY Only: Only affects TTY (terminal) streams. File redirects and pipes are unaffected.
• Process Exit: Most commonly used before process.exit() to ensure all output is flushed.
• Cross-Platform: Gracefully degrades on platforms where setBlocking is not available.

Typical Usage Pattern:

const setBlocking = require('set-blocking');

// ... your application logic ...

// Before exiting, ensure all output is complete
setBlocking(true);
console.log('Final output that must be seen');
process.exit(0);