Query API - Tree-sitter

The Query class allows you to search for patterns in syntax trees using a powerful pattern matching language. Queries are written in a Scheme-like S-expression syntax.

Constructor

`new Query(language, source)`

Create a new query from a string containing one or more S-expression patterns.

constructor(language: Language, source: string)

Parameters:

language - The Language object associated with the query
source - A string containing one or more query patterns

Throws: QueryError if the query string is invalid Example:

import { Query } from 'web-tree-sitter';

const query = new Query(JavaScript, `
  (function_declaration
    name: (identifier) @function.name)
  
  (call_expression
    function: (identifier) @function.call)
`);

Properties

`captureNames`

The names of the captures used in the query.

readonly captureNames: string[]

Example:

const query = new Query(JavaScript, '(identifier) @var');
console.log(query.captureNames); // ['var']

`captureQuantifiers`

The quantifiers of the captures used in the query.

readonly captureQuantifiers: CaptureQuantifier[][]

Quantifier values:

CaptureQuantifier.Zero (0) - Zero occurrences
CaptureQuantifier.ZeroOrOne (1) - Zero or one occurrence
CaptureQuantifier.ZeroOrMore (2) - Zero or more occurrences
CaptureQuantifier.One (3) - Exactly one occurrence
CaptureQuantifier.OneOrMore (4) - One or more occurrences

`predicates`

User-defined predicates associated with each pattern.

readonly predicates: QueryPredicate[][]

This includes predicates other than the built-in ones (match?, eq?, any-of?, is?, is-not?, set!).

`setProperties`

Properties set via the #set! directive for each pattern.

readonly setProperties: QueryProperties[]

`assertedProperties`

Properties asserted via the #is? directive for each pattern.

readonly assertedProperties: QueryProperties[]

`refutedProperties`

Properties refuted via the #is-not? directive for each pattern.

readonly refutedProperties: QueryProperties[]

Methods

`matches(node, options?)`

Execute the query and return all matches in the order they were found.

matches(node: Node, options?: QueryOptions): QueryMatch[]

Parameters:

node - The node to execute the query on (typically the root node)
options (optional) - Options for query execution

Returns: An array of QueryMatch objects Example:

const tree = parser.parse('function one() { two(); function three() {} }');

const query = new Query(JavaScript, `
  (function_declaration name: (identifier) @fn-def)
  (call_expression function: (identifier) @fn-ref)
`);

const matches = query.matches(tree.rootNode);

for (const match of matches) {
  console.log('Pattern:', match.patternIndex);
  for (const capture of match.captures) {
    console.log('  Capture:', capture.name, '=', capture.node.text);
  }
}
// Pattern: 0
//   Capture: fn-def = one
// Pattern: 1
//   Capture: fn-ref = two
// Pattern: 0
//   Capture: fn-def = three

`captures(node, options?)`

Execute the query and return all individual captures in the order they appear.

captures(node: Node, options?: QueryOptions): QueryCapture[]

Parameters:

node - The node to execute the query on
options (optional) - Options for query execution

Returns: An array of QueryCapture objects Example:

const tree = parser.parse('const a = 1, b = 2, c = 3;');

const query = new Query(JavaScript, '(identifier) @var');
const captures = query.captures(tree.rootNode);

for (const capture of captures) {
  console.log(capture.name, ':', capture.node.text);
}
// var : a
// var : b
// var : c

Use captures() when you want a single ordered sequence of all captures, regardless of which pattern matched. Use matches() when you care about which pattern matched and need to see all captures grouped by match.

Query Options

Both matches() and captures() accept an optional options parameter:

interface QueryOptions {
  // Byte range
  startIndex?: number;
  endIndex?: number;
  
  // Position range
  startPosition?: Point;
  endPosition?: Point;
  
  // Containing byte range (matches must be fully contained)
  startContainingIndex?: number;
  endContainingIndex?: number;
  
  // Containing position range (matches must be fully contained)
  startContainingPosition?: Point;
  endContainingPosition?: Point;
  
  // Performance tuning
  matchLimit?: number;      // Max in-progress matches (default: 0xFFFFFFFF)
  maxStartDepth?: number;   // Max depth to search (default: 0xFFFFFFFF)
  
  // Progress callback
  progressCallback?: (state: QueryState) => void;
}

Example with range:

const captures = query.captures(tree.rootNode, {
  startPosition: { row: 10, column: 0 },
  endPosition: { row: 20, column: 0 },
});

Example with timeout:

const startTime = Date.now();
const captures = query.captures(tree.rootNode, {
  progressCallback: (state) => {
    if (Date.now() - startTime > 1000) {
      return true; // Cancel query
    }
  },
});

Pattern Information

`patternCount()`

Get the number of patterns in the query.

patternCount(): number

`startIndexForPattern(patternIndex)`

Get the byte offset where the given pattern starts in the query’s source.

