# Language

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.

## Capabilities

### Language Loading

Load language grammars from WebAssembly modules.

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

**Usage Examples:**

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

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

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

// Load from bytes
const wasmBytes = new Uint8Array(/* ... */);
const CustomLang = await Language.load(wasmBytes);
```

### Language Metadata

Access language information and compatibility details.

```typescript { .api }
/**
 * Gets the name of the language
 */
get name(): string | null;

/**
 * Gets the ABI version of the language
 */
get abiVersion(): number;

/**
 * @deprecated Use abiVersion instead
 * Gets the version of the language
 */
get version(): number;

/**
 * Get the metadata for this language from tree-sitter.json
 */
get metadata(): LanguageMetadata | null;
```

**Usage Example:**

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

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

### Field Management

Work with named fields defined in the grammar.

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

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

/**
 * Gets the number of fields in the language
 */
get fieldCount(): number;

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

**Usage Example:**

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

// List all fields
console.log("All fields:", language.fields);
console.log("Field count:", language.fieldCount);
```

### Node Type Information

Access information about node types defined in the grammar.

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

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

/**
 * Check if a node type is named
 * @param typeId - ID of the node type to check
 * @returns True if node type is named
 */
nodeTypeIsNamed(typeId: number): boolean;

/**
 * Check if a node type is visible
 * @param typeId - ID of the node type to check
 * @returns True if node type is visible
 */
nodeTypeIsVisible(typeId: number): boolean;

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

/**
 * Gets the number of node types in the language
 */
get nodeTypeCount(): number;

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

**Usage Examples:**

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

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

// List all types
console.log("All node types:", language.types);
console.log("Total types:", language.nodeTypeCount);
```

### Supertype and Subtype Relationships

Access hierarchical relationships between node types.

```typescript { .api }
/**
 * Get the supertypes ids of this language
 */
get supertypes(): number[];

/**
 * Get the subtype ids for a given supertype node id
 * @param supertype - ID of the supertype to get subtypes for
 * @returns Array of subtype IDs
 */
subtypes(supertype: number): number[];
```

**Usage Example:**

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

// Get subtypes for a specific supertype
const supertypes = language.supertypes;
if (supertypes.length > 0) {
  const subtypes = language.subtypes(supertypes[0]);
  console.log("Subtypes:", subtypes);
}
```

### Parse State Operations

Access parse state information for advanced parsing scenarios.

```typescript { .api }
/**
 * Gets the number of states in the language
 */
get stateCount(): number;

/**
 * Get the next state id for a given state id and node type id
 * @param stateId - Current parse state ID
 * @param typeId - Node type ID
 * @returns Next parse state ID
 */
nextState(stateId: number, typeId: number): number;
```

### Lookahead Iterator

Create iterators for exploring valid symbols in parse states.

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

**Usage Example:**

```typescript
// Create lookahead iterator for error recovery
const errorNode = tree.rootNode.descendantsOfType("ERROR")[0];
if (errorNode) {
  const firstLeaf = errorNode.firstChild;
  if (firstLeaf) {
    const iterator = language.lookaheadIterator(firstLeaf.parseState);
    if (iterator) {
      console.log("Valid symbols:");
      for (const symbol of iterator) {
        console.log(` - ${symbol}`);
      }
      iterator.delete();
    }
  }
}
```

### Query Creation (Deprecated)

Create queries from S-expression patterns.

```typescript { .api }
/**
 * @deprecated Use new Query(language, source) instead
 * Create a new query from S-expression patterns
 * @param source - Query source containing S-expression patterns
 * @returns Query instance
 */
query(source: string): Query;
```

## Types

```typescript { .api }
class LanguageMetadata {
  readonly major_version: number;
  readonly minor_version: number;
  readonly patch_version: number;
}

class LookaheadIterator implements Iterable<string> {
  get currentTypeId(): number;
  get currentType(): string;
  delete(): void;
  reset(language: Language, stateId: number): boolean;
  resetState(stateId: number): boolean;
  [Symbol.iterator](): Iterator<string>;
}
```