{"id":12297,"library":"unist-util-position-from-estree","title":"Unist Utility: Position from ESTree Node","description":"unist-util-position-from-estree is a specialized utility that converts an ESTree (ECMAScript Abstract Syntax Tree) node into a unist (Universal Syntax Tree) position object. This package is crucial for projects that need to bridge the gap between JavaScript parsing tools (like Acorn) which produce ESTree, and the broader unist ecosystem used by tools like remark, rehype, and retext. The current stable version is 2.0.0. As part of the unified collective, it follows a release cadence tied to breaking changes in its dependencies or Node.js compatibility. Its key differentiator is providing a standardized way to represent code locations from ESTree within the unist data model, enabling interoperability with other unist utilities and plugins. It is ESM-only and requires Node.js 16+.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-position-from-estree","tags":["javascript","unist","unist-util","util","utility","recma","esast","estree","typescript"],"install":[{"cmd":"npm install unist-util-position-from-estree","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-position-from-estree","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-position-from-estree","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only since v2.0.0. CommonJS `require` is not supported.","wrong":"const { positionFromEstree } = require('unist-util-position-from-estree')","symbol":"positionFromEstree","correct":"import { positionFromEstree } from 'unist-util-position-from-estree'"},{"note":"The package ships its own types and consumes `@types/unist`. Ensure `@types/unist` is updated to a compatible version.","symbol":"positionFromEstree (TypeScript)","correct":"import type { Position } from 'unist';\nimport { positionFromEstree } from 'unist-util-position-from-estree'"}],"quickstart":{"code":"import { parse } from 'acorn';\nimport { positionFromEstree } from 'unist-util-position-from-estree';\n\n// Acorn requires `locations: true` to generate position data.\nconst code = 'function example() { console.log(\"Hello\"); }';\nconst node = parse(code, {\n  ecmaVersion: 2020,\n  locations: true, // Crucial for position information\n  sourceType: 'module'\n});\n\nconsole.log('Position for entire program:', positionFromEstree(node));\nconsole.log('Position for function name:', positionFromEstree(node.body[0].id));\nconsole.log('Position for console.log call:', positionFromEstree(node.body[0].body.body[0].expression));\n","lang":"typescript","description":"This quickstart demonstrates how to parse JavaScript code using Acorn, and then convert specific ESTree nodes into unist position objects using `positionFromEstree`."},"warnings":[{"fix":"Update your code to expect and handle `undefined` when an invalid ESTree node or node without location information is passed. E.g., `const pos = positionFromEstree(node); if (pos) { /* use pos */ }`","message":"Version 2.0.0 changes the return type of `positionFromEstree` for invalid points or positions. It now explicitly returns `undefined` instead of potentially incomplete or malformed position objects.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project runs on Node.js 16 or higher. Migrate your import statements from CommonJS `require()` to ESM `import` statements.","message":"Version 2.0.0 drops support for Node.js versions prior to 16. It is now ESM-only.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Only use the public API as exposed through the main entry point. Avoid importing from deep paths (e.g., `unist-util-position-from-estree/lib/some-internal-module`).","message":"The package now uses `export` maps, which means direct access to internal, non-exported paths is no longer supported and will break.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project's `@types/unist` dependency is also updated to a compatible version, ideally the latest stable version.","message":"The `@types/unist` dependency has been updated in v2.0.0. Incompatible versions of `@types/unist` can lead to type errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"When using a parser to generate ESTree nodes, ensure you pass the necessary options (e.g., `{ locations: true }` for Acorn) to include position information in the nodes.","message":"For `positionFromEstree` to return meaningful position data, the ESTree node must have `loc` and `range` properties. These are typically generated by parsers like Acorn when configured with `locations: true` and/or `ranges: true`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert your file and import statements to use ES Modules syntax: `import { positionFromEstree } from 'unist-util-position-from-estree';` and ensure your `package.json` has `\"type\": \"module\"` or your file ends with `.mjs`.","cause":"Attempting to `require()` an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Remove any deep imports. Import only from the main package entry point: `import { positionFromEstree } from 'unist-util-position-from-estree';`","cause":"Trying to import from an internal path that is no longer exposed due to `exports` map.","error":"Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/index.js' is not exported from package"},{"fix":"Ensure the ESTree node passed to `positionFromEstree` contains location data (e.g., from a parser configured with `locations: true`). Always check if the return value is `undefined` before accessing its properties: `const pos = positionFromEstree(node); if (pos) { console.log(pos.start); }`","cause":"Calling `positionFromEstree` with an ESTree node that lacks location information or is invalid, and then attempting to access properties on the `undefined` return value.","error":"TypeError: Cannot read properties of undefined (reading 'start')"}],"ecosystem":"npm"}