TSQuery

TSQuery is a port of the ESQuery API for TypeScript! TSQuery allows you to query a TypeScript AST for patterns of syntax using a CSS style selector system.

Demos:

ESQuery demo - note that the demo requires JavaScript code, not TypeScript TSQuery demo by Uri Shaked

Installation

1npm install @phenomnomnominal/tsquery --save-dev

Examples

Say we want to select all instances of an identifier with name "Animal", e.g. the identifier in the class declaration, and the identifier in the extends declaration.

We would do something like the following:

1import { ast, query } from '@phenomnomnominal/tsquery';
2
3const typescript = `
4
5class Animal {
6    constructor(public name: string) { }
7    move(distanceInMeters: number = 0) {
8        console.log(\`\${this.name} moved \${distanceInMeters}m.\`);
9    }
10}
11
12class Snake extends Animal {
13    constructor(name: string) { super(name); }
14    move(distanceInMeters = 5) {
15        console.log("Slithering...");
16        super.move(distanceInMeters);
17    }
18}
19
20`;
21
22const ast = ast(typescript);
23const nodes = query(ast, 'Identifier[name="Animal"]');
24console.log(nodes.length); // 2

Selectors

The following selectors are supported:

• AST node type: ForStatement (see common node types)
• wildcard: *
• attribute existence: [attr]
• attribute value: [attr="foo"] or [attr=123]
• attribute regex: [attr=/foo.*/]
• attribute conditions: [attr!="foo"], [attr>2], [attr<3], [attr>=2], or [attr<=3]
• nested attribute: [attr.level2="foo"]
• field: FunctionDeclaration > Identifier.id
• First or last child: :first-child or :last-child
• nth-child (no ax+b support): :nth-child(2)
• nth-last-child (no ax+b support): :nth-last-child(1)
• descendant: ancestor descendant
• child: parent > child
• following sibling: node ~ sibling
• adjacent sibling: node + adjacent
• negation: :not(ForStatement)
• matches-any: :matches([attr] > :first-child, :last-child)
• has: IfStatement:has([name="foo"])
• class of AST node: :statement, :expression, :declaration, :function, or :pattern

Common AST node types

• Identifier - any identifier (name of a function, class, variable, etc)
• IfStatement, ForStatement, WhileStatement, DoStatement - control flow
• FunctionDeclaration, ClassDeclaration, ArrowFunction - declarations
• VariableStatement - var, const, let.
• ImportDeclaration - any import statement
• StringLiteral - any string
• TrueKeyword, FalseKeyword, NullKeyword, AnyKeyword - various keywords
• CallExpression - function call
• NumericLiteral - any numeric constant
• NoSubstitutionTemplateLiteral, TemplateExpression - template strings and expressions

API:

ast:

Parse a string of code into an Abstract Syntax Tree which can then be queried with TSQuery Selectors.

1import { ast } from '@phenomnomnominal/tsquery';
2
3const sourceFile = ast('const x = 1;');

includes:

Check for Nodes within a given string of code or AST Node matching a Selector.

1import { includes } from '@phenomnomnominal/tsquery';
2
3const hasIdentifier = includes('const x = 1;', 'Identifier');

map:

Transform AST Nodes within a given Node matching a Selector. Can be used to do Node-based replacement or removal of parts of the input AST.

1import { factory } from 'typescript';
2import { map } from '@phenomnomnominal/tsquery';
3
4const tree = ast('const x = 1;')
5const updatedTree = map(tree, 'Identifier', () => factory.createIdentifier('y'));

match:

Find AST Nodes within a given AST Node matching a Selector.

1import { ast, match } from '@phenomnomnominal/tsquery';
2
3const tree = ast('const x = 1;')
4const [xNode] = match(tree, 'Identifier');

parse:

Parse a string into an ESQuery Selector.

1import { parse } from '@phenomnomnominal/tsquery';
2
3const selector = parse(':matches([attr] > :first-child, :last-child)');

print:

Print a given Node or SourceFile to a string, using the default TypeScript printer.

1import { print } from '@phenomnomnominal/tsquery';
2import { factory } from 'typescript';
3
4  // create synthetic node:
5const node = factory.createArrowFunction(
6  // ...
7);
8const code = print(node);

project:

Get all the SourceFiles included in a the TypeScript project described by a given config file.

1import { project } from '@phenomnomnominal/tsquery';
2
3const files = project('./tsconfig.json');

files:

Get all the file paths included ina the TypeScript project described by a given config file.

1import { files } from '@phenomnomnominal/tsquery';
2
3const filePaths = files('./tsconfig.json');

match:

Find AST Nodes within a given string of code or AST Node matching a Selector.

1import {query } from '@phenomnomnominal/tsquery';
2
3const [xNode] = query('const x = 1;', 'Identifier');

replace:

Transform AST Nodes within a given Node matching a Selector. Can be used to do string-based replacement or removal of parts of the input AST. The updated code will be printed with the TypeScript Printer, so you may need to run your own formatter on any output code.

1import { replace } from '@phenomnomnominal/tsquery';
2
3const updatedCode = replace('const x = 1;', 'Identifier', () => 'y'));