or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdlanguage.mdparser.mdquery.mdtree-cursor.mdtree-node.md
tile.json

tessl/npm-web-tree-sitter

Tree-sitter bindings for the web providing WebAssembly-based incremental parsing of source code

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/web-tree-sitter@0.25.x

To install, run

npx @tessl/cli install tessl/npm-web-tree-sitter@0.25.0

index.mddocs/

Web Tree-sitter

Web Tree-sitter provides WebAssembly bindings for the Tree-sitter parsing library, enabling incremental parsing of source code in web browsers and Node.js environments. It offers a comprehensive JavaScript/TypeScript API for creating parsers, loading language grammars as WebAssembly modules, parsing source code into syntax trees, and performing efficient incremental updates when code changes.

Package Information

  • Package Name: web-tree-sitter
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install web-tree-sitter
  • WebAssembly: Requires WebAssembly support

Core Imports

import { Parser, Language, Tree, Node, Query } from "web-tree-sitter";

For CommonJS:

const { Parser, Language, Tree, Node, Query } = require("web-tree-sitter");

Basic Usage

import { Parser, Language } from "web-tree-sitter";

// Initialize the WebAssembly module
await Parser.init();

// Load a language grammar (e.g., JavaScript)
const JavaScript = await Language.load("/path/to/tree-sitter-javascript.wasm");

// Create parser and set language
const parser = new Parser();
parser.setLanguage(JavaScript);

// Parse source code
const sourceCode = "let x = 1 + 2;";
const tree = parser.parse(sourceCode);

// Access the syntax tree
const rootNode = tree.rootNode;
console.log(rootNode.toString()); // S-expression representation
console.log(rootNode.type); // "program"

// Navigate the tree
const firstChild = rootNode.firstChild; // "let" statement
console.log(firstChild.type); // "lexical_declaration"

Architecture

Web Tree-sitter is built around several key components:

  • Parser: Stateful parsing engine that converts source code into syntax trees
  • Language: Grammar definitions compiled to WebAssembly modules for specific programming languages
  • Tree: Immutable syntax tree representing parsed source code structure
  • Node: Individual elements within the syntax tree with navigation and query capabilities
  • Query: S-expression pattern matching for advanced tree traversal and analysis
  • Incremental Parsing: Efficient re-parsing when source code changes using edit operations

Capabilities

Parser Management

Core parsing functionality for creating parsers, setting languages, and converting source code into syntax trees.

class Parser {
  static init(moduleOptions?: EmscriptenModule): Promise<void>;
  constructor();
  setLanguage(language: Language | null): this;
  parse(callback: string | ParseCallback, oldTree?: Tree | null, options?: ParseOptions): Tree | null;
}

Parser

Language Handling

Language grammar management for loading WebAssembly language modules and accessing language metadata.

class Language {
  static load(input: string | Uint8Array): Promise<Language>;
  get name(): string | null;
  get abiVersion(): number;
  fieldIdForName(fieldName: string): number | null;
  idForNodeType(type: string, named: boolean): number | null;
}

Language

Syntax Tree Navigation

Tree and node functionality for traversing and analyzing parsed syntax trees.

class Tree {
  get rootNode(): Node;
  edit(edit: Edit): void;
  getChangedRanges(other: Tree): Range[];
}

class Node {
  get type(): string;
  get children(): (Node | null)[];
  childForFieldName(fieldName: string): Node | null;
  descendantsOfType(types: string | string[]): (Node | null)[];
}

Tree & Node

Advanced Querying

Pattern-based querying for complex syntax tree analysis and extraction.

class Query {
  constructor(language: Language, source: string);
  matches(node: Node, options?: QueryOptions): QueryMatch[];
  captures(node: Node, options?: QueryOptions): QueryCapture[];
}

Query

Tree Cursor

Efficient tree traversal using stateful cursors for performance-critical applications.

class TreeCursor {
  get currentNode(): Node;
  gotoFirstChild(): boolean;
  gotoNextSibling(): boolean;
  gotoParent(): boolean;
}

Tree Cursor

Core Types

interface Point {
  row: number;
  column: number;
}

interface Range {
  startPosition: Point;
  endPosition: Point;
  startIndex: number;
  endIndex: number;
}

interface Edit {
  startPosition: Point;
  oldEndPosition: Point;
  newEndPosition: Point;
  startIndex: number;
  oldEndIndex: number;
  newEndIndex: number;
}

interface ParseState {
  currentOffset: number;
  hasError: boolean;
}

type ParseCallback = (index: number, position: Point) => string | undefined;
type ProgressCallback = (progress: ParseState) => boolean;
type LogCallback = (message: string, isLex: boolean) => void;

const LANGUAGE_VERSION: number;
const MIN_COMPATIBLE_VERSION: number;