# @tapjs/processinfo

> A Node.js loader to track processes and which JavaScript files they load.

Latest version **3.1.12** (published 2026-05-15) · BlueOak-1.0.0 license · 0 weekly downloads

## Install

```sh
npm install @tapjs/processinfo
pnpm add @tapjs/processinfo
yarn add @tapjs/processinfo
bun add @tapjs/processinfo
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.12 |
| Published | 2026-05-15 |
| First published | 2022-11-17 |
| Weekly downloads | 0 |
| License | BlueOak-1.0.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16.17 |
| Dependencies | 5 |
| Unpacked size | 407 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Maintainers | ljharb, isaacs |

## Links

- npm: https://www.npmjs.com/package/@tapjs/processinfo
- Repository: https://github.com/tapjs/processinfo
- Homepage: https://github.com/tapjs/processinfo#readme
- Issues: https://github.com/tapjs/processinfo/issues
- npm.io page: https://npm.io/package/@tapjs/processinfo

## Dependencies (5)

- [uuid](https://npm.io/package/uuid.md) ^14.0.0
- [pirates](https://npm.io/package/pirates.md) ^4.0.5
- [signal-exit](https://npm.io/package/signal-exit.md) ^4.0.2
- [process-on-spawn](https://npm.io/package/process-on-spawn.md) ^1.0.0
- [node-options-to-argv](https://npm.io/package/node-options-to-argv.md) ^1.0.0

## Recent versions

- 3.1.12 (latest) — 2026-05-15
- 3.1.11 — 2026-05-12
- 3.1.10 — 2026-05-01
- 3.1.9 — 2025-11-26
- 3.1.8 — 2024-06-05
- 3.1.7 — 2024-03-08
- 3.1.6 — 2023-11-03
- 3.1.5 — 2023-10-16
- 3.1.4 — 2023-10-01
- 3.1.3 — 2023-09-30
- 3.1.2 — 2023-09-27
- 3.1.1 — 2023-09-13
- 3.1.0 — 2023-09-10
- 3.0.2 — 2023-09-08
- 3.0.1 — 2023-09-08
- … 42 more at https://npm.io/package/@tapjs/processinfo/versions

## README

# @tapjs/processinfo

A Node.js loader to track processes and which JavaScript files they load.

After the process has run, all wrapped process info is dumped to
`.tap/processinfo`.

The exported object can also be used to spawn processes, clear the
processinfo data, or load the processinfo data.

## USAGE

Run the top level process with a `--loader` or `--require` argument to
track all Node.js child processes.

```sh
# wrap both CommonJS and ESM, node versions less than 20.6
node --loader=@tapjs/processinfo/loader file.js

# for node versions 20.6 and higher:
node --import=@tapjs/processinfo/import
```

To spawn a wrapped process from JavaScript, you can run:

```js
import {
  spawn,
  exec,
  execFile,
  execSync,
  execFileSync,
  fork,
} from '@tapjs/processinfo'
// any of these will work
const childProcess = spawn(cmd, args, options)
const childProcess = exec(cmd, options, callback)
const childProcess = execFile(cmd, options, callback)
const childProcess = spawnSync(cmd, args, options)
const childProcess = execSync(cmd, options)
const childProcess = execFileSync(cmd, options)
const childProcess = fork(cmd, options)
```

The `cmd` and `args` parameters are identical to the methods from the
Node.js `child_process` module. The `options` parameter is also identical,
but may also include an `externalID` field, which if set to a string, will
be used as the processinfo `externalID`.

If you just use the normal `spawn`/`exec` methods from the Node.js
`child_process` module, then the relevant environment variables will still
be tracked, unless explicitly set to `''` or some other value.

### Important

In order to properly track `lineLengths` (required for coverage
reporting on source mapped files), `@tapjs/processinfo` must be
the **last** loader specified on the command line, so that it can
get access to the transpiled source that Node.js actually
executes.

### Interacting with Process Info

To load the process info data, use the exported `ProcessInfo` class.

```js
import { ProcessInfo } from '@tapjs/processinfo'

// returns
// {
//   roots: Set([ProcessInfo.Node, ...]) for each root process group
//   files: Map({ filename => Set([ProcessInfo.Node, ...]) }),
//   externalIDs: Map({ externalID => ProcessInfo.Node }),
//   uuids: Map({ uuid => ProcessInfo.Node }),
// }
// A ProcessInfo.Node looks like:
// {
//   date: iso date string,
//   argv,
//   execArgv,
//   cwd,
//   pid,
//   ppid,
//   uuid,
//   externalID,
//   parent: <ProcessInfo.Node or null for root node>,
//   root: <ProcessInfo.Node>,
//   children: [ProcessInfo.Node, ...],
//   descendants: [ProcessInfo.Node, ...],
//   files: [ filename, ... ],
//   code: unix exit code,
//   signal: terminating signal or null,
//   runtime: high resolution run time in ms,
// }
const processInfoDB = await ProcessInfo.load()
// say we wanted to find all the files loaded by the process 'foo'
const proc = processInfoDB.externalIDs.get('foo')
console.error(`Files loaded by process named 'foo':`, proc.files)

// now let's find all any other named processes that loaded them
for (const f of proc.files) {
  for (const otherProc of processInfoDB.files.get(f)) {
    // walk up the tree looking for a named process
    for (let parent = otherProc; parent; parent = parent.parent) {
      if (parent.externalID && parent !== proc) {
        console.error(`Also loaded by process ${parent.externalID}`)
      }
    }
  }
}
```

Note: unless there has been a previous wrapped process run, nothing will be
present in the data. That is, `data.root` will be null, and all the maps
will be empty.

## Controlling Coverage

To disable coverage entirely, set
`_TAPJS_PROCESSINFO_COVERAGE_=0` in the environment.

To exclude certain file paths from coverage with a pattern, set
the `_TAPJS_PROCESSINFO_COV_EXCLUDE_` to a regular expression
string. Note that processinfo will _never_ provide coverage for a
file that's excluded from process file tracking.

To exclude specific individual file paths from coverage, set the
`_TAPJS_PROCESSINFO_COV_EXCLUDE_FILES_` to a `\n` delimited
set of file paths.

To include only a specific set of files for coverage (as with
node-tap's `coverage-map` option), set
`_TAPJS_PROCESSINFO_COV_FILES_` to a `\n` delimited list of the
files to include. These will have their coverage reported even if
they would be excluded by the `_TAPJS_PROCESSINFO_COV_EXCLUDE_`
regexp or `_TAPJS_PROCESSINFO_COV_EXCLUDE_FILES_` list.

Note that coverage _instrumentation_ is by necessity enabled for
all files, but it's only written to disk if the file (or any of
its sources, if it has a sourcemap) is included.

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