# tinyps

> A library of utilities for dealing with system processes.

Latest version **0.5.0** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install tinyps
pnpm add tinyps
yarn add tinyps
bun add tinyps
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2026-09-23 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 14.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 9 |
| Author | James Garbutt |
| Maintainers | 43081j |
| Keywords | proc, process, tree-kill, ps-tree, tiny, kill, tree |

## Links

- npm: https://www.npmjs.com/package/tinyps
- Repository: https://github.com/tinylibs/tinyps
- Homepage: https://github.com/tinylibs/tinyps#readme
- Issues: https://github.com/tinylibs/tinyps/issues
- npm.io page: https://npm.io/package/tinyps

## Alternatives

- [postcss-color-hex-alpha](https://npm.io/package/postcss-color-hex-alpha.md) — 6.4M weekly downloads
- [randomcolor](https://npm.io/package/randomcolor.md) — 348.0K weekly downloads
- [bows](https://npm.io/package/bows.md) — 1.3K weekly downloads
- [ep_prefer_color_scheme](https://npm.io/package/ep_prefer_color_scheme.md) — 260 weekly downloads
- [coc-yank](https://npm.io/package/coc-yank.md) — 61 weekly downloads

## Recent versions

- 0.5.0 (latest) — 2026-09-23
- 0.2.0 — 2026-09-23

## README

# ⚙️ tinyps

A cross-platform library of utilities for dealing with system processes.

## Install

```sh
npm install tinyps
```

## Usage

```ts
import { killTree, getProcessTree } from 'tinyps';

// kill a process and everything it spawned
await killTree(child.pid);

// or inspect the tree first
const tree = await getProcessTree(child.pid);
console.log(tree.get(child.pid)); // [ 1234, 1235 ]
```

## API

### `killTree(pid, signal?)`

- `pid` (`number`) - process to kill, along with all of its descendants
- `signal` (`NodeJS.Signals`, optional) - signal to send, defaults to `SIGTERM`
- Returns `Promise<void>`

Note that `signal` is not supported on Windows, and will be ignored.

### `getProcessTree(pid)`

- `pid` (`number`) - process to build the tree from
- Returns `Promise<ProcessTree>`

### `isRunning(pid)`

- `pid` (`number`) - process to check
- Returns `boolean`

A zombie process is still in the process table, so this returns `true` for a
process which has exited but has not yet been released by its parent.

### `getDescendants(pid)`

- `pid` (`number`) - process to collect descendants of
- Returns `Promise<number[]>`

### `listProcesses()`

- Returns `Promise<ProcessInfo[]>`

### `getProcessInfo(pid)`

- `pid` (`number`) - process to look up
- Returns `Promise<ProcessInfo | undefined>`

### `findProcessesByName(name, options?)`

- `name` (`string`) - name to match against
- `options.loose` (`boolean`, optional) - match any name containing `name`, ignoring case
- Returns `Promise<ProcessInfo[]>`

Names come from the process' `argv[0]`, so a process which has renamed itself
(e.g. via `process.title`) matches its new name rather than its executable.

### `findProcessesByPort(port, options?)`

- `port` (`number`) - local port to match against
- `options.protocol` (`'tcp' | 'udp'`, optional) - only match sockets of this
  protocol, defaults to matching both
- Returns `Promise<ProcessInfo[]>`

Matches any process holding a socket bound to `port` locally, whether it is
listening or connected.

## License

MIT

---
_Source: https://npm.io/package/tinyps · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._