@typescript-eslint/typescript-estree

What is @typescript-eslint/typescript-estree?

The @typescript-eslint/typescript-estree package is a parser that converts TypeScript source code into an ESTree-compatible form. It is primarily used in the context of ESLint to enable linting of TypeScript code by converting TypeScript syntax into a format that ESLint can understand and work with.

What are @typescript-eslint/typescript-estree's main functionalities?

Parsing TypeScript code to ESTree

This feature allows you to parse TypeScript code and get an Abstract Syntax Tree (AST) that is compatible with ESTree. This is useful for tools that need to analyze or manipulate the syntax of TypeScript code.

const tsEStree = require('@typescript-eslint/typescript-estree');
const code = 'let x: number = 1;';
const ast = tsEStree.parse(code, { jsx: false });
console.log(ast);

Parsing TypeScript code with JSX

This feature is similar to the previous one but includes support for JSX syntax, which is commonly used in React applications. It allows the parser to correctly interpret JSX elements within TypeScript code.

const tsEStree = require('@typescript-eslint/typescript-estree');
const code = '<div>Hello, TypeScript!</div>';
const ast = tsEStree.parse(code, { jsx: true });
console.log(ast);

Parsing a file

This feature allows you to parse the contents of a TypeScript file by reading the file and then parsing the code. It is useful when you want to analyze or lint a file directly.

const tsEStree = require('@typescript-eslint/typescript-estree');
const fs = require('fs');
const filePath = './example.ts';
const code = fs.readFileSync(filePath, 'utf8');
const ast = tsEStree.parse(code, { filePath });
console.log(ast);

Other packages similar to @typescript-eslint/typescript-estree

typescript-eslint-parser

This package was the predecessor to @typescript-eslint/typescript-estree and has been deprecated in favor of the newer package. It provided similar functionality in terms of parsing TypeScript code for ESLint.

babel-eslint

babel-eslint is a parser that allows ESLint to run on source code that is transpiled with Babel. While it is not TypeScript-specific, it can be used with Babel's TypeScript preset to parse TypeScript code.

espree

Espree is the default parser for ESLint and is built on top of Acorn. It is designed to parse ECMAScript (JavaScript) code. While it does not natively support TypeScript, it serves a similar purpose for JavaScript code as @typescript-eslint/typescript-estree does for TypeScript.

README

TypeScript ESTree

A parser that converts TypeScript source code into an ESTree-compatible form

About

This parser is somewhat generic and robust, and could be used to power any use-case which requires taking TypeScript source code and producing an ESTree-compatible AST.

In fact, it is already used within these hyper-popular open-source projects to power their TypeScript support:

• ESLint, the pluggable linting utility for JavaScript and JSX
• Prettier, an opinionated code formatter

Installation

yarn add -D @typescript-eslint/typescript-estree

API

parse(code, options)

Parses the given string of code with the options provided and returns an ESTree-compatible AST. The options object has the following properties:

{
  // attach range information to each node
  range: false,

  // attach line/column location information to each node
  loc: false,

  // create a top-level tokens array containing all tokens
  tokens: false,

  // create a top-level comments array containing all comments
  comment: false,

  /*
   * enable parsing JSX. For more details, see https://www.typescriptlang.org/docs/handbook/jsx.html
   *
   * NOTE: this setting does not effect known file types (.js, .jsx, .ts, .tsx, .json) because the
   * TypeScript compiler has its own internal handling for known file extensions.
   *
   * Exact behaviour:
   * - .js, .jsx, .tsx files are parsed as if this is true
   * - .ts files are parsed as if this is false
   * - unknown extensions (.md, .vue) will respect this setting
   */
  jsx: false,

  /*
   * The JSX AST changed the node type for string literals
   * inside a JSX Element from `Literal` to `JSXText`.
   * When value is `true`, these nodes will be parsed as type `JSXText`.
   * When value is `false`, these nodes will be parsed as type `Literal`.
   */
  useJSXTextNode: false,

  // Cause the parser to error if it encounters an unknown AST node type (useful for testing)
  errorOnUnknownASTType: false,

  /*
   * Allows overriding of function used for logging.
   * When value is `false`, no logging will occur.
   * When value is not provided, `console.log()` will be used.
   */
  loggerFn: undefined,

  /**
   * Allows the user to control whether or not two-way AST node maps are preserved
   * during the AST conversion process.
   *
   * By default: the AST node maps are NOT preserved, unless `project` has been specified,
   * in which case the maps are made available on the returned `parserServices`.
   *
   * NOTE: If `preserveNodeMaps` is explicitly set by the user, it will be respected,
   * regardless of whether or not `project` is in use.
   */
  preserveNodeMaps: undefined
}

Example usage:

const parser = require('@typescript-eslint/typescript-estree');
const code = `const hello: string = 'world';`;
const ast = parser.parse(code, {
  range: true,
  loc: true,
});

version

Exposes the current version of typescript-estree as specified in package.json.

Example usage:

const parser = require('@typescript-eslint/typescript-estree');
const version = parser.version;

AST_NODE_TYPES

Exposes an object that contains the AST node types produced by the parser.

Example usage:

const parser = require('@typescript-eslint/typescript-estree');
const astNodeTypes = parser.AST_NODE_TYPES;

Supported TypeScript Version

We will always endeavor to support the latest stable version of TypeScript.

The version of TypeScript currently supported by this parser is ~3.2.1. This is reflected in the devDependency requirement within the package.json file, and it is what the tests will be run against. We have an open peerDependency requirement in order to allow for experimentation on newer/beta versions of TypeScript.

If you use a non-supported version of TypeScript, the parser will log a warning to the console.

Please ensure that you are using a supported version before submitting any issues/bug reports.

Reporting Issues

Please check the current list of open and known issues and ensure the issue has not been reported before. When creating a new issue provide as much information about your environment as possible. This includes:

• TypeScript version
• The typescript-estree version

AST Alignment Tests

A couple of years after work on this parser began, the TypeScript Team at Microsoft began officially supporting TypeScript parsing via Babel.

I work closely with the TypeScript Team and we are gradually aligning the AST of this project with the one produced by Babel's parser. To that end, I have created a full test harness to compare the ASTs of the two projects which runs on every PR, please see the code for more details.

Build/Test Commands

• npm test - run all tests
• npm run unit-tests - run only unit tests
• npm run ast-alignment-tests - run only Babylon AST alignment tests

Debugging

If you encounter a bug with the parser that you want to investigate, you can turn on the debug logging via setting the environment variable: DEBUG=typescript-eslint:*. I.e. in this repo you can run: DEBUG=typescript-eslint:* yarn lint.

License

TypeScript ESTree inherits from the the original TypeScript ESLint Parser license, as the majority of the work began there. It is licensed under a permissive BSD 2-clause license.

Contributing

See the contributing guide here