or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-types--unist

TypeScript type definitions for unist - Universal Syntax Tree specification for syntax trees

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@types/unist@3.0.x

To install, run

npx @tessl/cli install tessl/npm-types--unist@3.0.0

Unist Types

Unist Types provides comprehensive TypeScript type definitions for the unist (Universal Syntax Tree) specification. It defines standardized interfaces for creating and working with abstract syntax trees representing source code or natural language, enabling type-safe development when working with syntax tree manipulation tools, parsers, transformers, and code analysis utilities.

Package Information

Package Name: @types/unist
Package Type: npm
Language: TypeScript
Version: 3.x (current major version)
Installation: npm install @types/unist

Version Note: This documentation covers unist types v3.x. The package also includes legacy v2 types in a separate directory with different generic interfaces, but v3 is the current recommended version.

Core Imports

import { Node, Literal, Parent, Point, Position } from "unist";

For CommonJS:

const { Node, Literal, Parent, Point, Position } = require("unist");

Note: The Data interface is typically used via module augmentation rather than direct import.

Basic Usage

import { Node, Literal, Parent, Point, Position } from "unist";

// Create a point in source code
const point: Point = {
  line: 1,
  column: 1,
  offset: 0
};

// Create a position range
const position: Position = {
  start: point,
  end: { line: 1, column: 5, offset: 4 }
};

// Create a basic node
const baseNode: Node = {
  type: "node",
  position
};

// Create a literal node (leaf node with value)
const textNode: Literal = {
  type: "text",
  value: "Hello",
  position
};

// Create a parent node (container with children)
const paragraph: Parent = {
  type: "parent",
  children: [baseNode, textNode],
  position
};

Architecture

Unist types are built around a hierarchical node system:

Node: Base interface for all syntax tree elements
Literal: Extends Node for leaf nodes containing values
Parent: Extends Node for container nodes with children
Position/Point: Location tracking interfaces for source mapping
Data: Extensible metadata interface for ecosystem-specific information

The type system supports module augmentation to extend the Data interface for custom properties.

Capabilities

Core Node Types

Base interfaces for all unist syntax tree nodes.

/**
 * Abstract unist node - the smallest syntactic unit in unist syntax trees
 */
interface Node {
  /** Node type identifier */
  type: string;
  /** Info from the ecosystem */
  data?: Data | undefined;
  /** Position in source document */
  position?: Position | undefined;
}

/**
 * Abstract unist node that contains the smallest possible value
 */
interface Literal extends Node {
  /** Plain value contained in the literal node */
  value: unknown;
}

/**
 * Abstract unist node that contains other nodes (children)
 */
interface Parent extends Node {
  /** List of child nodes */
  children: Node[];
}

Position Tracking

Interfaces for tracking location information in source documents.

/**
 * One place in a source file
 */
interface Point {
  /** Line in source file (1-indexed integer) */
  line: number;
  /** Column in source file (1-indexed integer) */
  column: number;
  /** Character in source file (0-indexed integer) */
  offset?: number | undefined;
}

/**
 * Position of a node in a source document (range between two points)
 */
interface Position {
  /** Place of the first character of the parsed source region */
  start: Point;
  /** Place of the first character after the parsed source region */
  end: Point;
}

Extensible Data

Interface for storing ecosystem-specific metadata.

/**
 * Info associated with nodes by the ecosystem.
 * This space is guaranteed to never be specified by unist or specifications
 * implementing unist. You can use it in utilities and plugins to store data.
 * This type can be augmented to register custom data.
 */
interface Data {}

Module Augmentation:

The Data interface is designed to be extended via module augmentation to add ecosystem-specific properties:

declare module 'unist' {
  interface Data {
    // `someNode.data.myId` is typed as `number | undefined`
    myId?: number | undefined;
    // Add more custom properties as needed
    metadata?: Record<string, unknown>;
  }
}

Usage Examples

Creating Syntax Trees

import { Node, Literal, Parent } from "unist";

// Create a simple text node
const textNode: Literal = {
  type: "text",
  value: "Hello world"
};

// Create a container node
const paragraph: Parent = {
  type: "paragraph",
  children: [textNode]
};

// Create a document root
const document: Parent = {
  type: "root",
  children: [paragraph]
};

Working with Positions

import { Point, Position, Node } from "unist";

// Track source locations
const startPoint: Point = { line: 1, column: 1, offset: 0 };
const endPoint: Point = { line: 1, column: 6, offset: 5 };

const nodeWithPosition: Node = {
  type: "emphasis",
  position: {
    start: startPoint,
    end: endPoint
  }
};

Extending with Custom Data

// Augment the Data interface
declare module 'unist' {
  interface Data {
    sourceId?: string;
    metadata?: Record<string, unknown>;
  }
}

// Use custom data
const nodeWithData: Node = {
  type: "custom",
  data: {
    sourceId: "file1.md",
    metadata: { author: "Alice" }
  }
};

Type Guards and Utilities

import { Node, Literal, Parent } from "unist";

// Type guard for literal nodes
function isLiteral(node: Node): node is Literal {
  return 'value' in node;
}

// Type guard for parent nodes
function isParent(node: Node): node is Parent {
  return 'children' in node;
}

// Example utility function
function collectAllText(node: Node): string {
  if (isLiteral(node)) {
    return String(node.value);
  }
  
  if (isParent(node)) {
    return node.children.map(collectAllText).join('');
  }
  
  return '';
}