0
# Language
1

2
Language grammar management for loading WebAssembly language modules and accessing language metadata. Languages define how to parse specific programming languages and are generated by the Tree-sitter CLI.
3

4
## Capabilities
5

6
### Language Loading
7

8
Load language grammars from WebAssembly modules.
9

10
```typescript { .api }
11
/**
12
 * Load a language from a WebAssembly module
13
 * @param input - Path to WASM file or Uint8Array containing WASM bytes
14
 * @returns Promise resolving to Language instance
15
 */
16
static load(input: string | Uint8Array): Promise<Language>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { Language } from "web-tree-sitter";
23

24
// Load from file path
25
const JavaScript = await Language.load("/path/to/tree-sitter-javascript.wasm");
26

27
// Load from URL
28
const Python = await Language.load("https://example.com/tree-sitter-python.wasm");
29

30
// Load from bytes
31
const wasmBytes = new Uint8Array(/* ... */);
32
const CustomLang = await Language.load(wasmBytes);
33
```
34

35
### Language Metadata
36

37
Access language information and compatibility details.
38

39
```typescript { .api }
40
/**
41
 * Gets the name of the language
42
 */
43
get name(): string | null;
44

45
/**
46
 * Gets the ABI version of the language
47
 */
48
get abiVersion(): number;
49

50
/**
51
 * @deprecated Use abiVersion instead
52
 * Gets the version of the language
53
 */
54
get version(): number;
55

56
/**
57
 * Get the metadata for this language from tree-sitter.json
58
 */
59
get metadata(): LanguageMetadata | null;
60
```
61

62
**Usage Example:**
63

64
```typescript
65
const language = await Language.load("/tree-sitter-javascript.wasm");
66

67
console.log(language.name); // "javascript"
68
console.log(language.abiVersion); // 14
69
console.log(language.metadata); // { major_version: 0, minor_version: 20, patch_version: 8 }
70
```
71

72
### Field Management
73

74
Work with named fields defined in the grammar.
75

76
```typescript { .api }
77
/**
78
 * Get the field id for a field name
79
 * @param fieldName - Name of the field to look up
80
 * @returns Field ID or null if not found
81
 */
82
fieldIdForName(fieldName: string): number | null;
83

84
/**
85
 * Get the field name for a field id
86
 * @param fieldId - ID of the field to look up
87
 * @returns Field name or null if not found
88
 */
89
fieldNameForId(fieldId: number): string | null;
90

91
/**
92
 * Gets the number of fields in the language
93
 */
94
get fieldCount(): number;
95

96
/** Array of all field names indexed by field ID */
97
fields: (string | null)[];
98
```
99

100
**Usage Example:**
101

102
```typescript
103
// Get field ID for "name" field
104
const nameFieldId = language.fieldIdForName("name");
105
if (nameFieldId !== null) {
106
  console.log(`Name field has ID: ${nameFieldId}`);
107
}
108

109
// List all fields
110
console.log("All fields:", language.fields);
111
console.log("Field count:", language.fieldCount);
112
```
113

114
### Node Type Information
115

116
Access information about node types defined in the grammar.
117

118
```typescript { .api }
119
/**
120
 * Get the node type id for a node type name
121
 * @param type - Name of the node type
122
 * @param named - Whether to look for named or anonymous nodes
123
 * @returns Node type ID or null if not found
124
 */
125
idForNodeType(type: string, named: boolean): number | null;
126

127
/**
128
 * Get the node type name for a node type id
129
 * @param typeId - ID of the node type
130
 * @returns Node type name or null if not found
131
 */
132
nodeTypeForId(typeId: number): string | null;
133

134
/**
135
 * Check if a node type is named
136
 * @param typeId - ID of the node type to check
137
 * @returns True if node type is named
138
 */
139
nodeTypeIsNamed(typeId: number): boolean;
140

141
/**
142
 * Check if a node type is visible
143
 * @param typeId - ID of the node type to check
144
 * @returns True if node type is visible
145
 */
146
nodeTypeIsVisible(typeId: number): boolean;
147

148
/**
149
 * Get the node type name for a node type id
150
 * @param typeId - ID of the node type to look up
151
 * @returns Node type name or null if not found
152
 */
153
nodeTypeForId(typeId: number): string | null;
154

155
/**
156
 * Gets the number of node types in the language
157
 */
158
get nodeTypeCount(): number;
159

160
/** Array of all node type names indexed by type ID */
161
types: string[];
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
// Find node type ID
168
const identifierTypeId = language.idForNodeType("identifier", true);
169
console.log("Identifier type ID:", identifierTypeId);
170

171
// Check if type is named
172
if (identifierTypeId !== null) {
173
  console.log("Is named:", language.nodeTypeIsNamed(identifierTypeId));
174
  console.log("Is visible:", language.nodeTypeIsVisible(identifierTypeId));
175
}
176

177
// List all types
178
console.log("All node types:", language.types);
179
console.log("Total types:", language.nodeTypeCount);
180
```
181

