{"id":12359,"library":"vfile-sort","title":"vfile-sort","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-sort","tags":["javascript","vfile","vfile-util","util","utility","virtual","file","sort","order","typescript"],"install":[{"cmd":"npm install vfile-sort","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-sort","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-sort","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v3. The `sort(file)` API was removed in v4, use this comparator directly with array sorting methods.","wrong":"const { compareFile } = require('vfile-sort')","symbol":"compareFile","correct":"import { compareFile } from 'vfile-sort'"},{"note":"ESM-only since v3. The `sort(file)` API was removed in v4, use this comparator directly with array sorting methods.","wrong":"const { compareMessage } = require('vfile-sort')","symbol":"compareMessage","correct":"import { compareMessage } from 'vfile-sort'"},{"note":"Often imported alongside `vfile-sort` as its functions operate on `VFile` instances. `vfile` is also ESM-only since v5.","wrong":"const { VFile } = require('vfile')","symbol":"VFile","correct":"import { VFile } from 'vfile'"},{"note":"Often imported alongside `vfile-sort` as its functions operate on `VFileMessage` instances.","wrong":"const { VFileMessage } = require('vfile-message')","symbol":"VFileMessage","correct":"import { VFileMessage } from 'vfile-message'"}],"quickstart":{"code":"import { VFile } from 'vfile';\nimport { VFileMessage } from 'vfile-message';\nimport { compareFile, compareMessage } from 'vfile-sort';\n\n// Sort VFileMessages\nconst messages = [\n  new VFileMessage('Error: Missing semicolon.', { place: { line: 3, column: 1 } }),\n  new VFileMessage('Warning: Unused variable.', { place: { line: 2, column: 5 } }),\n  new VFileMessage('Info: Deprecated API.', { place: { line: 3, column: 10 } })\n];\n\nconst sortedMessages = messages.toSorted(compareMessage).map(String);\nconsole.log('Sorted Messages:', sortedMessages);\n// Expected: ['2:5: Warning: Unused variable.', '3:1: Error: Missing semicolon.', '3:10: Info: Deprecated API.']\n\n// Sort VFiles (example using dummy paths for demonstration)\nconst fileA = new VFile({ path: '/project/src/components/button.ts' });\nconst fileB = new VFile({ path: '/project/src/utils/helpers.ts' });\nconst fileC = new VFile({ path: '/project/index.ts' });\n\nconst files = [fileA, fileB, fileC];\nconst sortedFiles = files.toSorted(compareFile).map((d) => d.path);\nconsole.log('Sorted Files:', sortedFiles);\n// Expected: ['/project/index.ts', '/project/src/components/button.ts', '/project/src/utils/helpers.ts']","lang":"typescript","description":"Demonstrates sorting `VFileMessage` and `VFile` instances using `compareMessage` and `compareFile` respectively."},"warnings":[{"fix":"Migrate calls from `sort(file)` to `file.messages.sort(compareMessage)` or `array.toSorted(compareFile/compareMessage)` for explicit sorting.","message":"The 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`).","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"vfile-sort is now an ESM-only package. CommonJS `require()` is no longer supported for importing this library.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your Node.js environment to version 16 or higher to ensure compatibility.","message":"Node.js 16 or newer is now required to use vfile-sort.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Using 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Review the `vfile` v6 changelog for specific migration steps and ensure all `vfile` ecosystem packages in your project are compatible.","message":"vfile-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.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Instead of `sort(file)`, use `file.messages.sort(compareMessage)` or `myArray.toSorted(compareMessage/compareFile)`.","cause":"Attempting to call the `sort` function after upgrading to v4.0.0, where it was removed.","error":"TypeError: (0 , _vfile_sort__WEBPACK_IMPORTED_MODULE_2__.sort) is not a function"},{"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+.","cause":"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).","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"Attempting to `require()` vfile-sort, which is an ESM-only package since v3.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/vfile-sort/index.js from ... not supported."}],"ecosystem":"npm"}