or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-human-signals

Human-friendly process signals mapping with metadata and descriptions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/human-signals@8.0.x

To install, run

npx @tessl/cli install tessl/npm-human-signals@8.0.0

index.mddocs/

Human Signals

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.

Package Information

  • Package Name: human-signals
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install human-signals

Core Imports

import { signalsByName, signalsByNumber } from "human-signals";

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

Basic Usage

import { signalsByName, signalsByNumber } from "human-signals";

// Access signal by name
console.log(signalsByName.SIGINT);
// {
//   name: 'SIGINT', 
//   number: 2,
//   description: 'User interruption with CTRL-C',
//   supported: true,
//   action: 'terminate', 
//   forced: false,
//   standard: 'ansi'
// }

// Access signal by number
console.log(signalsByNumber[15]);
// {
//   name: 'SIGTERM',
//   number: 15, 
//   description: 'Termination',
//   supported: true,
//   action: 'terminate',
//   forced: false,
//   standard: 'ansi'
// }

// List all supported signals
const supportedSignals = Object.values(signalsByName)
  .filter(signal => signal.supported);
console.log(supportedSignals.length, 'supported signals');

Capabilities

Signal Name Mapping

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

const signalsByName: { [SignalNameType in SignalName]: Signal };

Signal Number Mapping

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

const signalsByNumber: { [SignalNumberType in SignalNumber]: Signal };

Types

interface Signal {
  /** Standard name of the signal, for example 'SIGINT' */
  name: SignalName;
  /** Code number of the signal, for example 2 */
  number: SignalNumber;
  /** Human-friendly description for the signal */
  description: string;
  /** Whether the current OS can handle this signal in Node.js */
  supported: boolean;
  /** What is the default action for this signal when it is not handled */
  action: SignalAction;
  /** Whether the signal's default action cannot be prevented */
  forced: boolean;
  /** Which standard defined that signal */
  standard: SignalStandard;
}

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

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

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

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

Signal Properties Explained

Action Types

  • terminate: Process is terminated (can be caught and handled)
  • core: Process is terminated and core dump is created
  • ignore: Signal is ignored by default
  • pause: Process is paused/stopped
  • unpause: Process is resumed from pause

Standards

  • ansi: Defined by ANSI C standard
  • posix: Defined by POSIX standard
  • bsd: Defined by BSD Unix
  • systemv: Defined by System V Unix
  • other: Non-standard or other origin

Forced Signals

Some signals have default actions that cannot be prevented (marked as forced: true):

  • SIGKILL - Cannot be caught, blocked, or ignored (forced termination)
  • SIGSTOP - Cannot be caught, blocked, or ignored (forced pause)
  • SIGCONT - Cannot be caught, blocked, or ignored (forced resume from pause)

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

Signal Coverage

This package provides comprehensive coverage of process signals including:

  • Standard signals: Traditional Unix signals (SIGHUP, SIGINT, SIGTERM, etc.)
  • Realtime signals: POSIX realtime signals (SIGRT1 through SIGRT31)
  • Platform-specific signals: OS-specific signals like SIGBREAK (Windows)

Cross-Platform Compatibility

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.

Common Use Cases

Process Management:

import { signalsByName } from "human-signals";

// Check if a signal is supported before setting up handler
if (signalsByName.SIGTERM.supported) {
  process.on('SIGTERM', () => {
    console.log(`Received ${signalsByName.SIGTERM.description}`);
    // Graceful shutdown logic
  });
}

Signal Information Display:

import { signalsByNumber } from "human-signals";

// Display human-friendly information about a signal number
function describeSignal(signum) {
  const signal = signalsByNumber[signum];
  if (signal) {
    return `${signal.name}: ${signal.description} (${signal.standard} standard)`;
  }
  return `Unknown signal: ${signum}`;
}

Error Handling Context:

import { signalsByNumber } from "human-signals";

process.on('exit', (code) => {
  if (code > 128) {
    const signum = code - 128;
    const signal = signalsByNumber[signum];
    if (signal) {
      console.log(`Process terminated by ${signal.name}: ${signal.description}`);
    }
  }
});