0
# Process Exists
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: process-exists
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Module with TypeScript definitions)
9
- **Installation**: `npm install process-exists`
10
11
## Core Imports
12
13
```javascript
14
import { processExists, processExistsMultiple, filterExistingProcesses } from "process-exists";
15
```
16
17
For CommonJS (legacy):
18
19
```javascript
20
const { processExists, processExistsMultiple, filterExistingProcesses } = require("process-exists");
21
```
22
23
## Basic Usage
24
25
```javascript
26
import { processExists, processExistsMultiple, filterExistingProcesses } from "process-exists";
27
28
// Check if a single process exists
29
console.log(await processExists(process.pid)); // true (current process)
30
console.log(await processExists("nonexistent")); // false
31
32
// Check multiple processes at once
33
const results = await processExistsMultiple([process.pid, "chrome", "firefox"]);
34
console.log(results.get(process.pid)); // true
35
console.log(results.get("chrome")); // true/false depending on system
36
37
// Filter existing processes from a list
38
const existingProcesses = await filterExistingProcesses([process.pid, "chrome", "nonexistent"]);
39
console.log(existingProcesses); // [process.pid, "chrome"] (only existing ones)
40
```
41
42
## Platform Behavior
43
44
Process matching behavior varies by platform:
45
46
- **Linux**: Matches processes by name OR the first argument of the command line
47
- **Other platforms**: Matches processes only by name
48
49
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"`.
50
51
## Capabilities
52
53
### Single Process Check
54
55
Check if a single process exists by PID or name.
56
57
```javascript { .api }
58
/**
59
* Check if a process exists by PID or name
60
* @param input - The process ID (number) or name (string) to check
61
* @returns Promise that resolves to true if process exists, false otherwise
62
*/
63
function processExists(input: number | string): Promise<boolean>;
64
```
65
66
**Usage Examples:**
67
68
```javascript
69
// Check by PID
70
const exists = await processExists(1234);
71
72
// Check by process name
73
const chromeRunning = await processExists("chrome");
74
75
// Check current process (always true)
76
const currentExists = await processExists(process.pid);
77
```
78
79
### Multiple Process Check
80
81
Check multiple processes in a single operation, returning a Map with results.
82
83
```javascript { .api }
84
/**
85
* Check multiple processes if they exist
86
* @param input - Array of process IDs or names to check
87
* @returns Promise that resolves to a Map with process name/ID as key and boolean existence status as value
88
*/
89
function processExistsMultiple<T extends (number | string)>(
90
input: readonly T[]
91
): Promise<Map<T, boolean>>;
92
```
93
94
**Usage Examples:**
95
96
```javascript
97
// Check multiple processes
98
const processesToCheck = [process.pid, "chrome", "firefox", 9999];
99
const results = await processExistsMultiple(processesToCheck);
100
101
// Access results
102
results.get(process.pid); // true
103
results.get("chrome"); // true/false
104
results.get(9999); // false (assuming PID doesn't exist)
105
106
// Iterate over results
107
for (const [processName, exists] of results) {
108
console.log(`${processName}: ${exists ? 'running' : 'not running'}`);
109
}
110
```
111
112
### Process Filtering
113
114
Filter an array to only include processes that exist.
115
116
```javascript { .api }
117
/**
118
* Filter an array to only include processes that exist
119
* @param input - Array of process IDs or names to filter
120
* @returns Promise that resolves to filtered array containing only existing processes
121
*/
122
function filterExistingProcesses<T extends ReadonlyArray<number | string>>(
123
input: T
124
): Promise<T>;
125
```
126
127
**Usage Examples:**
128
129
```javascript
130
// Filter a mixed array
131
const candidates = [process.pid, "chrome", "nonexistent", "firefox"];
132
const running = await filterExistingProcesses(candidates);
133
// Result: [process.pid, "chrome", "firefox"] (only existing ones)
134
135
// Filter PIDs
136
const pids = [1, 1234, 5678, process.pid];
137
const runningPids = await filterExistingProcesses(pids);
138
console.log(runningPids); // Only PIDs that correspond to running processes
139
```
140
141
## Error Handling
142
143
All functions are async and may throw errors if:
144
- The underlying `ps-list` dependency fails to enumerate processes
145
- System permissions prevent process enumeration
146
- Invalid arguments are passed (though the functions are permissive with input types)
147
148
Errors from the underlying process enumeration will propagate as Promise rejections:
149
150
```javascript
151
try {
152
const exists = await processExists("some-process");
153
} catch (error) {
154
console.error("Failed to check process:", error.message);
155
}
156
```
157
158
## Dependencies
159
160
Process Exists depends on:
161
- **ps-list@^8.0.0**: Cross-platform process listing functionality
162
- **Node.js**: Requires Node.js ^12.20.0 || ^14.13.1 || >=16.0.0
163
164
## Performance Considerations
165
166
- All functions call `ps-list` internally to get the current process list
167
- For checking multiple processes, use `processExistsMultiple()` instead of multiple `processExists()` calls
168
- Process enumeration is a system-level operation that may be slower on systems with many running processes
169
- Results are not cached between calls