Registry / testing / istanbul-lib-processinfo

istanbul-lib-processinfo

JSON →
library3.0.0jsnpmunverified

istanbul-lib-processinfo is a foundational utility library within the Istanbul.js ecosystem, primarily designed to manage the `processinfo` folder utilized by NYC (Yet Another JavaScript Code Coverage Tool). It provides an API for creating and interacting with `ProcessInfo` objects, which represent data about individual processes, and a `ProcessDB` class for aggregating and managing collections of these files. Key functionalities include saving process information to disk, building hierarchical process trees, and merging coverage maps from multiple processes. The current stable version is 3.0.0, which notably requires Node.js 20 or 22+ due to dependency updates. While not explicitly tied to a strict release cadence, major versions are typically released to align with Node.js LTS cycles or significant internal architectural changes, making it a stable component for tools consuming NYC's coverage data. Its primary differentiator is its deep integration with NYC's internal data structures, offering a robust way to programmatically interact with coverage data across processes.

npm install istanbul-lib-processinfo
INSTALL
IMPORT
SIG · ISTANBUL-LIB-PROCE
I
istanbul-lib-processinfo
testingjavascriptv3.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ProcessInfo
import { ProcessInfo } from 'istanbul-lib-processinfo';
const ProcessInfo = require('istanbul-lib-processinfo').ProcessInfo;
ESM named imports are the modern and preferred way to access classes since v3, especially with Node.js 20+.
ProcessDB
import { ProcessDB } from 'istanbul-lib-processinfo';
const ProcessDB = require('istanbul-lib-processinfo').ProcessDB;
While CommonJS `require` might still function via compatibility shims, direct ESM named imports align with the library's Node.js 20+ requirement and modern best practices.

This quickstart demonstrates how to instantiate `ProcessDB` and `ProcessInfo`, simulate saving process data, build a process tree, and retrieve a coverage map, using mock NYC dependencies and temporary files.

import { ProcessDB, ProcessInfo } from 'istanbul-lib-processinfo'; import * as path from 'path'; import * as fs from 'fs/promises'; async function main() { const tempDir = path.join(process.cwd(), '.temp_processinfo_data'); await fs.mkdir(tempDir, { recursive: true }); console.log(`Working in temporary directory: ${tempDir}`); // Create a ProcessDB instance for the temporary directory const processDB = new ProcessDB(tempDir); await processDB.writeIndex(); // Ensure index.json exists // Simulate a root process info const rootProcessInfo = new ProcessInfo({ uuid: 'root-process-id-123', directory: tempDir, args: ['node', 'root.js'], externalId: 'main-app' }); await rootProcessInfo.save(); console.log(`Root process info saved: ${rootProcessInfo.uuid}.json`); // Simulate a child process using spawn // Note: in a real scenario, 'nyc' would wrap the spawned command. // For this example, we mock a successful spawn. console.log('Spawning a mock child process...'); // The actual `spawn` would return a ChildProcess, but we're simulating // for demonstration purposes without executing an actual child process. // A real spawn would look like: await processDB.spawn('child1', 'node', ['child.js'], {cwd: tempDir}); // Instead, manually create a child process info to illustrate data structure const childProcessInfo = new ProcessInfo({ uuid: 'child-process-id-456', directory: tempDir, args: ['node', 'child.js'], externalId: 'feature-module' }); await childProcessInfo.save(); console.log(`Child process info saved: ${childProcessInfo.uuid}.json`); // To build the tree and get coverage map, a (mock) nyc instance is required const mockNyc = { // Minimal mock for nyc properties needed by istanbul-lib-processinfo instrumenter: { /* ... */ }, sourceMaps: true, cache: true, exclude: [], include: [] }; await processDB.buildProcessTree(); const coverageMap = await processDB.getCoverageMap(mockNyc); console.log('Successfully built process tree and retrieved coverage map (mock).'); // In a real scenario, coverageMap would contain actual coverage data console.log(`Coverage Map's unique key count: ${Object.keys(coverageMap.data).length}`); // Clean up await fs.rm(tempDir, { recursive: true, force: true }); console.log(`Cleaned up temporary directory: ${tempDir}`); } main().catch(console.error);
Debug
Known issues
breakingVersion 3.0.0 introduces a breaking change requiring Node.js 20 or greater (specifically '20 || >=22'). Projects running on older Node.js versions will fail to install or run correctly.
fix
Upgrade your Node.js environment to version 20 or 22 and above. Check your project's `package.json` for engine constraints and update your development and CI/CD environments accordingly.
affects: >=3.0.0
gotchaThe `processDB.writeIndex()` method is non-atomic. It should not be called concurrently by multiple processes, as this can lead to data corruption or an invalid `index.json` file.
fix
Ensure that only a single, coordinated process is responsible for writing the `index.json` file. Implement appropriate synchronization mechanisms (e.g., file locks, semaphores) if multiple processes might attempt to write the index.
affects: >=1.0.0
gotchaCalling `processDB.spawn()` internally triggers an `expunge` operation. This invalidates the current `index.json` file. It is the caller's responsibility to call `processDB.writeIndex()` *after* all named processes (spawned or expunged) are completed to ensure the index is up-to-date.
fix
Always follow a sequence of `processDB.spawn()` and/or `processDB.expunge()` calls with a final `await processDB.writeIndex()` to re-synchronize the process information index on disk.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to `require()` an ESM-only package in a CommonJS context or an older Node.js version not configured for dual-package hazard resolution.
fix
Ensure your project uses Node.js 20+ and convert your usage to ESM `import` statements. If a CommonJS context is unavoidable, you may need to dynamically `import()` the module or use an older version if available.
Error: Node.js v18.x.x is not supported by this package. Please use Node.js v20 or v22+.
Running `istanbul-lib-processinfo@3.0.0` or higher with an unsupported Node.js version, as indicated by the `engines` field.
fix
Update your Node.js environment to version 20 or 22 or newer. Use `nvm` or a similar tool to manage Node.js versions.
ENOENT: no such file or directory, open '.nyc_output/processinfo/index.json'
The `index.json` file, crucial for `ProcessDB` operations, is missing or corrupted, and `processDB.readIndex()` failed to generate it.
fix
Ensure the directory supplied to `ProcessDB` constructor is correct and writable. If starting fresh or recovering, call `await processDB.writeIndex()` to create or overwrite the index file. Remember `writeIndex` is non-atomic.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies
nycrequiredThis library is primarily used by NYC and its ecosystem tools to consume and manage processinfo data for coverage reporting. Many key methods (e.g., `getCoverageMap`, `renderTree`) require an `nyc` instance.
Agent activity
4 hits · last 30 days
node
4
Resources
istanbul-lib-processinfo — npm install istanbul-lib-processinfo · libregistry