{"id":12360,"library":"vfile-statistics","title":"VFile Message Statistics Utility","description":"vfile-statistics is a lightweight utility within the unified ecosystem designed to categorize and count messages associated with `vfile` instances. It provides statistics such as the total number of messages, as well as counts for fatal errors, warnings, and informational messages. The current stable version is 3.0.0, which notably requires Node.js 16 or higher and is an ESM-only package. This library follows the release cadence of the broader unified collective, tying major version bumps to Node.js LTS updates and significant changes in its peer dependencies like `vfile`. Its key differentiator is its focused simplicity, serving as a composable building block for tools processing virtual files, rather than a standalone, opinionated linter or parser.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-statistics","tags":["javascript","vfile","vfile-util","util","utility","virtual","file","message","count","typescript"],"install":[{"cmd":"npm install vfile-statistics","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-statistics","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-statistics","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for `VFile` instances and `VFileMessage` objects, which this utility processes.","package":"vfile","optional":false}],"imports":[{"note":"vfile-statistics is an ESM-only package since v2.0.0. CommonJS `require` will result in an error.","wrong":"const statistics = require('vfile-statistics')","symbol":"statistics","correct":"import { statistics } from 'vfile-statistics'"},{"note":"This symbol is a TypeScript type definition, not a runtime value. It should be imported using `import type`.","wrong":"import { Statistics } from 'vfile-statistics'","symbol":"Statistics","correct":"import type { Statistics } from 'vfile-statistics'"},{"note":"For Deno and browser environments, `esm.sh` provides a convenient way to import the ESM module, specifying the major version for stability.","symbol":"statistics","correct":"import { statistics } from 'https://esm.sh/vfile-statistics@3'"}],"quickstart":{"code":"import { VFile } from 'vfile'\nimport { statistics } from 'vfile-statistics'\n\n// Create a new VFile instance\nconst file = new VFile({path: '~/example.md', value: '# Hello'}) \n\n// Add various types of messages to the file\nfile.message('This observation could be improved', { ruleId: 'style-guide' })\nfile.message('Another styling suggestion', { line: 1, column: 3 })\n\n// Simulate a fatal error that might be caught or thrown\ntry {\n file.fail('Critical parsing error found', { ruleId: 'parser-error', fatal: true })\n} catch (error) {\n // In a real application, you might handle the error here\n console.error('Caught a vfile.fail error:', error.message)\n}\n\nfile.info('Metadata: author is John Doe', { ruleId: 'meta-data' })\n\n// Get and log the statistics\nconst stats = statistics(file)\nconsole.log('File statistics:', stats)\n\n/* Expected Output:\nFile statistics: { fatal: 1, nonfatal: 3, warn: 2, info: 1, total: 4 }\n*/","lang":"typescript","description":"Demonstrates how to import `statistics` and `VFile`, add different message types to a vfile, and then compute and log the message statistics."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. If you must use an older Node.js version, remain on vfile-statistics v2.x.","message":"vfile-statistics v3.0.0 changed its minimum Node.js requirement to Node.js 16 or higher.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Refactor your imports to use ESM syntax (e.g., `import { statistics } from 'vfile-statistics'`). If your project is CommonJS-only, consider using an earlier version (v1.x) or migrating to ESM.","message":"vfile-statistics v2.0.0 transitioned to an ESM-only package, dropping CommonJS support.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always pass a valid `VFile`, `VFileMessage`, or an array of these types to the `statistics` function. Ensure the input is not `undefined` or `null`.","message":"In v3.0.0, the `value` parameter for `statistics` is now required. Calling it without a valid `VFile`, `VFileMessage`, or array of them will cause an error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Only use the public API as exposed by the package's `export` map. Avoid directly importing from deep paths within the package unless they are explicitly exposed.","message":"v3.0.0 introduced changes to use the `export` map. Direct access to private APIs or non-exported paths is no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Change `import { Statistics } from 'vfile-statistics'` to `import type { Statistics } from 'vfile-statistics'` in your TypeScript files.","message":"The `Statistics` type is for TypeScript only and should be imported using `import type`. Importing it as a regular value will lead to build or runtime errors.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert your project to ESM or switch to using dynamic `import()` if you need to load an ESM module from CommonJS. For example: `const { statistics } = await import('vfile-statistics');`","cause":"Attempting to `require()` vfile-statistics in a CommonJS context.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you are using named imports for ESM: `import { statistics } from 'vfile-statistics'`. Also, verify your environment supports ESM (Node.js 16+ or browser with `