startIndexForPattern(patternIndex: number): number

`endIndexForPattern(patternIndex)`

Get the byte offset where the given pattern ends in the query’s source.

endIndexForPattern(patternIndex: number): number

`predicatesForPattern(patternIndex)`

Get the predicates for a given pattern.

predicatesForPattern(patternIndex: number): QueryPredicate[]

`isPatternRooted(patternIndex)`

Check if a given pattern has a single root node.

isPatternRooted(patternIndex: number): boolean

`isPatternNonLocal(patternIndex)`

Check if a given pattern is non-local (can match at any depth).

isPatternNonLocal(patternIndex: number): boolean

`isPatternGuaranteedAtStep(byteIndex)`

Check if a given step in a query is ‘definite’ (guaranteed to match once reached).

isPatternGuaranteedAtStep(byteIndex: number): boolean

Capture Information

`captureIndexForName(captureName)`

Get the index for a given capture name.

captureIndexForName(captureName: string): number

Returns: The index, or -1 if not found Example:

const query = new Query(JavaScript, '(identifier) @var');
const index = query.captureIndexForName('var');
console.log(index); // 0

Disabling Patterns and Captures

`disablePattern(patternIndex)`

Disable a pattern, preventing it from matching.

disablePattern(patternIndex: number): void

Example:

const query = new Query(JavaScript, `
  (function_declaration) @func
  (class_declaration) @class
`);

// Disable the class pattern
query.disablePattern(1);

const captures = query.captures(tree.rootNode);
// Will only find functions, not classes

`disableCapture(captureName)`

Disable a capture, preventing it from being returned in results.

disableCapture(captureName: string): void

Example:

const query = new Query(JavaScript, `
  (function_declaration name: (identifier) @name body: (statement_block) @body)
`);

query.disableCapture('body');

const captures = query.captures(tree.rootNode);
// Will only return @name captures

Match Limit

`didExceedMatchLimit()`

Check if the query exceeded its maximum number of in-progress matches on the last execution.

didExceedMatchLimit(): boolean

Example:

const matches = query.matches(tree.rootNode, { matchLimit: 100 });

if (query.didExceedMatchLimit()) {
  console.warn('Query hit match limit - results may be incomplete');
}

`delete()`

Delete the query and free its resources.

delete(): void

Types

`QueryMatch`

A match of a query to a set of nodes.

interface QueryMatch {
  patternIndex: number;              // Index of the pattern that matched
  captures: QueryCapture[];          // All captures in this match
  setProperties?: QueryProperties;   // Properties from #set!
  assertedProperties?: QueryProperties; // Properties from #is?
  refutedProperties?: QueryProperties;  // Properties from #is-not?
}

`QueryCapture`

A particular node that has been captured with a name.

interface QueryCapture {
  patternIndex: number;              // Index of the pattern
  name: string;                      // Name of the capture
  node: Node;                        // The captured node
  setProperties?: QueryProperties;   // Properties from #set!
  assertedProperties?: QueryProperties; // Properties from #is?
  refutedProperties?: QueryProperties;  // Properties from #is-not?
}

`QueryPredicate`

A predicate that contains an operator and operands.

interface QueryPredicate {
  operator: string;           // e.g., 'match?', 'eq?', 'set!'
  operands: PredicateStep[];  // Captures or strings
}

`PredicateStep`

A step in a predicate (either a capture or a string).

type PredicateStep = CapturePredicateStep | StringPredicateStep;

interface CapturePredicateStep {
  type: 'capture';
  name: string;
}

interface StringPredicateStep {
  type: 'string';
  value: string;
}

`QueryError`

Error thrown when parsing a query fails.

class QueryError extends Error {
  kind: QueryErrorKind;
  info: QueryErrorInfo[typeof kind];
  index: number;  // Byte offset where error occurred
  length: number; // Length of the error region
}

Error kinds:

QueryErrorKind.Syntax (1) - Syntax error
QueryErrorKind.NodeName (2) - Invalid node type name
QueryErrorKind.FieldName (3) - Invalid field name
QueryErrorKind.CaptureName (4) - Invalid capture name
QueryErrorKind.PatternStructure (5) - Invalid pattern structure

Query Language

Basic Patterns

Match nodes by type:

(function_declaration) @function

Match with fields:

(function_declaration
  name: (identifier) @name
  body: (statement_block) @body)

Match nested structures:

(call_expression
  function: (member_expression
    object: (identifier) @object
    property: (property_identifier) @method))

Wildcards

Match any node:

(function_declaration
  name: (_) @name)  ; Any node type

Anonymous Nodes

Match literal tokens:

(binary_expression
  left: (_) @left
  operator: "+"    ; Match literal '+' token
  right: (_) @right)

Alternation

Match multiple patterns:

[
  (function_declaration) @function
  (class_declaration) @class
]

Negation

Match nodes that are NOT a certain type:

