.config/coc/extensions/node_modules/coc-prettier/node_modules/@typescript-eslint/typescript-estree/README.md

   1 <h1 align="center">TypeScript ESTree</h1>
   2
   3 <p align="center">A parser that converts TypeScript source code into an <a href="https://github.com/estree/estree">ESTree</a>-compatible form</p>
   4
   5 <p align="center">
   6     <img src="https://github.com/typescript-eslint/typescript-eslint/workflows/CI/badge.svg" alt="CI" />
   7     <a href="https://www.npmjs.com/package/@typescript-eslint/typescript-estree"><img src="https://img.shields.io/npm/v/@typescript-eslint/typescript-estree.svg?style=flat-square" alt="NPM Version" /></a>
   8     <a href="https://www.npmjs.com/package/@typescript-eslint/typescript-estree"><img src="https://img.shields.io/npm/dm/@typescript-eslint/typescript-estree.svg?style=flat-square" alt="NPM Downloads" /></a>
   9 </p>
  10
  11 ## Getting Started
  12
  13 **[You can find our Getting Started docs here](../../docs/getting-started/linting/README.md)**
  14
  15 ## About
  16
  17 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.
  18
  19 In fact, it is already used within these hyper-popular open-source projects to power their TypeScript support:
  20
  21 - [ESLint](https://eslint.org), the pluggable linting utility for JavaScript and JSX
  22 - [Prettier](https://prettier.io), an opinionated code formatter
  23
  24 ## Installation
  25
  26 ```sh
  27 yarn add -D @typescript-eslint/typescript-estree
  28 ```
  29
  30 ## API
  31
  32 ### Parsing
  33
  34 #### `parse(code, options)`
  35
  36 Parses the given string of code with the options provided and returns an ESTree-compatible AST.
  37
  38 ```ts
  39 interface ParseOptions {
  40   /**
  41    * create a top-level comments array containing all comments
  42    */
  43   comment?: boolean;
  44
  45   /**
  46    * An array of modules to turn explicit debugging on for.
  47    * - 'typescript-eslint' is the same as setting the env var `DEBUG=typescript-eslint:*`
  48    * - 'eslint' is the same as setting the env var `DEBUG=eslint:*`
  49    * - 'typescript' is the same as setting `extendedDiagnostics: true` in your tsconfig compilerOptions
  50    *
  51    * For convenience, also supports a boolean:
  52    * - true === ['typescript-eslint']
  53    * - false === []
  54    */
  55   debugLevel?: boolean | ('typescript-eslint' | 'eslint' | 'typescript')[];
  56
  57   /**
  58    * Cause the parser to error if it encounters an unknown AST node type (useful for testing).
  59    * This case only usually occurs when TypeScript releases new features.
  60    */
  61   errorOnUnknownASTType?: boolean;
  62
  63   /**
  64    * Absolute (or relative to `cwd`) path to the file being parsed.
  65    */
  66   filePath?: string;
  67
  68   /**
  69    * Enable parsing of JSX.
  70    * For more details, see https://www.typescriptlang.org/docs/handbook/jsx.html
  71    *
  72    * NOTE: this setting does not effect known file types (.js, .jsx, .ts, .tsx, .json) because the
  73    * TypeScript compiler has its own internal handling for known file extensions.
  74    *
  75    * For the exact behavior, see https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser#parseroptionsecmafeaturesjsx
  76    */
  77   jsx?: boolean;
  78
  79   /**
  80    * Controls whether the `loc` information to each node.
  81    * The `loc` property is an object which contains the exact line/column the node starts/ends on.
  82    * This is similar to the `range` property, except it is line/column relative.
  83    */
  84   loc?: boolean;
  85
  86   /*
  87    * Allows overriding of function used for logging.
  88    * When value is `false`, no logging will occur.
  89    * When value is not provided, `console.log()` will be used.
  90    */
  91   loggerFn?: Function | false;
  92
  93   /**
  94    * Controls whether the `range` property is included on AST nodes.
  95    * The `range` property is a [number, number] which indicates the start/end index of the node in the file contents.
  96    * This is similar to the `loc` property, except this is the absolute index.
  97    */
  98   range?: boolean;
  99
 100   /**
 101    * Set to true to create a top-level array containing all tokens from the file.
 102    */
 103   tokens?: boolean;
 104
 105   /*
 106    * The JSX AST changed the node type for string literals
 107    * inside a JSX Element from `Literal` to `JSXText`.
 108    * When value is `true`, these nodes will be parsed as type `JSXText`.
 109    * When value is `false`, these nodes will be parsed as type `Literal`.
 110    */
 111   useJSXTextNode?: boolean;
 112 }
 113
 114 const PARSE_DEFAULT_OPTIONS: ParseOptions = {
 115   comment: false,
 116   errorOnUnknownASTType: false,
 117   filePath: 'estree.ts', // or 'estree.tsx', if you pass jsx: true
 118   jsx: false,
 119   loc: false,
 120   loggerFn: undefined,
 121   range: false,
 122   tokens: false,
 123   useJSXTextNode: false,
 124 };
 125
 126 declare function parse(
 127   code: string,
 128   options: ParseOptions = PARSE_DEFAULT_OPTIONS,
 129 ): TSESTree.Program;
 130 ```
 131
 132 Example usage:
 133
 134 ```js
 135 import { parse } from '@typescript-eslint/typescript-estree';
 136
 137 const code = `const hello: string = 'world';`;
 138 const ast = parse(code, {
 139   loc: true,
 140   range: true,
 141 });
 142 ```
 143
 144 #### `parseAndGenerateServices(code, options)`
 145
 146 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.
 147
 148 ```ts
 149 interface ParseAndGenerateServicesOptions extends ParseOptions {
 150   /**
 151    * Causes the parser to error if the TypeScript compiler returns any unexpected syntax/semantic errors.
 152    */
 153   errorOnTypeScriptSyntacticAndSemanticIssues?: boolean;
 154
 155   /**
 156    * When `project` is provided, this controls the non-standard file extensions which will be parsed.
 157    * It accepts an array of file extensions, each preceded by a `.`.
 158    */
 159   extraFileExtensions?: string[];
 160
 161   /**
 162    * Absolute (or relative to `tsconfigRootDir`) path to the file being parsed.
 163    * When `project` is provided, this is required, as it is used to fetch the file from the TypeScript compiler's cache.
 164    */
 165   filePath?: string;
 166
 167   /**
 168    * Allows the user to control whether or not two-way AST node maps are preserved
 169    * during the AST conversion process.
 170    *
 171    * By default: the AST node maps are NOT preserved, unless `project` has been specified,
 172    * in which case the maps are made available on the returned `parserServices`.
 173    *
 174    * NOTE: If `preserveNodeMaps` is explicitly set by the user, it will be respected,
 175    * regardless of whether or not `project` is in use.
 176    */
 177   preserveNodeMaps?: boolean;
 178
 179   /**
 180    * Absolute (or relative to `tsconfigRootDir`) paths to the tsconfig(s).
 181    * If this is provided, type information will be returned.
 182    */
 183   project?: string | string[];
 184
 185   /**
 186    * If you provide a glob (or globs) to the project option, you can use this option to blacklist
 187    * certain folders from being matched by the globs.
 188    * Any project path that matches one or more of the provided regular expressions will be removed from the list.
 189    *
 190    * Accepts an array of strings that are passed to new RegExp(), or an array of regular expressions.
 191    * By default, this is set to ["/node_modules/"]
 192    */
 193   projectFolderIgnoreList?: (string | RegExp)[];
 194
 195   /**
 196    * The absolute path to the root directory for all provided `project`s.
 197    */
 198   tsconfigRootDir?: string;
 199
 200   /**
 201    ***************************************************************************************
 202    * IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. *
 203    ***************************************************************************************
 204    *
 205    * When passed with `project`, this allows the parser to create a catch-all, default program.
 206    * This means that if the parser encounters a file not included in any of the provided `project`s,
 207    * it will not error, but will instead parse the file and its dependencies in a new program.
 208    */
 209   createDefaultProgram?: boolean;
 210 }
 211
 212 const PARSE_AND_GENERATE_SERVICES_DEFAULT_OPTIONS: ParseOptions = {
 213   ...PARSE_DEFAULT_OPTIONS,
 214   errorOnTypeScriptSyntacticAndSemanticIssues: false,
 215   extraFileExtensions: [],
 216   preserveNodeMaps: false, // or true, if you do not set this, but pass `project`
 217   project: undefined,
 218   projectFolderIgnoreList: ['/node_modules/'],
 219   tsconfigRootDir: process.cwd(),
 220 };
 221
 222 declare function parseAndGenerateServices(
 223   code: string,
 224   options: ParseOptions = PARSE_DEFAULT_OPTIONS,
 225 ): TSESTree.Program;
 226 ```
 227
 228 Example usage:
 229
 230 ```js
 231 import { parseAndGenerateServices } from '@typescript-eslint/typescript-estree';
 232
 233 const code = `const hello: string = 'world';`;
 234 const ast = parseAndGenerateServices(code, {
 235   filePath: '/some/path/to/file/foo.ts',
 236   loc: true,
 237   project: './tsconfig.json',
 238   range: true,
 239 });
 240 ```
 241
 242 ### `TSESTree`, `AST_NODE_TYPES` and `AST_TOKEN_TYPES`
 243
 244 Types for the AST produced by the parse functions.
 245
 246 - `TSESTree` is a namespace which contains object types representing all of the AST Nodes produced by the parser.
 247 - `AST_NODE_TYPES` is an enum which provides the values for every single AST node's `type` property.
 248 - `AST_TOKEN_TYPES` is an enum which provides the values for every single AST token's `type` property.
 249
 250 ## Supported TypeScript Version
 251
 252 See the [Supported TypeScript Version](../../README.md#supported-typescript-version) section in the project root.
 253
 254 If you use a non-supported version of TypeScript, the parser will log a warning to the console.
 255
 256 **Please ensure that you are using a supported version before submitting any issues/bug reports.**
 257
 258 ## Reporting Issues
 259
 260 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:
 261
 262 - TypeScript version
 263 - The `typescript-estree` version
 264
 265 ## AST Alignment Tests
 266
 267 A couple of years after work on this parser began, the TypeScript Team at Microsoft began [officially supporting TypeScript parsing via Babel](https://blogs.msdn.microsoft.com/typescript/2018/08/27/typescript-and-babel-7/).
 268
 269 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.
 270
 271 ## Build/Test Commands
 272
 273 - `npm test` - run all tests
 274 - `npm run unit-tests` - run only unit tests
 275 - `npm run ast-alignment-tests` - run only Babylon AST alignment tests
 276
 277 ## Debugging
 278
 279 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:*`.
 280 I.e. in this repo you can run: `DEBUG=typescript-eslint:* yarn lint`.
 281
 282 ## License
 283
 284 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.
 285
 286 ## Contributing
 287
 288 [See the contributing guide here](../../CONTRIBUTING.md)