182
### Supertype and Subtype Relationships
183

184
Access hierarchical relationships between node types.
185

186
```typescript { .api }
187
/**
188
 * Get the supertypes ids of this language
189
 */
190
get supertypes(): number[];
191

192
/**
193
 * Get the subtype ids for a given supertype node id
194
 * @param supertype - ID of the supertype to get subtypes for
195
 * @returns Array of subtype IDs
196
 */
197
subtypes(supertype: number): number[];
198
```
199

200
**Usage Example:**
201

202
```typescript
203
// Get all supertypes
204
console.log("Supertypes:", language.supertypes);
205

206
// Get subtypes for a specific supertype
207
const supertypes = language.supertypes;
208
if (supertypes.length > 0) {
209
  const subtypes = language.subtypes(supertypes[0]);
210
  console.log("Subtypes:", subtypes);
211
}
212
```
213

214
### Parse State Operations
215

216
Access parse state information for advanced parsing scenarios.
217

218
```typescript { .api }
219
/**
220
 * Gets the number of states in the language
221
 */
222
get stateCount(): number;
223

224
/**
225
 * Get the next state id for a given state id and node type id
226
 * @param stateId - Current parse state ID
227
 * @param typeId - Node type ID
228
 * @returns Next parse state ID
229
 */
230
nextState(stateId: number, typeId: number): number;
231
```
232

233
### Lookahead Iterator
234

235
Create iterators for exploring valid symbols in parse states.
236

237
```typescript { .api }
238
/**
239
 * Create a new lookahead iterator for this language and parse state
240
 * @param stateId - Parse state ID to create iterator for
241
 * @returns LookaheadIterator or null if state is invalid
242
 */
243
lookaheadIterator(stateId: number): LookaheadIterator | null;
244
```
245

246
**Usage Example:**
247

248
```typescript
249
// Create lookahead iterator for error recovery
250
const errorNode = tree.rootNode.descendantsOfType("ERROR")[0];
251
if (errorNode) {
252
  const firstLeaf = errorNode.firstChild;
253
  if (firstLeaf) {
254
    const iterator = language.lookaheadIterator(firstLeaf.parseState);
255
    if (iterator) {
256
      console.log("Valid symbols:");
257
      for (const symbol of iterator) {
258
        console.log(` - ${symbol}`);
259
      }
260
      iterator.delete();
261
    }
262
  }
263
}
264
```
265

266
### Query Creation (Deprecated)
267

268
Create queries from S-expression patterns.
269

270
```typescript { .api }
271
/**
272
 * @deprecated Use new Query(language, source) instead
273
 * Create a new query from S-expression patterns
274
 * @param source - Query source containing S-expression patterns
275
 * @returns Query instance
276
 */
277
query(source: string): Query;
278
```
279

280
## Types
281

282
```typescript { .api }
283
class LanguageMetadata {
284
  readonly major_version: number;
285
  readonly minor_version: number;
286
  readonly patch_version: number;
287
}
288

289
class LookaheadIterator implements Iterable<string> {
290
  get currentTypeId(): number;
291
  get currentType(): string;
292
  delete(): void;
293
  reset(language: Language, stateId: number): boolean;
294
  resetState(stateId: number): boolean;
295
  [Symbol.iterator](): Iterator<string>;
296
}
297
```