unist-util-lsp Conversion Utility

2.1.0 · active · verified Sun Apr 19

The `unist-util-lsp` library provides a focused set of utility functions to accurately convert positional information between unist (Universal Syntax Tree) nodes and the Language Server Protocol (LSP) format. This is crucial for developers building sophisticated tooling, such as IDE extensions or linters, that operate on both ASTs and interact with LSP-compliant language servers. The current stable version is 2.1.0, with an active release cadence demonstrating ongoing maintenance and feature additions. Key differentiators include its tight integration with the unist ecosystem and its precise mapping to LSP’s `Range` and `Position` types, making it an essential bridge for creating robust language-aware applications. It primarily targets environments supporting ECMAScript Modules (ESM) and requires Node.js version 16 or higher.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import an ESM-only package.

fix Change CommonJS `require()` calls to ES Module `import` statements: `import { fromPoint } from 'unist-util-lsp'`.
```
TypeError: Cannot read properties of undefined (reading 'start')
```
cause Attempting to access properties of a `null` or `undefined` Unist point/position.

fix Ensure the `place` argument passed to utilities like `fromPoint` or `fromPosition` is a valid `UnistPoint` or `UnistPosition` object, not nullish.

Warnings

breaking Version 2.0.0 of `unist-util-lsp` changed to require Node.js 16 or newer. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or higher. For example, use `nvm install 16 && nvm use 16`.
breaking Starting with v2.0.0, the package is ESM-only. CommonJS `require()` statements will no longer work.
Fix: Migrate your project to use ES Modules `import` syntax. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions.
breaking Version 2.0.0 updated its dependency on `@types/unist`. Users leveraging TypeScript should ensure their `@types/unist` dependency is also updated to avoid type mismatches.
Fix: Update your `@types/unist` package to the latest compatible version (e.g., `npm update @types/unist`).
gotcha The `fromPlace` utility was added in version 2.1.0. If you are on an earlier `2.x` version, this function will not be available.
Fix: Ensure you are using `unist-util-lsp` version 2.1.0 or newer if you intend to use the `fromPlace` function.

Install

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

Imports

fromPoint
wrong:
```
const { fromPoint } = require('unist-util-lsp')
```
correct:
```
import { fromPoint } from 'unist-util-lsp'
```
This package is ESM-only since v2.0.0. Use `import` syntax. `fromPoint` converts a unist point to an LSP position.
toPosition
wrong:
```
import toPosition from 'unist-util-lsp'
```
correct:
```
import { toPosition } from 'unist-util-lsp'
```
There is no default export; all utilities are named exports. `toPosition` converts an LSP range to a unist position.
fromPlace
wrong:
```
import { fromPlace } from 'unist-util-lsp/fromPlace'
```
correct:
```
import { fromPlace } from 'unist-util-lsp'
```
`fromPlace` was added in v2.1.0. It converts a unist point or position to an LSP range.

Quickstart

This example demonstrates how to use the core conversion utilities to map positional data between unist and LSP formats, including converting full positions and individual points, and showcasing the `fromPlace` utility.

import { fromMarkdown } from 'mdast-util-from-markdown';
import {
  fromPlace,
  fromPoint,
  fromPosition,
  toPoint,
  toPosition
} from 'unist-util-lsp';

const markdown = '## Hello **World**!\n';
const mdast = fromMarkdown(markdown);

console.log('Unist Position:', mdast.position);

// Convert unist position to LSP range
const lspRange = fromPosition(mdast.position);
console.log('LSP Range from Unist Position:', lspRange);

// Convert LSP range back to unist position
const unistPosition = toPosition(lspRange);
console.log('Unist Position from LSP Range:', unistPosition);

// Convert unist point (start of the AST) to LSP position
const lspStartPosition = fromPoint(mdast.position.start);
console.log('LSP Position from Unist Start Point:', lspStartPosition);

// Convert LSP position back to unist point
const unistStartPoint = toPoint(lspStartPosition);
console.log('Unist Point from LSP Start Position:', unistStartPoint);

// Convert a unist place (point or position) to an LSP range (introduced in v2.1.0)
const fullRangeFromPlace = fromPlace(mdast.position);
console.log('LSP Range from Unist Position (via fromPlace):', fullRangeFromPlace);

const startRangeFromPlace = fromPlace(mdast.position.start);
console.log('LSP Range from Unist Start Point (via fromPlace):', startRangeFromPlace);

view raw JSON →