0
# set-blocking
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: set-blocking
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install set-blocking`
10

11
## Core Imports
12

13
```javascript
14
const setBlocking = require('set-blocking');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const setBlocking = require('set-blocking');
21

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

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

29
// Typically called before process.exit()
30
process.exit(0);
31
```
32

33
## Architecture
34

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

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

44
## Capabilities
45

46
### Set Blocking Mode
47

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

50
```javascript { .api }
51
/**
52
 * Sets blocking mode for stdout and stderr streams
53
 * @param {boolean} blocking - true to enable blocking mode, false to disable
54
 * @returns {undefined} - void function with no return value
55
 */
56
function setBlocking(blocking);
57
```
58

59
**Parameters:**
60
- `blocking` (boolean): Whether to enable (true) or disable (false) blocking mode for stdout and stderr streams
61

62
**Behavior:**
63
- Iterates through `process.stdout` and `process.stderr` streams
64
- For each stream, checks if it has a `_handle`, is a TTY, and supports `setBlocking`
65
- Calls `stream._handle.setBlocking(blocking)` when conditions are met
66
- Silently handles cases where conditions are not met (no errors thrown)
67

68
**Usage Examples:**
69

70
```javascript
71
const setBlocking = require('set-blocking');
72

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

79
// Disable blocking mode (optional - rarely needed)
80
setBlocking(false);
81
```
82

83
**Important Considerations:**
84

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

90
**Typical Usage Pattern:**
91

92
```javascript
93
const setBlocking = require('set-blocking');
94

95
// ... your application logic ...
96

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