Registry / serialization / unist-util-position-from-estree

unist-util-position-from-estree

library2.0.0jsnpmunverified

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

serialization

npm install unist-util-position-from-estree

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-POSITIO

unist-util-position-from-estree

serializationjavascriptv2.0.0

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.

positionFromEstree

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

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

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

Debug

Known issues

breakingVersion 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 */ }`

affects: >=2.0.0

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

affects: >=2.0.0

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

affects: >=2.0.0

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

affects: >=2.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

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

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); }`

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/syntax-tree/unist-util-position-from-estree ↗

packagehttps://www.npmjs.com/package/unist-util-position-from-estree ↗