{"id":13361,"library":"istanbul-lib-processinfo","title":"Istanbul Process Info Management","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/istanbuljs/istanbul-lib-processinfo","tags":["javascript"],"install":[{"cmd":"npm install istanbul-lib-processinfo","lang":"bash","label":"npm"},{"cmd":"yarn add istanbul-lib-processinfo","lang":"bash","label":"yarn"},{"cmd":"pnpm add istanbul-lib-processinfo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This 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.","package":"nyc","optional":false}],"imports":[{"note":"ESM named imports are the modern and preferred way to access classes since v3, especially with Node.js 20+.","wrong":"const ProcessInfo = require('istanbul-lib-processinfo').ProcessInfo;","symbol":"ProcessInfo","correct":"import { ProcessInfo } from 'istanbul-lib-processinfo';"},{"note":"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.","wrong":"const ProcessDB = require('istanbul-lib-processinfo').ProcessDB;","symbol":"ProcessDB","correct":"import { ProcessDB } from 'istanbul-lib-processinfo';"}],"quickstart":{"code":"import { ProcessDB, ProcessInfo } from 'istanbul-lib-processinfo';\nimport * as path from 'path';\nimport * as fs from 'fs/promises';\n\nasync function main() {\n  const tempDir = path.join(process.cwd(), '.temp_processinfo_data');\n  await fs.mkdir(tempDir, { recursive: true });\n\n  console.log(`Working in temporary directory: ${tempDir}`);\n\n  // Create a ProcessDB instance for the temporary directory\n  const processDB = new ProcessDB(tempDir);\n  await processDB.writeIndex(); // Ensure index.json exists\n\n  // Simulate a root process info\n  const rootProcessInfo = new ProcessInfo({\n    uuid: 'root-process-id-123',\n    directory: tempDir,\n    args: ['node', 'root.js'],\n    externalId: 'main-app'\n  });\n  await rootProcessInfo.save();\n  console.log(`Root process info saved: ${rootProcessInfo.uuid}.json`);\n\n  // Simulate a child process using spawn\n  // Note: in a real scenario, 'nyc' would wrap the spawned command.\n  // For this example, we mock a successful spawn.\n  console.log('Spawning a mock child process...');\n  // The actual `spawn` would return a ChildProcess, but we're simulating\n  // for demonstration purposes without executing an actual child process.\n  // A real spawn would look like: await processDB.spawn('child1', 'node', ['child.js'], {cwd: tempDir});\n\n  // Instead, manually create a child process info to illustrate data structure\n  const childProcessInfo = new ProcessInfo({\n    uuid: 'child-process-id-456',\n    directory: tempDir,\n    args: ['node', 'child.js'],\n    externalId: 'feature-module'\n  });\n  await childProcessInfo.save();\n  console.log(`Child process info saved: ${childProcessInfo.uuid}.json`);\n\n  // To build the tree and get coverage map, a (mock) nyc instance is required\n  const mockNyc = {\n    // Minimal mock for nyc properties needed by istanbul-lib-processinfo\n    instrumenter: { /* ... */ },\n    sourceMaps: true,\n    cache: true,\n    exclude: [],\n    include: []\n  };\n\n  await processDB.buildProcessTree();\n  const coverageMap = await processDB.getCoverageMap(mockNyc);\n  console.log('Successfully built process tree and retrieved coverage map (mock).');\n  // In a real scenario, coverageMap would contain actual coverage data\n  console.log(`Coverage Map's unique key count: ${Object.keys(coverageMap.data).length}`);\n\n  // Clean up\n  await fs.rm(tempDir, { recursive: true, force: true });\n  console.log(`Cleaned up temporary directory: ${tempDir}`);\n}\n\nmain().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Calling `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` an ESM-only package in a CommonJS context or an older Node.js version not configured for dual-package hazard resolution.","error":"ERR_REQUIRE_ESM"},{"fix":"Update your Node.js environment to version 20 or 22 or newer. Use `nvm` or a similar tool to manage Node.js versions.","cause":"Running `istanbul-lib-processinfo@3.0.0` or higher with an unsupported Node.js version, as indicated by the `engines` field.","error":"Error: Node.js v18.x.x is not supported by this package. Please use Node.js v20 or v22+."},{"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.","cause":"The `index.json` file, crucial for `ProcessDB` operations, is missing or corrupted, and `processDB.readIndex()` failed to generate it.","error":"ENOENT: no such file or directory, open '.nyc_output/processinfo/index.json'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}