# 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

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

For CommonJS:

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

## Basic Usage

```typescript
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.

```typescript { .api }
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](./parser.md)

### Language Handling

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

```typescript { .api }
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](./language.md)

### Syntax Tree Navigation

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

```typescript { .api }
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](./tree-node.md)

### Advanced Querying

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

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

[Query](./query.md)

### Tree Cursor

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

```typescript { .api }
class TreeCursor {
  get currentNode(): Node;
  gotoFirstChild(): boolean;
  gotoNextSibling(): boolean;
  gotoParent(): boolean;
}
```

[Tree Cursor](./tree-cursor.md)

## Core Types

```typescript { .api }
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;
```