unist-util-position

5.0.0 · active · verified Sun Apr 19

unist-util-position is a crucial utility within the unified (unist) ecosystem, designed to robustly extract positional information from Unist (Universal Syntax Tree) nodes. This includes `start` and `end` points, along with `line`, `column`, and `offset` details. It's particularly valuable when processing trees that might have inconsistent or incomplete positional data due to user modifications or external plugins, acting as a safeguard against malformed data. The current stable version is 5.0.0, which mandates Node.js 16 or newer and operates exclusively as an ES module. New major versions are typically released to align with Node.js EOL policies and introduce significant breaking changes, while minor releases provide features and fixes. Its key differentiator is its focus on providing reliable positional data, returning `undefined` for invalid inputs rather than potentially throwing errors or returning partial, incorrect data, making it safer for robust plugin development compared to directly accessing `node.position` properties.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/unist-util-position/index.js from ... not supported.
```
cause Attempting to import `unist-util-position` (which is ESM-only) using CommonJS `require()` syntax.

fix Change your import statements from `const pkg = require('pkg')` to `import pkg from 'pkg'` or `import { namedExport } from 'pkg'`, and ensure your project/file is configured for ESM.
```
TypeError: position is not a function
```
cause Incorrectly trying to access a named export after using `require('unist-util-position')` or attempting to destructure `require`'s result as if it were an ESM module.

fix Use proper ES module named imports: `import { position, pointStart, pointEnd } from 'unist-util-position'`.
```
Error: This module uses Node.js 16 or later features and cannot be run on Node.js 14.
```
cause Running `unist-util-position` v5.0.0 or higher on an unsupported Node.js version (e.g., Node.js 14).

fix Upgrade your Node.js runtime environment to version 16 or a more recent, actively maintained version.
```
TypeError: Cannot read properties of undefined (reading 'line')
```
cause Attempting to access properties (like `start.line`) on the return value of `position`, `pointStart`, or `pointEnd` without checking if the result is `undefined` (a new behavior in v5.0.0).

fix Add a check for `undefined` before accessing properties, e.g., `const pos = position(node); if (pos) { console.log(pos.start.line); }`.

Warnings

breaking Version 5.0.0 and later require Node.js 16 or a newer compatible version. Running on older Node.js runtimes will result in runtime errors.
Fix: Upgrade your Node.js environment to version 16 or higher.
breaking Starting with version 4.0.0, unist-util-position is an ES module (ESM) only. CommonJS `require()` is no longer supported.
Fix: Migrate your project to use ES modules (`import` syntax) and ensure your `package.json` includes `"type": "module"` or use `.mjs` file extensions.
breaking As of v5.0.0, the `position`, `pointStart`, and `pointEnd` functions now return `undefined` for invalid nodes or positions, instead of potentially throwing an error or returning partial data. Consumers must explicitly check for `undefined`.
Fix: Update your code to include nullish checks: `const pos = position(node); if (pos) { /* use pos */ }`.
breaking Version 5.0.0 changes to use `exports` map in `package.json`. This means direct imports to internal, non-public paths are no longer supported and will break.
Fix: Always use the public API surface for imports (e.g., `import { position } from 'unist-util-position'`) and avoid deep imports.
gotcha When upgrading to `unist-util-position` v5.0.0, ensure that you also update your `@types/unist` dependency to a compatible version to avoid potential type mismatches or errors, as v5 updated its internal `@types/unist` dependency.
Fix: Run `npm install @types/unist@latest` or `yarn upgrade @types/unist` alongside `unist-util-position`.

Install

npm install unist-util-position npm
yarn add unist-util-position yarn
pnpm add unist-util-position pnpm

Imports

position

wrong:

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

correct:

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

The package is ESM-only since v4.0.0. Use `import` syntax.

pointStart
wrong:
```
import pointStart from 'unist-util-position/pointStart'
```
correct:
```
import { pointStart } from 'unist-util-position'
```
Only named exports are provided; there is no default export. Do not use direct deep imports into private paths as the package uses `exports` map.
pointEnd
wrong:
```
const position = require('unist-util-position').position
```
correct:
```
import { pointEnd } from 'unist-util-position'
```
Ensure your environment is configured for ESM, typically via `type: "module"` in `package.json` or using `.mjs` file extensions.

Quickstart

Demonstrates how to parse Markdown into a unist tree and extract its overall position, start point, and end point using the utility functions, including handling potentially undefined results from v5+.

import {fromMarkdown} from 'mdast-util-from-markdown'
import {pointEnd, pointStart, position} from 'unist-util-position'

const markdown = '# Hello\n\n* World\n'
const tree = fromMarkdown(markdown)

// Get the full position of the tree
const fullPosition = position(tree)
console.log('Full Position:', fullPosition)
// Expected: { start: { line: 1, column: 1, offset: 0 }, end: { line: 4, column: 1, offset: 13 } }

// Get the starting point of the tree
const startPoint = pointStart(tree)
console.log('Start Point:', startPoint)
// Expected: { line: 1, column: 1, offset: 0 }

// Get the ending point of the tree
const endPoint = pointEnd(tree)
console.log('End Point:', endPoint)
// Expected: { line: 4, column: 1, offset: 13 }

// Example of handling undefined for invalid nodes (v5+ behavior)
const invalidNode = null
const invalidPosition = position(invalidNode)
console.log('Invalid Position:', invalidPosition)
// Expected: undefined - always check for undefined with v5+

view raw JSON →