VFile Message Statistics Utility

3.0.0 · active · verified Sun Apr 19

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.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` vfile-statistics in a CommonJS context.

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');`
```
TypeError: statistics is not a function
```
cause Incorrect import statement (e.g., `import statistics from 'vfile-statistics'`) or trying to use a CJS `require` in an ESM context.

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 `<script type="module">`).
```
The 'value' parameter is required. Don't call when missing.
```
cause Calling `statistics()` without providing a valid `VFile`, `VFileMessage`, or array thereof.

fix Always pass a non-null, non-undefined `VFile`, `VFileMessage`, or an array containing these types as the argument to `statistics(file)`.

Warnings

breaking vfile-statistics v3.0.0 changed its minimum Node.js requirement to Node.js 16 or higher.
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.
breaking vfile-statistics v2.0.0 transitioned to an ESM-only package, dropping CommonJS support.
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.
breaking 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.
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`.
breaking v3.0.0 introduced changes to use the `export` map. Direct access to private APIs or non-exported paths is no longer supported.
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.
gotcha 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.
Fix: Change `import { Statistics } from 'vfile-statistics'` to `import type { Statistics } from 'vfile-statistics'` in your TypeScript files.

Install

npm install vfile-statistics npm
yarn add vfile-statistics yarn
pnpm add vfile-statistics pnpm

Imports

statistics
wrong:
```
const statistics = require('vfile-statistics')
```
correct:
```
import { statistics } from 'vfile-statistics'
```
vfile-statistics is an ESM-only package since v2.0.0. CommonJS `require` will result in an error.
Statistics
wrong:
```
import { Statistics } from 'vfile-statistics'
```
correct:
```
import type { Statistics } from 'vfile-statistics'
```
This symbol is a TypeScript type definition, not a runtime value. It should be imported using `import type`.
statistics
```
import { statistics } from 'https://esm.sh/vfile-statistics@3'
```
For Deno and browser environments, `esm.sh` provides a convenient way to import the ESM module, specifying the major version for stability.

Quickstart

Demonstrates how to import `statistics` and `VFile`, add different message types to a vfile, and then compute and log the message statistics.

import { VFile } from 'vfile'
import { statistics } from 'vfile-statistics'

// Create a new VFile instance
const file = new VFile({path: '~/example.md', value: '# Hello'}) 

// Add various types of messages to the file
file.message('This observation could be improved', { ruleId: 'style-guide' })
file.message('Another styling suggestion', { line: 1, column: 3 })

// Simulate a fatal error that might be caught or thrown
try {
  file.fail('Critical parsing error found', { ruleId: 'parser-error', fatal: true })
} catch (error) {
  // In a real application, you might handle the error here
  console.error('Caught a vfile.fail error:', error.message)
}

file.info('Metadata: author is John Doe', { ruleId: 'meta-data' })

// Get and log the statistics
const stats = statistics(file)
console.log('File statistics:', stats)

/* Expected Output:
File statistics: { fatal: 1, nonfatal: 3, warn: 2, info: 1, total: 4 }
*/

view raw JSON →