vfile-statistics

library3.0.0jsnpmunverified

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.

testing

npm install vfile-statistics

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VFILE-STATISTICS

vfile-statistics

testingjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

statistics

✓ import { statistics } from 'vfile-statistics'

✗ const statistics = require('vfile-statistics')

vfile-statistics is an ESM-only package since v2.0.0. CommonJS `require` will result in an error.

Statistics

✓ import type { Statistics } from 'vfile-statistics'

✗ import { 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.

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 } */

Debug

Known issues

breakingvfile-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.

affects: >=3.0.0

breakingvfile-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.

affects: >=2.0.0

breakingIn 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`.

affects: >=3.0.0

breakingv3.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.

affects: >=3.0.0

gotchaThe `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.

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

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.

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)`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

vfilerequiredCore dependency for `VFile` instances and `VFileMessage` objects, which this utility processes.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/vfile/vfile-statistics ↗

packagehttps://www.npmjs.com/package/vfile-statistics ↗

homepagehttps://unifiedjs.com ↗