@webpod/ps

A Node.js module for looking up running processes. Originated from neekey/ps, UmbraEngineering/ps and completely reforged.

Differences

• Rewritten in TypeScript
• CJS and ESM package entry points
• table-parser replaced with @webpod/ingrid to handle some issues: neekey/ps#76, neekey/ps#62, neekey/table-parser#11, neekey/table-parser#18
• Provides promisified responses
• Brings sync API
• Builds a process tree

Install

$ npm install @webpod/ps

Internals

This module invokes different tools to get process list:

• ps for unix/mac: ps -lx
• wmic for win runtimes: wmic process get ProcessId,CommandLine.

Usage

lookup()

Searches for the process by the specified pid.

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:

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:

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)

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}).

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:

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.

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.

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:

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