![Introducing Dashboard Analytics](https://cdn.sanity.io/images/cgdhsj6q/production/af327c5bd94708db501516a75da6870aef894c64-2286x1522.png?w=400&fit=max&auto=format)
Product
Introducing Dashboard Analytics
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.
@typescript-eslint/typescript-estree
Advanced tools
A parser that converts TypeScript source code into an ESTree compatible form
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.
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);
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 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 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.
A parser that converts TypeScript source code into an ESTree-compatible form
You can find our Getting Started docs here
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:
yarn add -D @typescript-eslint/typescript-estree
parse(code, options)
Parses the given string of code with the options provided and returns an ESTree-compatible AST.
interface ParseOptions {
/**
* create a top-level comments array containing all comments
*/
comment?: boolean;
/**
* An array of modules to turn explicit debugging on for.
* - 'typescript-eslint' is the same as setting the env var `DEBUG=typescript-eslint:*`
* - 'eslint' is the same as setting the env var `DEBUG=eslint:*`
* - 'typescript' is the same as setting `extendedDiagnostics: true` in your tsconfig compilerOptions
*
* For convenience, also supports a boolean:
* - true === ['typescript-eslint']
* - false === []
*/
debugLevel?: boolean | ('typescript-eslint' | 'eslint' | 'typescript')[];
/**
* Cause the parser to error if it encounters an unknown AST node type (useful for testing).
* This case only usually occurs when TypeScript releases new features.
*/
errorOnUnknownASTType?: boolean;
/**
* Absolute (or relative to `cwd`) path to the file being parsed.
*/
filePath?: string;
/**
* Enable parsing of 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.
*
* For the exact behavior, see https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser#parseroptionsecmafeaturesjsx
*/
jsx?: boolean;
/**
* Controls whether the `loc` information to each node.
* The `loc` property is an object which contains the exact line/column the node starts/ends on.
* This is similar to the `range` property, except it is line/column relative.
*/
loc?: boolean;
/*
* 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?: Function | false;
/**
* Controls whether the `range` property is included on AST nodes.
* The `range` property is a [number, number] which indicates the start/end index of the node in the file contents.
* This is similar to the `loc` property, except this is the absolute index.
*/
range?: boolean;
/**
* Set to true to create a top-level array containing all tokens from the file.
*/
tokens?: boolean;
/*
* 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?: boolean;
}
const PARSE_DEFAULT_OPTIONS: ParseOptions = {
comment: false,
errorOnUnknownASTType: false,
filePath: 'estree.ts', // or 'estree.tsx', if you pass jsx: true
jsx: false,
loc: false,
loggerFn: undefined,
range: false,
tokens: false,
useJSXTextNode: false,
};
declare function parse(
code: string,
options: ParseOptions = PARSE_DEFAULT_OPTIONS,
): TSESTree.Program;
Example usage:
import { parse } from '@typescript-eslint/typescript-estree';
const code = `const hello: string = 'world';`;
const ast = parse(code, {
loc: true,
range: true,
});
parseAndGenerateServices(code, options)
Parses the given string of code with the options provided and returns an ESTree-compatible AST. Accepts additional options which can be used to generate type information along with the AST.
interface ParseAndGenerateServicesOptions extends ParseOptions {
/**
* Causes the parser to error if the TypeScript compiler returns any unexpected syntax/semantic errors.
*/
errorOnTypeScriptSyntacticAndSemanticIssues?: boolean;
/**
* ***EXPERIMENTAL FLAG*** - Use this at your own risk.
*
* Causes TS to use the source files for referenced projects instead of the compiled .d.ts files.
* This feature is not yet optimized, and is likely to cause OOMs for medium to large projects.
*
* This flag REQUIRES at least TS v3.9, otherwise it does nothing.
*
* See: https://github.com/typescript-eslint/typescript-eslint/issues/2094
*/
EXPERIMENTAL_useSourceOfProjectReferenceRedirect?: boolean;
/**
* When `project` is provided, this controls the non-standard file extensions which will be parsed.
* It accepts an array of file extensions, each preceded by a `.`.
*/
extraFileExtensions?: string[];
/**
* Absolute (or relative to `tsconfigRootDir`) path to the file being parsed.
* When `project` is provided, this is required, as it is used to fetch the file from the TypeScript compiler's cache.
*/
filePath?: string;
/**
* 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?: boolean;
/**
* Absolute (or relative to `tsconfigRootDir`) paths to the tsconfig(s).
* If this is provided, type information will be returned.
*/
project?: string | string[];
/**
* If you provide a glob (or globs) to the project option, you can use this option to ignore certain folders from
* being matched by the globs.
* This accepts an array of globs to ignore.
*
* By default, this is set to ["/node_modules/"]
*/
projectFolderIgnoreList?: string[];
/**
* The absolute path to the root directory for all provided `project`s.
*/
tsconfigRootDir?: string;
/**
***************************************************************************************
* IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. *
***************************************************************************************
*
* When passed with `project`, this allows the parser to create a catch-all, default program.
* This means that if the parser encounters a file not included in any of the provided `project`s,
* it will not error, but will instead parse the file and its dependencies in a new program.
*/
createDefaultProgram?: boolean;
}
interface ParserServices {
program: ts.Program;
esTreeNodeToTSNodeMap: WeakMap<TSESTree.Node, ts.Node | ts.Token>;
tsNodeToESTreeNodeMap: WeakMap<ts.Node | ts.Token, TSESTree.Node>;
hasFullTypeInformation: boolean;
}
interface ParseAndGenerateServicesResult<T extends TSESTreeOptions> {
ast: TSESTree.Program;
services: ParserServices;
}
const PARSE_AND_GENERATE_SERVICES_DEFAULT_OPTIONS: ParseOptions = {
...PARSE_DEFAULT_OPTIONS,
errorOnTypeScriptSyntacticAndSemanticIssues: false,
extraFileExtensions: [],
preserveNodeMaps: false, // or true, if you do not set this, but pass `project`
project: undefined,
projectFolderIgnoreList: ['/node_modules/'],
tsconfigRootDir: process.cwd(),
};
declare function parseAndGenerateServices(
code: string,
options: ParseOptions = PARSE_DEFAULT_OPTIONS,
): ParseAndGenerateServicesResult;
Example usage:
import { parseAndGenerateServices } from '@typescript-eslint/typescript-estree';
const code = `const hello: string = 'world';`;
const { ast, services } = parseAndGenerateServices(code, {
filePath: '/some/path/to/file/foo.ts',
loc: true,
project: './tsconfig.json',
range: true,
});
parseWithNodeMaps(code, options)
Parses the given string of code with the options provided and returns both the ESTree-compatible AST as well as the node maps.
This allows you to work with both ASTs without the overhead of types that may come with parseAndGenerateServices
.
interface ParseWithNodeMapsResult<T extends TSESTreeOptions> {
ast: TSESTree.Program;
esTreeNodeToTSNodeMap: ParserServices['esTreeNodeToTSNodeMap'];
tsNodeToESTreeNodeMap: ParserServices['tsNodeToESTreeNodeMap'];
}
declare function parseWithNodeMaps(
code: string,
options: ParseOptions = PARSE_DEFAULT_OPTIONS,
): ParseWithNodeMapsResult;
Example usage:
import { parseWithNodeMaps } from '@typescript-eslint/typescript-estree';
const code = `const hello: string = 'world';`;
const { ast, esTreeNodeToTSNodeMap, tsNodeToESTreeNodeMap } = parseWithNodeMaps(
code,
{
loc: true,
range: true,
},
);
TSESTree
, AST_NODE_TYPES
and AST_TOKEN_TYPES
Types for the AST produced by the parse functions.
TSESTree
is a namespace which contains object types representing all of the AST Nodes produced by the parser.AST_NODE_TYPES
is an enum which provides the values for every single AST node's type
property.AST_TOKEN_TYPES
is an enum which provides the values for every single AST token's type
property.See the Supported TypeScript Version section in the project root.
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.
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-estree
versionA 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.
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
.
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.
FAQs
A parser that converts TypeScript source code into an ESTree compatible form
The npm package @typescript-eslint/typescript-estree receives a total of 33,363,159 weekly downloads. As such, @typescript-eslint/typescript-estree popularity was classified as popular.
We found that @typescript-eslint/typescript-estree demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.
Security News
A new OpenSSF report uncovers critical gaps in secure software training, with 75% of new developers unfamiliar with secure practices, highlighting urgent educational needs.
Security News
The 2023 Python Developers Survey reveals key trends in packaging, web frameworks, and developer demographics, highlighting a shift toward innovative tools as the Python community diversifies and grows among less experienced developers.