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