vfile-sort

library4.0.0jsnpmunverified

vfile-sort is a utility package within the unified/vfile ecosystem designed for ordering `VFile` objects and `VFileMessage` objects. Its current stable version is 4.0.0. The package primarily exposes comparator functions, `compareFile` and `compareMessage`, which can be used with array sorting methods (e.g., `Array.prototype.sort` or `toSorted`) to arrange files or messages by properties like line, column, severity, and other metadata. It follows the Node.js LTS release cycle for compatibility and ships with TypeScript types, making it suitable for modern JavaScript and TypeScript projects. Key differentiators include its tight integration with the `vfile` specification and its focus on providing precise, consistent sorting logic for diagnostics and file-related metadata, ensuring human-readable reports.

serialization testing

npm install vfile-sort

github ↗package ↗

INSTALL

IMPORT

SIG · VFILE-SORT

vfile-sort

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

compareFile

✓ import { compareFile } from 'vfile-sort'

✗ const { compareFile } = require('vfile-sort')

ESM-only since v3. The `sort(file)` API was removed in v4, use this comparator directly with array sorting methods.

compareMessage

✓ import { compareMessage } from 'vfile-sort'

✗ const { compareMessage } = require('vfile-sort')

ESM-only since v3. The `sort(file)` API was removed in v4, use this comparator directly with array sorting methods.

VFile

✓ import { VFile } from 'vfile'

✗ const { VFile } = require('vfile')

Often imported alongside `vfile-sort` as its functions operate on `VFile` instances. `vfile` is also ESM-only since v5.

VFileMessage

✓ import { VFileMessage } from 'vfile-message'

✗ const { VFileMessage } = require('vfile-message')

Often imported alongside `vfile-sort` as its functions operate on `VFileMessage` instances.

Demonstrates sorting `VFileMessage` and `VFile` instances using `compareMessage` and `compareFile` respectively.

import { VFile } from 'vfile'; import { VFileMessage } from 'vfile-message'; import { compareFile, compareMessage } from 'vfile-sort'; // Sort VFileMessages const messages = [ new VFileMessage('Error: Missing semicolon.', { place: { line: 3, column: 1 } }), new VFileMessage('Warning: Unused variable.', { place: { line: 2, column: 5 } }), new VFileMessage('Info: Deprecated API.', { place: { line: 3, column: 10 } }) ]; const sortedMessages = messages.toSorted(compareMessage).map(String); console.log('Sorted Messages:', sortedMessages); // Expected: ['2:5: Warning: Unused variable.', '3:1: Error: Missing semicolon.', '3:10: Info: Deprecated API.'] // Sort VFiles (example using dummy paths for demonstration) const fileA = new VFile({ path: '/project/src/components/button.ts' }); const fileB = new VFile({ path: '/project/src/utils/helpers.ts' }); const fileC = new VFile({ path: '/project/index.ts' }); const files = [fileA, fileB, fileC]; const sortedFiles = files.toSorted(compareFile).map((d) => d.path); console.log('Sorted Files:', sortedFiles); // Expected: ['/project/index.ts', '/project/src/components/button.ts', '/project/src/utils/helpers.ts']

Debug

Known issues

breakingThe primary `sort(file)` function that directly mutated a `VFile` object was removed in v4.0.0. The package now exclusively exports comparison functions (`compareFile` and `compareMessage`).

fix

Migrate calls from `sort(file)` to `file.messages.sort(compareMessage)` or `array.toSorted(compareFile/compareMessage)` for explicit sorting.

affects: >=4.0.0

breakingvfile-sort is now an ESM-only package. CommonJS `require()` is no longer supported for importing this library.

fix

Migrate your project to use ESM `import` statements (e.g., `import { compareMessage } from 'vfile-sort'`) or a compatible bundler. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions for your code.

affects: >=3.0.0

breakingNode.js 16 or newer is now required to use vfile-sort.

fix

Update your Node.js environment to version 16 or higher to ensure compatibility.

affects: >=4.0.0

gotchaUsing private module APIs, such as directly importing from deep paths (e.g., `vfile-sort/lib/some-internal-module`), is not supported and may break in future versions due to the package's use of `export` maps.

fix

Always import directly from the main package entry point (`vfile-sort`) to use only the public API as specified in the package's `export` map.

affects: >=4.0.0

breakingvfile-sort v4.0.0 updates its internal `vfile` dependency/compatibility to `vfile@6.0.0`. This might introduce further breaking changes if your project uses an older `vfile` version.

fix

Review the `vfile` v6 changelog for specific migration steps and ensure all `vfile` ecosystem packages in your project are compatible.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: (0 , _vfile_sort__WEBPACK_IMPORTED_MODULE_2__.sort) is not a function

Attempting to call the `sort` function after upgrading to v4.0.0, where it was removed.

fix

Instead of `sort(file)`, use `file.messages.sort(compareMessage)` or `myArray.toSorted(compareMessage/compareFile)`.

SyntaxError: Cannot use import statement outside a module

Attempting to `import` vfile-sort in a CommonJS context (e.g., in a `.js` file without `"type": "module"` in `package.json` or in an older Node.js version).

fix

Ensure your project is configured for ESM (add `"type": "module"` to your `package.json` or use `.mjs` file extensions) and upgrade Node.js to v16+.

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/vfile-sort/index.js from ... not supported.

Attempting to `require()` vfile-sort, which is an ESM-only package since v3.

fix

Use `import` statements instead of `require()`. If in a CommonJS context, consider upgrading to a newer Node.js version and migrating to ESM for your project.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

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

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