@webpod/ps

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

Features

• Written in TypeScript, ships with types
• CJS and ESM entry points
• Promise and callback API, sync variants
• Process tree traversal by parent pid
• Uses @webpod/ingrid instead of table-parser (neekey/ps#76, neekey/ps#62)

Install

npm install @webpod/ps

Internals

Platform	Command
Unix / macOS	ps -eo pid,ppid,args
Windows (kernel >= 26000)	pwsh -NoProfile -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine | ConvertTo-Json -Compress"
Windows (kernel < 26000)	wmic process get ProcessId,CommandLine

API

lookup(query?, callback?)

Returns a list of processes matching the query.

import { lookup } from '@webpod/ps'

// Find by pid
const list = await lookup({ pid: 12345 })
// [{ pid: '12345', ppid: '123', command: '/usr/bin/node', arguments: ['server.js', '--port=3000'] }]

// Filter by command and/or arguments (treated as RegExp)
const nodes = await lookup({ command: 'node', arguments: '--debug' })

// Filter by parent pid
const children = await lookup({ ppid: 82292 })

// Synchronous
const all = lookup.sync()

On Unix, you can override the default ps arguments via psargs:

const list = await lookup({ command: 'node', psargs: '-eo pid,ppid,comm' })

Callback style is also supported:

lookup({ pid: 12345 }, (err, list) => { /* ... */ })

tree(opts?, callback?)

Returns child processes of a given parent pid.

import { tree } from '@webpod/ps'

// Direct children
const children = await tree(123)
// [
//   { pid: '124', ppid: '123', command: 'node', arguments: ['worker.js'] },
//   { pid: '125', ppid: '123', command: 'node', arguments: ['worker.js'] }
// ]

// All descendants
const all = await tree({ pid: 123, recursive: true })
// [
//   { pid: '124', ppid: '123', ... },
//   { pid: '125', ppid: '123', ... },
//   { pid: '126', ppid: '124', ... },
//   { pid: '127', ppid: '125', ... }
// ]

// Synchronous
const list = tree.sync({ pid: 123, recursive: true })

kill(pid, opts?, callback?)

Kills a process and waits for it to exit. The returned promise resolves once the process is confirmed dead, or rejects on timeout.

import { kill } from '@webpod/ps'

// Sends SIGTERM, polls until the process is gone (default timeout 30s)
await kill(12345)

// With signal
await kill(12345, 'SIGKILL')

// With custom timeout (seconds) and polling interval (ms)
await kill(12345, { signal: 'SIGKILL', timeout: 10, interval: 250 })

// With callback
await kill(12345, (err, pid) => {
  // called when the process is confirmed dead or timeout is reached
})

License

MIT