0
# Human Signals
1

2
Human Signals provides comprehensive mapping of Unix process signals with human-friendly descriptions and metadata. It enhances Node.js's built-in `os.constants.signals` by providing additional context like descriptions, default behaviors, cross-platform support information, and which standard defined each signal.
3

4
## Package Information
5

6
- **Package Name**: human-signals
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install human-signals`
10

11
## Core Imports
12

13
```javascript
14
import { signalsByName, signalsByNumber } from "human-signals";
15
```
16

17
This package is an ES Module. It must be loaded using an `import` or `import()` statement, not `require()`.
18

19
## Basic Usage
20

21
```javascript
22
import { signalsByName, signalsByNumber } from "human-signals";
23

24
// Access signal by name
25
console.log(signalsByName.SIGINT);
26
// {
27
//   name: 'SIGINT', 
28
//   number: 2,
29
//   description: 'User interruption with CTRL-C',
30
//   supported: true,
31
//   action: 'terminate', 
32
//   forced: false,
33
//   standard: 'ansi'
34
// }
35

36
// Access signal by number
37
console.log(signalsByNumber[15]);
38
// {
39
//   name: 'SIGTERM',
40
//   number: 15, 
41
//   description: 'Termination',
42
//   supported: true,
43
//   action: 'terminate',
44
//   forced: false,
45
//   standard: 'ansi'
46
// }
47

48
// List all supported signals
49
const supportedSignals = Object.values(signalsByName)
50
  .filter(signal => signal.supported);
51
console.log(supportedSignals.length, 'supported signals');
52
```
53

54
## Capabilities
55

56
### Signal Name Mapping
57

58
Provides an object mapping signal names to signal objects with complete metadata.
59

60
```typescript { .api }
61
const signalsByName: { [SignalNameType in SignalName]: Signal };
62
```
63

64
### Signal Number Mapping
65

66
Provides an object mapping signal numbers to signal objects with complete metadata.
67

68
```typescript { .api }
69
const signalsByNumber: { [SignalNumberType in SignalNumber]: Signal };
70
```
71

72
## Types
73

74
```typescript { .api }
75
interface Signal {
76
  /** Standard name of the signal, for example 'SIGINT' */
77
  name: SignalName;
78
  /** Code number of the signal, for example 2 */
79
  number: SignalNumber;
80
  /** Human-friendly description for the signal */
81
  description: string;
82
  /** Whether the current OS can handle this signal in Node.js */
83
  supported: boolean;
84
  /** What is the default action for this signal when it is not handled */
85
  action: SignalAction;
86
  /** Whether the signal's default action cannot be prevented */
87
  forced: boolean;
88
  /** Which standard defined that signal */
89
  standard: SignalStandard;
90
}
91

92
type SignalAction = 'terminate' | 'core' | 'ignore' | 'pause' | 'unpause';
93

94
type SignalStandard = 'ansi' | 'posix' | 'bsd' | 'systemv' | 'other';
95

96
type SignalName = 
97
  | 'SIGHUP' | 'SIGINT' | 'SIGQUIT' | 'SIGILL' | 'SIGTRAP' | 'SIGABRT' 
98
  | 'SIGIOT' | 'SIGBUS' | 'SIGEMT' | 'SIGFPE' | 'SIGKILL' | 'SIGUSR1' 
99
  | 'SIGSEGV' | 'SIGUSR2' | 'SIGPIPE' | 'SIGALRM' | 'SIGTERM' | 'SIGSTKFLT' 
100
  | 'SIGCHLD' | 'SIGCLD' | 'SIGCONT' | 'SIGSTOP' | 'SIGTSTP' | 'SIGTTIN' 
101
  | 'SIGBREAK' | 'SIGTTOU' | 'SIGURG' | 'SIGXCPU' | 'SIGXFSZ' | 'SIGVTALRM' 
102
  | 'SIGPROF' | 'SIGWINCH' | 'SIGIO' | 'SIGPOLL' | 'SIGINFO' | 'SIGPWR' 
