Unist Utility: Position from ESTree Node

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `require()` an ESM-only package.
  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`.

• Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/index.js' is not exported from package

  cause Trying to import from an internal path that is no longer exposed due to `exports` map.
  fix Remove any deep imports. Import only from the main package entry point: `import { positionFromEstree } from 'unist-util-position-from-estree';`

• TypeError: Cannot read properties of undefined (reading '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.
  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); }`

Warnings

• breaking 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.
  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 */ }`
• breaking Version 2.0.0 drops support for Node.js versions prior to 16. It is now ESM-only.
  Fix: Ensure your project runs on Node.js 16 or higher. Migrate your import statements from CommonJS `require()` to ESM `import` statements.
• breaking The package now uses `export` maps, which means direct access to internal, non-exported paths is no longer supported and will break.
  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`).
• breaking The `@types/unist` dependency has been updated in v2.0.0. Incompatible versions of `@types/unist` can lead to type errors.
  Fix: Ensure your project's `@types/unist` dependency is also updated to a compatible version, ideally the latest stable version.
• gotcha 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`.
  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.

Install

• npm install unist-util-position-from-estree npm
• yarn add unist-util-position-from-estree yarn
• pnpm add unist-util-position-from-estree pnpm

Imports

• positionFromEstree
  wrong:

  const { positionFromEstree } = require('unist-util-position-from-estree')

  correct:

  import { positionFromEstree } from 'unist-util-position-from-estree'

  This package is ESM-only since v2.0.0. CommonJS `require` is not supported.
• positionFromEstree (TypeScript)

  import type { Position } from 'unist';
  import { positionFromEstree } from 'unist-util-position-from-estree'

  The package ships its own types and consumes `@types/unist`. Ensure `@types/unist` is updated to a compatible version.

Quickstart

This quickstart demonstrates how to parse JavaScript code using Acorn, and then convert specific ESTree nodes into unist position objects using `positionFromEstree`.

import { parse } from 'acorn';
import { positionFromEstree } from 'unist-util-position-from-estree';

// Acorn requires `locations: true` to generate position data.
const code = 'function example() { console.log("Hello"); }';
const node = parse(code, {
  ecmaVersion: 2020,
  locations: true, // Crucial for position information
  sourceType: 'module'
});

console.log('Position for entire program:', positionFromEstree(node));
console.log('Position for function name:', positionFromEstree(node.body[0].id));
console.log('Position for console.log call:', positionFromEstree(node.body[0].body.body[0].expression));