CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-process-exists

Check if a process is running by PID or name with cross-platform support

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Process Exists

Process Exists is a lightweight Node.js library that provides reliable cross-platform functionality to check if processes are running. It supports both process ID (PID) and process name checking, with specialized handling for different operating systems.

Package Information

  • Package Name: process-exists
  • Package Type: npm
  • Language: JavaScript (ES Module with TypeScript definitions)
  • Installation: npm install process-exists

Core Imports

import { processExists, processExistsMultiple, filterExistingProcesses } from "process-exists";

For CommonJS (legacy):

const { processExists, processExistsMultiple, filterExistingProcesses } = require("process-exists");

Basic Usage

import { processExists, processExistsMultiple, filterExistingProcesses } from "process-exists";

// Check if a single process exists
console.log(await processExists(process.pid)); // true (current process)
console.log(await processExists("nonexistent")); // false

// Check multiple processes at once
const results = await processExistsMultiple([process.pid, "chrome", "firefox"]);
console.log(results.get(process.pid)); // true
console.log(results.get("chrome")); // true/false depending on system

// Filter existing processes from a list
const existingProcesses = await filterExistingProcesses([process.pid, "chrome", "nonexistent"]);
console.log(existingProcesses); // [process.pid, "chrome"] (only existing ones)

Platform Behavior

Process matching behavior varies by platform:

  • Linux: Matches processes by name OR the first argument of the command line
  • Other platforms: Matches processes only by name

This means on Linux, a process named node running /usr/bin/node script.js can be found by searching for either "node" or "/usr/bin/node".

Capabilities

Single Process Check

Check if a single process exists by PID or name.

/**
 * Check if a process exists by PID or name
 * @param input - The process ID (number) or name (string) to check
 * @returns Promise that resolves to true if process exists, false otherwise
 */
function processExists(input: number | string): Promise<boolean>;

Usage Examples:

// Check by PID
const exists = await processExists(1234);

// Check by process name
const chromeRunning = await processExists("chrome");

// Check current process (always true)
const currentExists = await processExists(process.pid);

Multiple Process Check

Check multiple processes in a single operation, returning a Map with results.

/**
 * Check multiple processes if they exist
 * @param input - Array of process IDs or names to check  
 * @returns Promise that resolves to a Map with process name/ID as key and boolean existence status as value
 */
function processExistsMultiple<T extends (number | string)>(
  input: readonly T[]
): Promise<Map<T, boolean>>;

Usage Examples:

// Check multiple processes
const processesToCheck = [process.pid, "chrome", "firefox", 9999];
const results = await processExistsMultiple(processesToCheck);

// Access results
results.get(process.pid); // true
results.get("chrome"); // true/false
results.get(9999); // false (assuming PID doesn't exist)

// Iterate over results
for (const [processName, exists] of results) {
  console.log(`${processName}: ${exists ? 'running' : 'not running'}`);
}

Process Filtering

Filter an array to only include processes that exist.

/**
 * Filter an array to only include processes that exist
 * @param input - Array of process IDs or names to filter
 * @returns Promise that resolves to filtered array containing only existing processes
 */
function filterExistingProcesses<T extends ReadonlyArray<number | string>>(
  input: T
): Promise<T>;

Usage Examples:

// Filter a mixed array
const candidates = [process.pid, "chrome", "nonexistent", "firefox"];
const running = await filterExistingProcesses(candidates);
// Result: [process.pid, "chrome", "firefox"] (only existing ones)

// Filter PIDs
const pids = [1, 1234, 5678, process.pid];
const runningPids = await filterExistingProcesses(pids);
console.log(runningPids); // Only PIDs that correspond to running processes

Error Handling

All functions are async and may throw errors if:

  • The underlying ps-list dependency fails to enumerate processes
  • System permissions prevent process enumeration
  • Invalid arguments are passed (though the functions are permissive with input types)

Errors from the underlying process enumeration will propagate as Promise rejections:

try {
  const exists = await processExists("some-process");
} catch (error) {
  console.error("Failed to check process:", error.message);
}

Dependencies

Process Exists depends on:

  • ps-list@^8.0.0: Cross-platform process listing functionality
  • Node.js: Requires Node.js ^12.20.0 || ^14.13.1 || >=16.0.0

Performance Considerations

  • All functions call ps-list internally to get the current process list
  • For checking multiple processes, use processExistsMultiple() instead of multiple processExists() calls
  • Process enumeration is a system-level operation that may be slower on systems with many running processes
  • Results are not cached between calls

docs

index.md

tile.json