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.

Check out the ESQuery demo - note that the demo requires JavaScript code, not TypeScript

You can also check out the TSQuery Playground - Lovingly crafted by Uri Shaked

Installation

npm install @phenomnomnominal/tsquery --save-dev

Upgrading from version 4.x.x to 5.x.x

Update all your calls to tsquery.map() to make sure they match the new contract. For more information, check phenomnomnominal#76.

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:

import { tsquery } from '@phenomnomnominal/tsquery';

const typescript = `

class Animal {
    constructor(public name: string) { }
    move(distanceInMeters: number = 0) {
        console.log(\`\${this.name} moved \${distanceInMeters}m.\`);
    }
}

class Snake extends Animal {
    constructor(name: string) { super(name); }
    move(distanceInMeters = 5) {
        console.log("Slithering...");
        super.move(distanceInMeters);
    }
}

`;

const ast = tsquery.ast(typescript);
const nodes = tsquery(ast, 'Identifier[name="Animal"]');
console.log(nodes.length); // 2

Try running this code in StackBlitz!

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 conditons: [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

skvale / tsquery