{"id":12298,"library":"unist-util-position","title":"unist-util-position","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-position","tags":["javascript","unist","unist-util","util","utility","node","position","point","typescript"],"install":[{"cmd":"npm install unist-util-position","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-position","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-position","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only since v4.0.0. Use `import` syntax.","wrong":"const { position } = require('unist-util-position')","symbol":"position","correct":"import { position } from 'unist-util-position'"},{"note":"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.","wrong":"import pointStart from 'unist-util-position/pointStart'","symbol":"pointStart","correct":"import { pointStart } from 'unist-util-position'"},{"note":"Ensure your environment is configured for ESM, typically via `type: \"module\"` in `package.json` or using `.mjs` file extensions.","wrong":"const position = require('unist-util-position').position","symbol":"pointEnd","correct":"import { pointEnd } from 'unist-util-position'"}],"quickstart":{"code":"import {fromMarkdown} from 'mdast-util-from-markdown'\nimport {pointEnd, pointStart, position} from 'unist-util-position'\n\nconst markdown = '# Hello\\n\\n* World\\n'\nconst tree = fromMarkdown(markdown)\n\n// Get the full position of the tree\nconst fullPosition = position(tree)\nconsole.log('Full Position:', fullPosition)\n// Expected: { start: { line: 1, column: 1, offset: 0 }, end: { line: 4, column: 1, offset: 13 } }\n\n// Get the starting point of the tree\nconst startPoint = pointStart(tree)\nconsole.log('Start Point:', startPoint)\n// Expected: { line: 1, column: 1, offset: 0 }\n\n// Get the ending point of the tree\nconst endPoint = pointEnd(tree)\nconsole.log('End Point:', endPoint)\n// Expected: { line: 4, column: 1, offset: 13 }\n\n// Example of handling undefined for invalid nodes (v5+ behavior)\nconst invalidNode = null\nconst invalidPosition = position(invalidNode)\nconsole.log('Invalid Position:', invalidPosition)\n// Expected: undefined - always check for undefined with v5+","lang":"typescript","description":"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+."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate your project to use ES modules (`import` syntax) and ensure your `package.json` includes `\"type\": \"module\"` or use `.mjs` file extensions.","message":"Starting with version 4.0.0, unist-util-position is an ES module (ESM) only. CommonJS `require()` is no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update your code to include nullish checks: `const pos = position(node); if (pos) { /* use pos */ }`.","message":"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`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always use the public API surface for imports (e.g., `import { position } from 'unist-util-position'`) and avoid deep imports.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Run `npm install @types/unist@latest` or `yarn upgrade @types/unist` alongside `unist-util-position`.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `unist-util-position` (which is ESM-only) using CommonJS `require()` syntax.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/unist-util-position/index.js from ... not supported."},{"fix":"Use proper ES module named imports: `import { position, pointStart, pointEnd } from 'unist-util-position'`.","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.","error":"TypeError: position is not a function"},{"fix":"Upgrade your Node.js runtime environment to version 16 or a more recent, actively maintained version.","cause":"Running `unist-util-position` v5.0.0 or higher on an unsupported Node.js version (e.g., Node.js 14).","error":"Error: This module uses Node.js 16 or later features and cannot be run on Node.js 14."},{"fix":"Add a check for `undefined` before accessing properties, e.g., `const pos = position(node); if (pos) { console.log(pos.start.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).","error":"TypeError: Cannot read properties of undefined (reading 'line')"}],"ecosystem":"npm"}