Registry / serialization / vfile-location

vfile-location

library5.0.3jsnpmunverified

vfile-location is a utility package within the unified ecosystem, currently at stable version 5.0.3, designed to convert between positional (line and column-based) and offset (character index-based) locations within a vfile instance. It provides `toOffset` and `toPoint` methods for accurate translation. The package sees active development and frequent, minor releases, with major versions typically introducing breaking changes like the move to ESM-only and Node.js 16+ requirement in v5. A key differentiator is its tight integration with `vfile`, making it ideal for tasks like generating precise linting reports or manipulating text based on raw file content where traditional AST node locations might be insufficient for location tracking.

serialization data

npm install vfile-location

github ↗package ↗

INSTALL

IMPORT

SIG · VFILE-LOCATION

vfile-location

serializationjavascriptv5.0.3

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.

location

✓ import { location } from 'vfile-location'

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

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

Location

✓ import type { Location } from 'vfile-location'

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

✓ import { VFile } from 'vfile'

✗ const { VFile } = require('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.

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

Debug

Known issues

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

affects: >=5.0.0

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

affects: >=5.0.0

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

affects: >=5.0.0

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

affects: >=5.0.0

gotchaWhen 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'`.

affects: >=3.0.0

Errors

Common errors & fixes

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

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

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

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

Upgrade

Version history

5.0.3latest on npm

Audit

Dependencies

vfilerequiredProvides the primary file object (`VFile`) that `vfile-location` operates on; explicitly added as a dependency in v4.0.1 to fix types.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

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

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