{"id":12356,"library":"vfile-location","title":"vfile-location","description":"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.","status":"active","version":"5.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-location","tags":["javascript","vfile","vfile-util","util","utility","virtual","file","location","point","typescript"],"install":[{"cmd":"npm install vfile-location","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-location","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-location","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the primary file object (`VFile`) that `vfile-location` operates on; explicitly added as a dependency in v4.0.1 to fix types.","package":"vfile","optional":false}],"imports":[{"note":"Package is ESM-only since v5. Use named import. The `location` function is not a default export.","wrong":"const { location } = require('vfile-location')","symbol":"location","correct":"import { location } from 'vfile-location'"},{"note":"Imports only the TypeScript type for the `Location` interface. Direct runtime import of `Location` as a value is not intended.","wrong":"import { Location } from 'vfile-location'","symbol":"Location","correct":"import type { Location } from 'vfile-location'"},{"note":"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.","wrong":"const { VFile } = require('vfile')","symbol":"VFile","correct":"import { VFile } from 'vfile'"}],"quickstart":{"code":"import { VFile } from 'vfile';\nimport { location } from 'vfile-location';\n\n// Create a VFile instance with some content\nconst fileContent = 'foo\\nbar\\nbaz';\nconst file = new VFile(fileContent);\n\n// Create a location index for the file\nconst place = location(file);\n\n// Convert a line/column point to an offset\nconst point = { line: 3, column: 3 };\nconst offset = place.toOffset(point); // Should be 10 (0-indexed)\nconsole.log(`Offset for point {line: ${point.line}, column: ${point.column}} is: ${offset}`);\n\n// Convert an offset back to a line/column point\nconst targetOffset = 10;\nconst retrievedPoint = place.toPoint(targetOffset);\nconsole.log(`Point for offset ${targetOffset} is: {line: ${retrievedPoint?.line}, column: ${retrievedPoint?.column}, offset: ${retrievedPoint?.offset}}`);\n\n// Demonstrate out-of-bounds handling (v5 change)\nconst outOfBoundsOffset = 100;\nconst invalidPoint = place.toPoint(outOfBoundsOffset);\nconsole.log(`Point for out-of-bounds offset ${outOfBoundsOffset} is: ${invalidPoint}`); // Should be undefined\n\nconst outOfBoundsPoint = { line: 10, column: 1 };\nconst invalidOffset = place.toOffset(outOfBoundsPoint);\nconsole.log(`Offset for out-of-bounds point {line: ${outOfBoundsPoint.line}, column: ${outOfBoundsPoint.column}} is: ${invalidOffset}`); // Should be undefined\n","lang":"typescript","description":"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."},"warnings":[{"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).","message":"`vfile-location` v5.0.0 and later are ESM-only. CommonJS `require()` statements will fail, leading to `ERR_REQUIRE_ESM` errors.","severity":"breaking","affected_versions":">=5.0.0"},{"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`.","message":"Version 5.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your code to check for `undefined` instead of `-1` when validating the return value of `toOffset`. For example, use `if (offset === undefined)`.","message":"The `toOffset` method now returns `undefined` for out-of-bounds input instead of `-1`. This changes how you should check for invalid results.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your code to explicitly check for `undefined` when validating the return value of `toPoint`. For example, `if (point === undefined)`.","message":"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).","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always use `import { location } from 'vfile-location'`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `vfile-location` (an ESM package since v5) with a CommonJS `require()` statement.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/vfile-location/index.js from .../your-file.js not supported."},{"fix":"Ensure you are using a named import: `import { location } from 'vfile-location'`.","cause":"Incorrect import syntax for the `location` function, often due to attempting a default import or transpilation issues with named exports.","error":"TypeError: (0, _vfile_location.location) is not a function"},{"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`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'toOffset')"}],"ecosystem":"npm"}