103
  | 'SIGSYS' | 'SIGUNUSED' | 'SIGRT1' | 'SIGRT2' | 'SIGRT3' | 'SIGRT4' 
104
  | 'SIGRT5' | 'SIGRT6' | 'SIGRT7' | 'SIGRT8' | 'SIGRT9' | 'SIGRT10' 
105
  | 'SIGRT11' | 'SIGRT12' | 'SIGRT13' | 'SIGRT14' | 'SIGRT15' | 'SIGRT16' 
106
  | 'SIGRT17' | 'SIGRT18' | 'SIGRT19' | 'SIGRT20' | 'SIGRT21' | 'SIGRT22' 
107
  | 'SIGRT23' | 'SIGRT24' | 'SIGRT25' | 'SIGRT26' | 'SIGRT27' | 'SIGRT28' 
108
  | 'SIGRT29' | 'SIGRT30' | 'SIGRT31';
109

110
type SignalNumber = 
111
  | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 
112
  | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 
113
  | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 
114
  | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64;
115
```
116

117
## Signal Properties Explained
118

119
### Action Types
120
- **`terminate`**: Process is terminated (can be caught and handled)
121
- **`core`**: Process is terminated and core dump is created
122
- **`ignore`**: Signal is ignored by default
123
- **`pause`**: Process is paused/stopped
124
- **`unpause`**: Process is resumed from pause
125

126
### Standards
127
- **`ansi`**: Defined by ANSI C standard
128
- **`posix`**: Defined by POSIX standard  
129
- **`bsd`**: Defined by BSD Unix
130
- **`systemv`**: Defined by System V Unix
131
- **`other`**: Non-standard or other origin
132

133
### Forced Signals
134
Some signals have default actions that cannot be prevented (marked as `forced: true`):
135
- `SIGKILL` - Cannot be caught, blocked, or ignored (forced termination)
136
- `SIGSTOP` - Cannot be caught, blocked, or ignored (forced pause)
137
- `SIGCONT` - Cannot be caught, blocked, or ignored (forced resume from pause)
138

139
These signals bypass normal signal handling mechanisms and their default actions always execute.
140

141
### Signal Coverage
142
This package provides comprehensive coverage of process signals including:
143
- **Standard signals**: Traditional Unix signals (SIGHUP, SIGINT, SIGTERM, etc.)
144
- **Realtime signals**: POSIX realtime signals (SIGRT1 through SIGRT31)
145
- **Platform-specific signals**: OS-specific signals like SIGBREAK (Windows)
146

147
### Cross-Platform Compatibility
148
The `supported` property indicates whether the current operating system supports the signal in Node.js using `process.on(name, handler)`. Signal numbers may vary between operating systems, but this package handles OS-specific mappings automatically using Node.js's `os.constants.signals`.
149

150
## Common Use Cases
151

152
**Process Management**:
153
```javascript
154
import { signalsByName } from "human-signals";
155

156
// Check if a signal is supported before setting up handler
157
if (signalsByName.SIGTERM.supported) {
158
  process.on('SIGTERM', () => {
159
    console.log(`Received ${signalsByName.SIGTERM.description}`);
160
    // Graceful shutdown logic
161
  });
162
}
163
```
164

165
**Signal Information Display**:
166
```javascript
167
import { signalsByNumber } from "human-signals";
168

169
// Display human-friendly information about a signal number
170
function describeSignal(signum) {
171
  const signal = signalsByNumber[signum];
172
  if (signal) {
173
    return `${signal.name}: ${signal.description} (${signal.standard} standard)`;
174
  }
175
  return `Unknown signal: ${signum}`;
176
}
177
```
178

179
**Error Handling Context**:
180
```javascript
181
import { signalsByNumber } from "human-signals";
182

183
process.on('exit', (code) => {
184
  if (code > 128) {
185
    const signum = code - 128;
186
    const signal = signalsByNumber[signum];
187
    if (signal) {
188
      console.log(`Process terminated by ${signal.name}: ${signal.description}`);
189
    }
190
  }
191
});
192
```