(call_expression
  function: (identifier) @func
  (#not-eq? @func "console"))

Predicates

Text Predicates

Match against regex:

((identifier) @constant
  (#match? @constant "^[A-Z_]+$"))

String equality:

((identifier) @console
  (#eq? @console "console"))

Compare two captures:

((assignment_expression
  left: (identifier) @left
  right: (identifier) @right)
  (#eq? @left @right))  ; Same variable on both sides

Check against multiple values:

((identifier) @keyword
  (#any-of? @keyword "if" "else" "while" "for"))

Property Predicates

Assert a property:

((identifier) @local
  (#is? local))

Refute a property:

((identifier) @global
  (#is-not? local))

Set a property:

((function_declaration) @func
  (#set! kind "function"))

Quantifiers

Match multiple children:

; Zero or more
(call_expression
  arguments: (arguments (_)* @arg))

; One or more
(array (_)+ @element)

; Optional
(function_declaration
  name: (identifier)? @name)

Examples

Find All Function Calls

const query = new Query(JavaScript, `
  (call_expression
    function: (identifier) @function)
`);

const captures = query.captures(tree.rootNode);
for (const { node } of captures) {
  console.log('Function call:', node.text);
}

Find Unused Variables

const query = new Query(JavaScript, `
  (lexical_declaration
    (variable_declarator
      name: (identifier) @var.def))
  
  (identifier) @var.use
`);

const captures = query.captures(tree.rootNode);
const defined = new Set();
const used = new Set();

for (const capture of captures) {
  if (capture.name === 'var.def') {
    defined.add(capture.node.text);
  } else {
    used.add(capture.node.text);
  }
}

const unused = [...defined].filter(v => !used.has(v));
console.log('Unused variables:', unused);

Extract Function Names and Bodies

const query = new Query(JavaScript, `
  (function_declaration
    name: (identifier) @name
    body: (statement_block) @body)
`);

const matches = query.matches(tree.rootNode);

for (const match of matches) {
  const name = match.captures.find(c => c.name === 'name');
  const body = match.captures.find(c => c.name === 'body');
  
  console.log('Function:', name.node.text);
  console.log('Body:', body.node.text);
}

Find JSX Components

const query = new Query(JSX, `
  (jsx_element
    open_tag: (jsx_opening_element
      name: (identifier) @component))
`);

const components = query.captures(tree.rootNode)
  .map(c => c.node.text)
  .filter((name, i, arr) => arr.indexOf(name) === i); // unique

console.log('Components used:', components);

Documentation Index

​Constructor

​new Query(language, source)

​Properties

​captureNames

​captureQuantifiers

​predicates

​setProperties

​assertedProperties

​refutedProperties

​Methods

​matches(node, options?)

​captures(node, options?)

​Query Options

​Pattern Information

​patternCount()

​startIndexForPattern(patternIndex)

​endIndexForPattern(patternIndex)

​predicatesForPattern(patternIndex)

​isPatternRooted(patternIndex)

​isPatternNonLocal(patternIndex)

​isPatternGuaranteedAtStep(byteIndex)

​Capture Information

​captureIndexForName(captureName)

​Disabling Patterns and Captures

​disablePattern(patternIndex)

​disableCapture(captureName)

​Match Limit

​didExceedMatchLimit()

​delete()

​Types

​QueryMatch

​QueryCapture

​QueryPredicate

​PredicateStep

​QueryError

​Query Language

​Basic Patterns

​Wildcards

​Anonymous Nodes

​Alternation

​Negation

​Predicates

​Text Predicates

​Property Predicates

​Quantifiers

​Examples

​Find All Function Calls

​Find Unused Variables

​Extract Function Names and Bodies

​Find JSX Components

​See Also

Constructor

`new Query(language, source)`

Properties

`captureNames`

`captureQuantifiers`

`predicates`

`setProperties`

`assertedProperties`

`refutedProperties`

Methods

`matches(node, options?)`

`captures(node, options?)`

Query Options

Pattern Information

`patternCount()`

`startIndexForPattern(patternIndex)`

`endIndexForPattern(patternIndex)`

`predicatesForPattern(patternIndex)`

`isPatternRooted(patternIndex)`

`isPatternNonLocal(patternIndex)`

`isPatternGuaranteedAtStep(byteIndex)`

Capture Information

`captureIndexForName(captureName)`

Disabling Patterns and Captures

`disablePattern(patternIndex)`

`disableCapture(captureName)`

Match Limit

`didExceedMatchLimit()`

`delete()`

Types

`QueryMatch`

`QueryCapture`

`QueryPredicate`

`PredicateStep`

`QueryError`

Query Language

Basic Patterns

Wildcards

Anonymous Nodes

Alternation

Negation

Predicates

Text Predicates

Property Predicates

Quantifiers

Examples

Find All Function Calls

Find Unused Variables

Extract Function Names and Bodies

Find JSX Components

See Also