Skip to main content

@typescript-eslint/typescript-estree

The underlying code used by @typescript-eslint/parser that converts TypeScript source code into an ESTree-compatible form. ✨

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

It is most known for use 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

It works by:

  1. Invoking the TypeScript compiler on the given source code in order to produce a TypeScript AST
  2. Converting that TypeScript AST into an ESTree AST

API

Parsing

parse(code, options)

Parses the given string of code with the options provided and returns an ESTree-compatible AST.

interface ParseOptions {
/**
* Prevents the parser from throwing an error if it receives an invalid AST from TypeScript.
* This case only usually occurs when attempting to lint invalid code.
*/
allowInvalidAST?: boolean;

/**
* create a top-level comments array containing all comments
*/
comment?: boolean;

/**
* Whether deprecated AST properties should skip calling console.warn on accesses.
*/
suppressDeprecatedPropertyWarnings?: 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;

/**
* If you are using TypeScript version >=5.3 then this option can be used as a performance optimization.
*
* The valid values for this rule are:
* - `'all'` - parse all JSDoc comments, always.
* - `'none'` - parse no JSDoc comments, ever.
* - `'type-info'` - parse just JSDoc comments that are required to provide correct type-info. TS will always parse JSDoc in non-TS files, but never in TS files.
*
* If you do not rely on JSDoc tags from the TypeScript AST, then you can safely set this to `'none'` to improve performance.
*/
jsDocParsingMode?: JSDocParsingMode;

/**
* 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, .cjs, .mjs, .jsx, .ts, .mts, .cts, .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/main/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;
}

const PARSE_DEFAULT_OPTIONS: ParseOptions = {
comment: false,
filePath: 'estree.ts', // or 'estree.tsx', if you pass jsx: true
jsDocParsingMode: 'all',
jsx: false,
loc: false,
loggerFn: undefined,
range: false,
tokens: 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.
*
* Whether to create a shared TypeScript server to power program creation.
*
* @see https://github.com/typescript-eslint/typescript-eslint/issues/6575
*/
EXPERIMENTAL_useProjectService?: boolean | ProjectServiceOptions;

/**
* ***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),
* or `true` to find the nearest tsconfig.json to the file.
* If this is provided, type information will be returned.
*
* If set to `false`, `null`, or `undefined`, type information will not be returned.
*/
project?: string[] | string | boolean | null;

/**
* 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;

/**
* An array of one or more instances of TypeScript Program objects to be used for type information.
* This overrides any program or programs that would have been computed from the `project` option.
* All linted files must be part of the provided program(s).
*/
programs?: Program[];

/**
* @deprecated - this flag will be removed in the next major.
* Do not rely on the behavior provided by this flag.
*/
DEPRECATED__createDefaultProgram?: boolean;

/**
* ESLint (and therefore typescript-eslint) is used in both "single run"/one-time contexts,
* such as an ESLint CLI invocation, and long-running sessions (such as continuous feedback
* on a file in an IDE).
*
* When typescript-eslint handles TypeScript Program management behind the scenes, this distinction
* is important because there is significant overhead to managing the so called Watch Programs
* needed for the long-running use-case.
*
* When allowAutomaticSingleRunInference is enabled, we will use common heuristics to infer
* whether or not ESLint is being used as part of a single run.
*
* This setting's default value can be specified by setting a `TSESTREE_SINGLE_RUN`
* environment variable to `"false"` or `"true"`.
*/
allowAutomaticSingleRunInference?: boolean;

/**
* Granular control of the expiry lifetime of our internal caches.
* You can specify the number of seconds as an integer number, or the string
* 'Infinity' if you never want the cache to expire.
*
* By default cache entries will be evicted after 30 seconds, or will persist
* indefinitely if `allowAutomaticSingleRunInference = true` AND the parser
* infers that it is a single run.
*/
cacheLifetime?: {
/**
* Glob resolution for `parserOptions.project` values.
*/
glob?: number | 'Infinity';
};
}

/**
* Granular options to configure the project service.
*/
interface ProjectServiceOptions {
/**
* Globs of files to allow running with the default project compiler options.
*/
allowDefaultProjectForFiles?: string[];

/**
* Path to a TSConfig to use instead of TypeScript's default project configuration.
*/
defaultProject?: string;

/**
* The maximum number of files {@link allowDefaultProjectForFiles} may match.
* Each file match slows down linting, so if you do need to use this, please
* file an informative issue on typescript-eslint explaining why - so we can
* help you avoid using it!
* @default 8
*/
maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING?: number;
}

interface ParserServices {
program: ts.Program;
esTreeNodeToTSNodeMap: WeakMap<TSESTree.Node, ts.Node | ts.Token>;
tsNodeToESTreeNodeMap: WeakMap<ts.Node | ts.Token, TSESTree.Node>;
}

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,
});

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.

Utilities

createProgram(configFile, projectDirectory)

This serves as a utility method for users of the ParseOptions.programs feature to create a TypeScript program instance from a config file.

declare function createProgram(
configFile: string,
projectDirectory: string = process.cwd(),
): import('typescript').Program;

Example usage:

const tsESTree = require('@typescript-eslint/typescript-estree');

const program = tsESTree.createProgram('tsconfig.json');
const code = `const hello: string = 'world';`;
const { ast, services } = parseAndGenerateServices(code, {
filePath: '/some/path/to/file/foo.ts',
loc: true,
program,
range: true,
});

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.