Tree Kill

Tree Kill is a cross-platform Node.js library for terminating process trees by killing a parent process and all its descendant processes. It provides platform-specific implementations for Linux, macOS/Darwin, and Windows, offering both programmatic API and command-line interface with security features to prevent code injection vulnerabilities.

Package Information

• Package Name: tree-kill
• Package Type: npm
• Language: JavaScript
• Installation: npm install tree-kill

Core Imports

const kill = require('tree-kill');

ES Modules:

import kill from 'tree-kill';

TypeScript:

import kill from 'tree-kill';

Basic Usage

const kill = require('tree-kill');

// Kill a process tree with default SIGTERM signal
kill(1234);

// Kill with a specific signal
kill(1234, 'SIGKILL');

// Kill with callback for error handling
kill(1234, 'SIGTERM', function(err) {
    if (err) {
        console.log('Error:', err.message);
    } else {
        console.log('Process tree killed successfully');
    }
});

// Kill with callback but default signal
kill(1234, function(err) {
    if (err) {
        console.log('Error:', err.message);
    } else {
        console.log('Process tree killed successfully');
    }
});

Architecture

Tree Kill uses platform-specific process management commands to build and terminate process trees:

• Linux: Uses ps -o pid --no-headers --ppid PID to discover child processes
• macOS/Darwin: Uses pgrep -P PID to find child processes
• Windows: Uses taskkill /pid PID /T /F to kill the entire process tree at once

The library builds a complete process tree by recursively discovering all descendant processes, then systematically terminates them to ensure no orphaned processes remain.

Capabilities

Process Tree Termination

Kills a process and all its descendant processes across different operating systems.

/**
 * Kills process identified by pid and all its children
 * @param pid - Process ID to kill (required)
 * @param signal - Signal to send (optional, defaults to 'SIGTERM')
 * @param callback - Error-first callback (optional)
 */
function kill(pid: number, callback?: (error?: Error) => void): void;
function kill(pid: number, signal?: string | number, callback?: (error?: Error) => void): void;

Parameters:

• pid (number): The process ID of the root process to kill. Must be a valid integer.
• signal (string | number | null, optional): The signal to send to processes. Defaults to 'SIGTERM'. Can be any valid Node.js process signal (e.g., 'SIGKILL', 'SIGINT', 9, 15) or null to use the default signal.
• callback (function, optional): Error-first callback function called when the operation completes. Signature: (error?: Error) => void.

Behavior:

• Validates that pid is a number; throws/returns error if not
• Discovers all descendant processes using platform-specific commands
• Kills all processes in the tree, starting with children then parent
• On Windows, uses taskkill which handles the entire tree atomically
• On Unix-like systems, recursively discovers and kills each process individually
• Ignores ESRCH errors (process not found) as processes may exit during tree traversal

Error Handling:

• Throws Error("pid must be a number") if pid is not a valid number (when no callback provided)
• Calls callback with error if pid validation fails (when callback provided)
• Handles process-not-found errors gracefully during tree killing
• Platform-specific command failures are handled appropriately

Usage Examples:

const kill = require('tree-kill');

// Basic usage - kill with default SIGTERM
kill(1234);

// Kill with specific signal
kill(1234, 'SIGKILL');
kill(1234, 9); // Same as SIGKILL

// Async usage with callback
kill(1234, function(err) {
    if (err) {
        console.error('Failed to kill process tree:', err.message);
    } else {
        console.log('Process tree terminated successfully');
    }
});

// Kill with specific signal and callback
kill(1234, 'SIGTERM', function(err) {
    if (err) {
        console.error('Kill failed:', err.message);
    } else {
        console.log('Process tree killed with SIGTERM');
    }
});

// Kill with null signal (uses default) and callback
kill(1234, null, function(err) {
    if (err) {
        console.error('Kill failed:', err.message);
    } else {
        console.log('Process tree killed with default signal');
    }
});

// Error handling for invalid PID
try {
    kill('invalid-pid');
} catch (err) {
    console.error('Invalid PID:', err.message);
}

// Async error handling for invalid PID
kill('invalid-pid', function(err) {
    if (err) {
        console.error('Invalid PID:', err.message);
    }
});

Command Line Interface

Tree Kill provides a command-line interface for process tree termination.

# Kill process tree with default SIGTERM signal
tree-kill <pid>

# Kill process tree with specific signal
tree-kill <pid> <signal>

Parameters:

• <pid>: Process ID to kill (required)
• <signal>: Signal to send (optional, defaults to SIGTERM)

Examples:

# Kill process 1234 and its children with SIGTERM
tree-kill 1234

# Kill process 1234 and its children with SIGKILL
tree-kill 1234 SIGKILL

# Kill with numeric signal
tree-kill 1234 9

Error Handling:

• Exits with status code 1 on error
• Prints error messages to console
• Handles both synchronous errors (invalid PID) and asynchronous errors (kill failures)

Platform-Specific Behavior

Linux

• Uses ps -o pid --no-headers --ppid PID to find child processes
• Recursively builds process tree by querying each parent
• Kills processes individually using Node.js process.kill()
• Handles ESRCH errors gracefully when processes exit during traversal

macOS/Darwin

• Uses pgrep -P PID to find child processes
• Same recursive tree building and individual killing as Linux
• Optimized for macOS process management utilities

Windows

• Uses taskkill /pid PID /T /F command
• /T flag kills the process tree (parent and all descendants)
• /F flag forces termination
• Atomic operation - entire tree killed in one command
• Note: POSIX signal differentiation not supported on Windows

Security Features

• PID Validation: Strictly validates PID parameter to prevent code injection
• Integer Parsing: Converts PID to integer and validates it's a number
• Command Safety: Uses child_process.spawn/exec with validated parameters only
• Input Sanitization: Security fix in v1.2.2 prevents arbitrary code execution vulnerabilities

Error Types

interface TreeKillError extends Error {
    message: string;
    code?: string; // May include system error codes like 'ESRCH'
}

Common Errors:

• "pid must be a number": Invalid PID parameter provided
• "ESRCH": Process not found (handled gracefully during tree killing)
• Platform-specific command execution errors (rare, usually indicate system issues)

TypeScript Support

Tree Kill includes TypeScript definitions with function overloads for optional parameters:

declare function treeKill(pid: number, callback?: (error?: Error) => void): void;
declare function treeKill(pid: number, signal?: string | number, callback?: (error?: Error) => void): void;

declare namespace treeKill {}

export = treeKill;