vfile-sort

Common errors

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

  cause 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

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

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

Warnings

• breaking 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`).
  Fix: Migrate calls from `sort(file)` to `file.messages.sort(compareMessage)` or `array.toSorted(compareFile/compareMessage)` for explicit sorting.
• breaking vfile-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.
• breaking Node.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.
• gotcha 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.
  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.
• breaking 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.
  Fix: Review the `vfile` v6 changelog for specific migration steps and ensure all `vfile` ecosystem packages in your project are compatible.

Install

• npm install vfile-sort npm
• yarn add vfile-sort yarn
• pnpm add vfile-sort pnpm

Imports

• compareFile
  wrong:

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

  correct:

  import { compareFile } from 'vfile-sort'

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

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

  correct:

  import { compareMessage } from 'vfile-sort'

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

  const { VFile } = require('vfile')

  correct:

  import { VFile } from 'vfile'

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

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

  correct:

  import { VFileMessage } from 'vfile-message'

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

Quickstart

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']