vfile-location

Common errors

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

  cause Attempting to use `vfile-location` (an ESM package since v5) with a CommonJS `require()` statement.
  fix Update your module to use ES module syntax (`import { location } from 'vfile-location'`) and ensure your project is configured for ESM, or use a bundler.

• TypeError: (0, _vfile_location.location) is not a function

  cause Incorrect import syntax for the `location` function, often due to attempting a default import or transpilation issues with named exports.
  fix Ensure you are using a named import: `import { location } from 'vfile-location'`.

• TypeError: Cannot read properties of undefined (reading 'toOffset')

  cause The `place` variable (returned by `location(file)`) is `undefined` because `location()` was called with an invalid `file` object, or the `location` function itself was not correctly imported.
  fix Verify that `VFile` is correctly imported and initialized before passing it to `location()`. Also, double-check the `location` import syntax as detailed in `imports`.

Warnings

• breaking `vfile-location` v5.0.0 and later are ESM-only. CommonJS `require()` statements will fail, leading to `ERR_REQUIRE_ESM` errors.
  Fix: Migrate your project to use ES modules (`import`/`export`) or use a bundler that can handle ESM imports. Update your Node.js version if necessary (Node.js 16+ is required).
• breaking Version 5.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js runtime to version 16 or newer. For projects that must support older Node.js versions, consider pinning to `vfile-location@^4`.
• breaking The `toOffset` method now returns `undefined` for out-of-bounds input instead of `-1`. This changes how you should check for invalid results.
  Fix: Update your code to check for `undefined` instead of `-1` when validating the return value of `toOffset`. For example, use `if (offset === undefined)`.
• breaking The `toPoint` method now returns `undefined` for invalid points (e.g., out-of-bounds offsets) instead of its previous behavior (which might have been returning an invalid point or throwing).
  Fix: Update your code to explicitly check for `undefined` when validating the return value of `toPoint`. For example, `if (point === undefined)`.
• gotcha When importing, ensure you use named imports (`{ location }`) as `vfile-location` does not provide a default export. Attempting a default import (`import location from 'vfile-location'`) will result in `undefined` or a runtime error.
  Fix: Always use `import { location } from 'vfile-location'`.

Install

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

Imports

• location
  wrong:

  const { location } = require('vfile-location')

  correct:

  import { location } from 'vfile-location'

  Package is ESM-only since v5. Use named import. The `location` function is not a default export.
• Location
  wrong:

  import { Location } from 'vfile-location'

  correct:

  import type { Location } from 'vfile-location'

  Imports only the TypeScript type for the `Location` interface. Direct runtime import of `Location` as a value is not intended.
• VFile
  wrong:

  const { VFile } = require('vfile')

  correct:

  import { VFile } from 'vfile'

  While `VFile` is from the `vfile` package, it's the primary input type for `vfile-location` and is almost always used in conjunction with it. The `vfile` package is also ESM-first.

Quickstart

This quickstart demonstrates how to create a location index for a `VFile`, convert a line/column point to a character offset, and convert an offset back to a point, including how out-of-bounds values are handled since v5.

import { VFile } from 'vfile';
import { location } from 'vfile-location';

// Create a VFile instance with some content
const fileContent = 'foo\nbar\nbaz';
const file = new VFile(fileContent);

// Create a location index for the file
const place = location(file);

// Convert a line/column point to an offset
const point = { line: 3, column: 3 };
const offset = place.toOffset(point); // Should be 10 (0-indexed)
console.log(`Offset for point {line: ${point.line}, column: ${point.column}} is: ${offset}`);

// Convert an offset back to a line/column point
const targetOffset = 10;
const retrievedPoint = place.toPoint(targetOffset);
console.log(`Point for offset ${targetOffset} is: {line: ${retrievedPoint?.line}, column: ${retrievedPoint?.column}, offset: ${retrievedPoint?.offset}}`);

// Demonstrate out-of-bounds handling (v5 change)
const outOfBoundsOffset = 100;
const invalidPoint = place.toPoint(outOfBoundsOffset);
console.log(`Point for out-of-bounds offset ${outOfBoundsOffset} is: ${invalidPoint}`); // Should be undefined

const outOfBoundsPoint = { line: 10, column: 1 };
const invalidOffset = place.toOffset(outOfBoundsPoint);
console.log(`Offset for out-of-bounds point {line: ${outOfBoundsPoint.line}, column: ${outOfBoundsPoint.column}} is: ${invalidOffset}`); // Should be undefined