Registry / serialization / unist-util-position

unist-util-position

library5.0.0jsnpmunverified

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.

serialization data

npm install unist-util-position

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-POSITIO

unist-util-position

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

position

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

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

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

pointStart

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

✗ import pointStart from 'unist-util-position/pointStart'

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

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

✗ const position = require('unist-util-position').position

Ensure your environment is configured for ESM, typically via `type: "module"` in `package.json` or using `.mjs` file extensions.

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+

Debug

Known issues

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

affects: >=5.0.0

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

affects: >=4.0.0

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

affects: >=5.0.0

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

affects: >=5.0.0

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

affects: >=5.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/unist-util-position/index.js from ... not supported.

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

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.

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

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

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

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

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