# @phenomnomnominal/tsquery

> Query TypeScript ASTs with the esquery API!

Latest version **6.2.0** (published 2026-04-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install @phenomnomnominal/tsquery
pnpm add @phenomnomnominal/tsquery
yarn add @phenomnomnominal/tsquery
bun add @phenomnomnominal/tsquery
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 6.2.0 |
| Published | 2026-04-06 |
| First published | 2018-04-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 82.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1054 |
| Author | Craig Spence |
| Maintainers | phenomnomnominal |

## Links

- npm: https://www.npmjs.com/package/@phenomnomnominal/tsquery
- Repository: https://github.com/phenomnomnominal/tsquery
- Homepage: https://github.com/phenomnomnominal/tsquery#readme
- Issues: https://github.com/phenomnomnominal/tsquery/issues
- npm.io page: https://npm.io/package/@phenomnomnominal/tsquery

## Dependencies (2)

- [esquery](https://npm.io/package/esquery.md) ^1.7.0
- [@types/esquery](https://npm.io/package/@types/esquery.md) ^1.5.4

## Recent versions

- 6.2.0 (latest) — 2026-04-06
- 6.1.4 — 2025-12-04
- 6.1.3 — 2023-08-22
- 6.1.2 — 2023-07-12
- 6.1.1 — 2023-07-11
- 6.1.0 — 2023-07-11
- 6.0.2 — 2023-07-10
- 6.0.1 — 2023-07-10
- 6.0.0 — 2023-07-10
- 5.0.1 — 2023-03-18
- 5.0.0 — 2022-04-22
- 4.2.0 — 2022-01-19
- 4.1.1 — 2020-09-01
- 4.1.0 — 2020-05-14
- 4.0.0 — 2019-10-16
- … 26 more at https://npm.io/package/@phenomnomnominal/tsquery/versions

## README

# TSQuery

[![npm version](https://img.shields.io/npm/v/@phenomnomnominal/tsquery.svg)](https://img.shields.io/npm/v/@phenomnomnominal/tsquery.svg)

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](https://estools.github.io/esquery/) - note that the demo requires JavaScript code, not TypeScript
[TSQuery demo](https://tsquery-playground.firebaseapp.com) by [Uri Shaked](https://github.com/urish)

## Installation

```sh
npm 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:

```ts
import { ast, query } 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 tree = ast(typescript);
const nodes = query(tree, 'Identifier[name="Animal"]');
console.log(nodes.length); // 2
```

### Selectors

The following selectors are supported:

* AST node type: `ForStatement` (see [common node types](#common-ast-node-types))
* [wildcard](http://dev.w3.org/csswg/selectors4/#universal-selector): `*`
* [attribute existence](http://dev.w3.org/csswg/selectors4/#attribute-selectors): `[attr]`
* [attribute value](http://dev.w3.org/csswg/selectors4/#attribute-selectors): `[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](http://dev.w3.org/csswg/selectors4/#the-first-child-pseudo) or [last](http://dev.w3.org/csswg/selectors4/#the-last-child-pseudo) child: `:first-child` or `:last-child`
* [nth-child](http://dev.w3.org/csswg/selectors4/#the-nth-child-pseudo) (no ax+b support): `:nth-child(2)`
* [nth-last-child](http://dev.w3.org/csswg/selectors4/#the-nth-last-child-pseudo) (no ax+b support): `:nth-last-child(1)`
* [descendant](http://dev.w3.org/csswg/selectors4/#descendant-combinators): `ancestor descendant`
* [child](http://dev.w3.org/csswg/selectors4/#child-combinators): `parent > child`
* [following sibling](http://dev.w3.org/csswg/selectors4/#general-sibling-combinators): `node ~ sibling`
* [adjacent sibling](http://dev.w3.org/csswg/selectors4/#adjacent-sibling-combinators): `node + adjacent`
* [negation](http://dev.w3.org/csswg/selectors4/#negation-pseudo): `:not(ForStatement)`
* [matches-any](http://dev.w3.org/csswg/selectors4/#matches): `:matches([attr] > :first-child, :last-child)`
* [has](https://drafts.csswg.org/selectors-4/#has-pseudo): `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.

```typescript
import { ast } from '@phenomnomnominal/tsquery';

const sourceFile = ast('const x = 1;');
```

### `includes`:

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

```typescript
import { includes } from '@phenomnomnominal/tsquery';

const 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.

```typescript
import { factory } from 'typescript';
import { map } from '@phenomnomnominal/tsquery';

const tree = ast('const x = 1;')
const updatedTree = map(tree, 'Identifier', () => factory.createIdentifier('y'));
```

### `match`:

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

```typescript
import { ast, match } from '@phenomnomnominal/tsquery';

const tree = ast('const x = 1;')
const [xNode] = match(tree, 'Identifier');
```

### `parse`:

Parse a `string` into an [ESQuery](https://github.com/estools/esquery) `Selector`.

```typescript
import { parse } from '@phenomnomnominal/tsquery';

const selector = parse(':matches([attr] > :first-child, :last-child)');
```

### `print`:

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

```typescript
import { print } from '@phenomnomnominal/tsquery';
import { factory } from 'typescript';

  // create synthetic node:
const node = factory.createArrowFunction(
  // ...
);
const code = print(node);
```

### `project`:

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

```typescript
import { project } from '@phenomnomnominal/tsquery';

const files = project('./tsconfig.json');
```

### `files`:

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

```typescript
import { files } from '@phenomnomnominal/tsquery';

const filePaths = files('./tsconfig.json');
```

### `match`:

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

```typescript
import {query } from '@phenomnomnominal/tsquery';

const [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`](https://github.com/microsoft/TypeScript-wiki/blob/main/Using-the-Compiler-API.md#creating-and-printing-a-typescript-ast), so you may need to run your own formatter on any output code.

```typescript
import { replace } from '@phenomnomnominal/tsquery';

const updatedCode = replace('const x = 1;', 'Identifier', () => 'y'));
```

---
_Source: https://npm.io/package/@phenomnomnominal/tsquery · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._