0
# Web Tree-sitter
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: web-tree-sitter
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install web-tree-sitter`
10
- **WebAssembly**: Requires WebAssembly support
11

12
## Core Imports
13

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

18
For CommonJS:
19

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

24
## Basic Usage
25

26
```typescript
27
import { Parser, Language } from "web-tree-sitter";
28

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

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

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

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

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

48
// Navigate the tree
49
const firstChild = rootNode.firstChild; // "let" statement
50
console.log(firstChild.type); // "lexical_declaration"
51
```
52

53
## Architecture
54

55
Web Tree-sitter is built around several key components:
56

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

64
## Capabilities
65

66
### Parser Management
67

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

70
```typescript { .api }
71
class Parser {
72
  static init(moduleOptions?: EmscriptenModule): Promise<void>;
73
  constructor();
74
  setLanguage(language: Language | null): this;
75
  parse(callback: string | ParseCallback, oldTree?: Tree | null, options?: ParseOptions): Tree | null;
76
}
77
```
78

79
[Parser](./parser.md)
80

81
### Language Handling
82

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

85
```typescript { .api }
86
class Language {
87
  static load(input: string | Uint8Array): Promise<Language>;
88
  get name(): string | null;
89
  get abiVersion(): number;
90
  fieldIdForName(fieldName: string): number | null;
91
  idForNodeType(type: string, named: boolean): number | null;
92
}
93
```
94

95
[Language](./language.md)
96

97
### Syntax Tree Navigation
98

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

101
```typescript { .api }
102
class Tree {
103
  get rootNode(): Node;
104
  edit(edit: Edit): void;
105
  getChangedRanges(other: Tree): Range[];
106
}
107

108
class Node {
109
  get type(): string;
110
  get children(): (Node | null)[];
111
  childForFieldName(fieldName: string): Node | null;
112
  descendantsOfType(types: string | string[]): (Node | null)[];
113
}
114
```
115

116
[Tree & Node](./tree-node.md)
117

118
### Advanced Querying
119

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

122
```typescript { .api }
123
class Query {
124
  constructor(language: Language, source: string);
125
  matches(node: Node, options?: QueryOptions): QueryMatch[];
126
  captures(node: Node, options?: QueryOptions): QueryCapture[];
127
}
128
```
129

130
[Query](./query.md)
131

132
### Tree Cursor
133

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

136
```typescript { .api }
137
class TreeCursor {
138
  get currentNode(): Node;
139
  gotoFirstChild(): boolean;
140
  gotoNextSibling(): boolean;
141
  gotoParent(): boolean;
142
}
143
```
144

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

147
## Core Types
148

149
```typescript { .api }
150
interface Point {
151
  row: number;
152
  column: number;
153
}
154

155
interface Range {
156
  startPosition: Point;
157
  endPosition: Point;
158
  startIndex: number;
159
  endIndex: number;
160
}
161

162
interface Edit {
163
  startPosition: Point;
164
  oldEndPosition: Point;
165
  newEndPosition: Point;
166
  startIndex: number;
167
  oldEndIndex: number;
168
  newEndIndex: number;
169
}
170

171
interface ParseState {
172
  currentOffset: number;
173
  hasError: boolean;
174
}
175

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

180
const LANGUAGE_VERSION: number;
181
const MIN_COMPATIBLE_VERSION: number;
182
```