Unist Utility to Stringify Position

4.0.0 · active · verified Sun Apr 19

unist-util-stringify-position is a utility package within the unified (unist) ecosystem designed to consistently serialize positional information from abstract syntax tree (AST) nodes, positions, or points into a human-readable string format. This is particularly useful for generating error messages, warnings, or logging location-specific information in parsers, compilers, and transformers. The current stable version is 4.0.0, which was released recently and is actively maintained by the syntax-tree collective. Its release cadence is tied to breaking changes and necessary updates within the broader unist ecosystem. Key differentiators include its adherence to the unist specification, full TypeScript support, and its focus on standardizing how location data is presented to end-users, ensuring consistency across various unified processors like `remark` or `rehype`.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require` this ESM-only package in a CommonJS context.

fix Use `import { stringifyPosition } from 'unist-util-stringify-position'` instead of `require`. Ensure your Node.js project or file is configured for ES modules (e.g., `"type": "module"` in `package.json`).
```
TypeError: stringifyPosition is not a function
```
cause Incorrect CommonJS `require` attempt, often occurring when trying to destructure named exports from an ESM-only package without a default export.

fix This package exports named exports. If you're in an ESM context, use `import { stringifyPosition } from 'unist-util-stringify-position'`. If you're stuck in CommonJS, consider dynamically `import`ing or transpiling your code.

Warnings

breaking Version 4.0.0 changes the minimum required Node.js version to 16 or later.
Fix: Update your Node.js runtime environment to version 16 or newer to ensure compatibility.
breaking The package switched to ESM-only in v3.0.0 and further adopted `export` maps in v4.0.0, meaning CommonJS `require` statements are no longer supported for importing this package.
Fix: Migrate your project to use ES modules (`import`/`export` syntax). If in Node.js, ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions. Consult the Node.js documentation on ESM for proper setup.
gotcha Version 4.0.0 includes an update to its `@types/unist` dependency, which might cause type conflicts if your project uses an incompatible older version of `@types/unist`.
Fix: Ensure your project's `@types/unist` dependency is also updated to a compatible version (e.g., `^4.0.0` or higher) to align with this package's types.

Install

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

Imports

stringifyPosition
wrong:
```
const stringifyPosition = require('unist-util-stringify-position')
```
correct:
```
import { stringifyPosition } from 'unist-util-stringify-position'
```
This package is ESM-only since v3.0.0, and v4.0.0 further enforces this with an `export` map. CommonJS `require` is not supported for direct import.

Quickstart

Demonstrates how to use `stringifyPosition` to convert a point, position range, or a unist node's position into a human-readable string format, returning an empty string for invalid inputs.

import { stringifyPosition } from 'unist-util-stringify-position';

console.log('Point:', stringifyPosition({line: 2, column: 3}));
// => '2:3'

console.log('Position:', stringifyPosition({start: {line: 2, column: 1}, end: {line: 3, column: 1}}));
// => '2:1-3:1'

console.log('Node:', stringifyPosition({
  type: 'text',
  value: '!',
  position: {
    start: {line: 5, column: 11},
    end: {line: 5, column: 12}
  }
}));
// => '5:11-5:12'

console.log('Invalid input:', stringifyPosition(null));
// => ''

view raw JSON →