Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/webpod/ps
A Node.js module for looking up running processes
https://github.com/webpod/ps
Last synced: about 12 hours ago
JSON representation
A Node.js module for looking up running processes
- Host: GitHub
- URL: https://github.com/webpod/ps
- Owner: webpod
- License: mit
- Created: 2024-03-19T16:50:54.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2024-11-10T06:53:43.000Z (7 days ago)
- Last Synced: 2024-11-10T07:31:19.698Z (7 days ago)
- Language: TypeScript
- Homepage:
- Size: 242 KB
- Stars: 11
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# @webpod/ps
> A Node.js module for looking up running processes. Originated from [neekey/ps](https://github.com/neekey/ps), [UmbraEngineering/ps](https://github.com/UmbraEngineering/ps) and completely reforged.
## Differences
* [x] Rewritten in TypeScript
* [x] CJS and ESM package entry points
* [x] `table-parser` replaced with `@webpod/ingrid` to handle some issues: [neekey/ps#76](https://github.com/neekey/ps/issues/76), [neekey/ps#62](https://github.com/neekey/ps/issues/62), [neekey/table-parser#11](https://github.com/neekey/table-parser/issues/11), [neekey/table-parser#18](https://github.com/neekey/table-parser/issues/18)
* [x] Provides promisified responses
* [x] Brings sync API
* [x] Builds a process tree
## Install
```bash
$ npm install @webpod/ps
```
## Internals
This module invokes different tools to get process list:
* `ps` for unix/mac: `ps -lx`
* [`wmic` for win runtimes](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic): `wmic process get ProcessId,CommandLine`.
## Usage
### lookup()
Searches for the process by the specified `pid`.
```ts
import {lookup} from '@webpod/ps'
// Both callback and promise styles are supported
const list = await lookup({pid: 12345})
// or
lookup({pid: 12345}, (err, list) => {
if (err) {
throw new Error(err)
}
const [found] = list
if (found) {
console.log('PID: %s, COMMAND: %s, ARGUMENTS: %s', found.pid, found.command, found.arguments)
} else {
console.log('No such process found!')
}
})
// or syncronously
const _list = lookup.sync({pid: 12345})
```
Define a query opts to filter the results by `command` and/or `arguments` predicates:
```ts
const list = await lookup({
command: 'node', // it will be used to build a regex
arguments: '--debug',
})
list.forEach(entry => {
console.log('PID: %s, COMMAND: %s, ARGUMENTS: %s', entry.pid, entry.command, entry.arguments);
})
```
Unix users can override the default `ps` arguments:
```ts
lookup({
command: 'node',
psargs: 'ux'
}, (err, resultList) => {
// ...
})
```
Specify the `ppid` option to filter the results by the parent process id (make sure that your custom `psargs` provides this output: `-l` or `-j` for instance)
```ts
lookup({
command: 'mongod',
psargs: '-l',
ppid: 82292
}, (err, resultList) => {
// ...
})
```
### tree()
Returns a child processes list by the specified parent `pid`. Some kind of shortcut for `lookup({ppid: pid})`.
```ts
import { tree } from '@webpod/ps'
const children = await tree(123)
/**
[
{pid: 124, ppid: 123},
{pid: 125, ppid: 123}
]
*/
```
To obtain all nested children, set `recursive` option to `true`:
```ts
const children = await tree({pid: 123, recursive: true})
/**
[
{pid: 124, ppid: 123},
{pid: 125, ppid: 123},
{pid: 126, ppid: 124},
{pid: 127, ppid: 124},
{pid: 128, ppid: 124},
{pid: 129, ppid: 125},
{pid: 130, ppid: 125},
]
*/
// or syncronously
const list = tree.sync({pid: 123, recursive: true})
```
### kill()
Eliminates the process by its `pid`.
```ts
import { kill } from '@webpod/ps'
kill('12345', (err, pid) => {
if (err) {
throw new Error(err)
} else {
console.log('Process %s has been killed!', pid)
}
})
```
Method `kill` also supports a `signal` option to be passed. It's only a wrapper of `process.kill()` with checking of that killing is finished after the method is called.
```ts
import { kill } from '@webpod/ps'
// Pass signal SIGKILL for killing the process without allowing it to clean up
kill('12345', 'SIGKILL', (err, pid) => {
if (err) {
throw new Error(err)
} else {
console.log('Process %s has been killed without a clean-up!', pid)
}
})
```
You can also use object notation to specify more opts:
```ts
kill( '12345', {
signal: 'SIGKILL',
timeout: 10, // will set up a ten seconds timeout if the killing is not successful
}, () => {})
```
Notice that the nodejs build-in `process.kill()` does not accept number as a signal, you will have to use string format.
## License
[MIT](./LICENSE)