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

   1 <h1 align="center">TypeScript ESLint Parser</h1>
   2
   3 <p align="center">An ESLint parser which leverages <a href="https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/typescript-estree">TypeScript ESTree</a> to allow for ESLint to lint TypeScript source code.</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/parser"><img src="https://img.shields.io/npm/v/@typescript-eslint/parser.svg?style=flat-square" alt="NPM Version" /></a>
   8     <a href="https://www.npmjs.com/package/@typescript-eslint/parser"><img src="https://img.shields.io/npm/dm/@typescript-eslint/parser.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 These docs walk you through setting up ESLint, this parser, and our plugin. If you know what you're doing and just want to quick start, read on...
  16
  17 ## Quick-start
  18
  19 ### Installation
  20
  21 ```bash
  22 $ yarn add -D typescript @typescript-eslint/parser
  23 $ npm i --save-dev typescript @typescript-eslint/parser
  24 ```
  25
  26 ### Usage
  27
  28 In your ESLint configuration file, set the `parser` property:
  29
  30 ```json
  31 {
  32   "parser": "@typescript-eslint/parser"
  33 }
  34 ```
  35
  36 There is sometimes an incorrect assumption that the parser itself is what does everything necessary to facilitate the use of ESLint with TypeScript. In actuality, it is the combination of the parser _and_ one or more plugins which allow you to maximize your usage of ESLint with TypeScript.
  37
  38 For example, once this parser successfully produces an AST for the TypeScript source code, it might well contain some information which simply does not exist in a standard JavaScript context, such as the data for a TypeScript-specific construct, like an `interface`.
  39
  40 The core rules built into ESLint, such as `indent` have no knowledge of such constructs, so it is impossible to expect them to work out of the box with them.
  41
  42 Instead, you also need to make use of one more plugins which will add or extend rules with TypeScript-specific features.
  43
  44 By far the most common case will be installing the [`@typescript-eslint/eslint-plugin`](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin) plugin, but there are also other relevant options available such a [`@typescript-eslint/eslint-plugin-tslint`](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin-tslint).
  45
  46 ## Configuration
  47
  48 The following additional configuration options are available by specifying them in [`parserOptions`](https://eslint.org/docs/user-guide/configuring#specifying-parser-options) in your ESLint configuration file.
  49
  50 ```ts
  51 interface ParserOptions {
  52   ecmaFeatures?: {
  53     jsx?: boolean;
  54   };
  55   project?: string | string[];
  56   projectFolderIgnoreList?: (string | RegExp)[];
  57   tsconfigRootDir?: string;
  58   extraFileExtensions?: string[];
  59   warnOnUnsupportedTypeScriptVersion?: boolean;
  60 }
  61 ```
  62
  63 ### `parserOptions.ecmaFeatures.jsx`
  64
  65 Default `false`.
  66
  67 Enable parsing JSX when `true`. More details can be found [here](https://www.typescriptlang.org/docs/handbook/jsx.html).
  68
  69 **NOTE:** this setting does not affect known file types (`.js`, `.jsx`, `.ts`, `.tsx`, `.json`) because the TypeScript compiler has its own internal handling for known file extensions. The exact behavior is as follows:
  70
  71 - if `parserOptions.project` is _not_ provided:
  72   - `.js`, `.jsx`, `.tsx` files are parsed as if this is true.
  73   - `.ts` files are parsed as if this is false.
  74   - unknown extensions (`.md`, `.vue`) will respect this setting.
  75 - if `parserOptions.project` is provided (i.e. you are using rules with type information):
  76   - `.js`, `.jsx`, `.tsx` files are parsed as if this is true.
  77   - `.ts` files are parsed as if this is false.
  78   - "unknown" extensions (`.md`, `.vue`) **are parsed as if this is false**.
  79
  80 ### `parserOptions.project`
  81
  82 Default `undefined`.
  83
  84 This option allows you to provide a path to your project's `tsconfig.json`. **This setting is required if you want to use rules which require type information**. Relative paths are interpreted relative to the current working directory if `tsconfigRootDir` is not set. If you intend on running ESLint from directories other than the project root, you should consider using `tsconfigRootDir`.
  85
  86 - Accepted values:
  87
  88   ```js
  89   // path
  90   project: './tsconfig.json';
  91
  92   // glob pattern
  93   project: './packages/**/tsconfig.json';
  94
  95   // array of paths and/or glob patterns
  96   project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json'];
  97   ```
  98
  99 - If you use project references, TypeScript will not automatically use project references to resolve files. This means that you will have to add each referenced tsconfig to the `project` field either separately, or via a glob.
 100
 101 - TypeScript will ignore files with duplicate filenames in the same folder (for example, `src/file.ts` and `src/file.js`). TypeScript purposely ignore all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is `.ts`, `.tsx`, `.d.ts`, `.js`, `.jsx`). For more info see #955.
 102
 103 - Note that if this setting is specified and `createDefaultProgram` is not, you must only lint files that are included in the projects as defined by the provided `tsconfig.json` files. If your existing configuration does not include all of the files you would like to lint, you can create a separate `tsconfig.eslint.json` as follows:
 104
 105   ```jsonc
 106   {
 107     // extend your base config so you don't have to redefine your compilerOptions
 108     "extends": "./tsconfig.json",
 109     "include": [
 110       "src/**/*.ts",
 111       "test/**/*.ts",
 112       "typings/**/*.ts",
 113       // etc
 114
 115       // if you have a mixed JS/TS codebase, don't forget to include your JS files
 116       "src/**/*.js"
 117     ]
 118   }
 119   ```
 120
 121 ### `parserOptions.tsconfigRootDir`
 122
 123 Default `undefined`.
 124
 125 This option allows you to provide the root directory for relative tsconfig paths specified in the `project` option above.
 126
 127 ### `parserOptions.projectFolderIgnoreList`
 128
 129 Default `["/node_modules/"]`.
 130
 131 This option allows you to ignore folders from being included in your provided list of `project`s.
 132 Any resolved project path that matches one or more of the provided regular expressions will be removed from the list.
 133 This is useful if you have configured glob patterns, but want to make sure you ignore certain folders.
 134
 135 For example, by default it will ensure that a glob like `./**/tsconfig.json` will not match any `tsconfig`s within your `node_modules` folder (some npm packages do not exclude their source files from their published packages).
 136
 137 ### `parserOptions.extraFileExtensions`
 138
 139 Default `undefined`.
 140
 141 This option allows you to provide one or more additional file extensions which should be considered in the TypeScript Program compilation.
 142 The default extensions are `.ts`, `.tsx`, `.js`, and `.jsx`. Add extensions starting with `.`, followed by the file extension. E.g. for a `.vue` file use `"extraFileExtensions: [".vue"]`.
 143
 144 ### `parserOptions.warnOnUnsupportedTypeScriptVersion`
 145
 146 Default `true`.
 147
 148 This option allows you to toggle the warning that the parser will give you if you use a version of TypeScript which is not explicitly supported
 149
 150 ### `parserOptions.createDefaultProgram`
 151
 152 Default `false`.
 153
 154 This option allows you to request that when the `project` setting is specified, files will be allowed when not included in the projects defined by the provided `tsconfig.json` files. **Using this option will incur significant performance costs. This option is primarily included for backwards-compatibility.** See the **`project`** section above for more information.
 155
 156 ## Supported TypeScript Version
 157
 158 Please see [`typescript-eslint`](https://github.com/typescript-eslint/typescript-eslint) for the supported TypeScript version.
 159
 160 **Please ensure that you are using a supported version before submitting any issues/bug reports.**
 161
 162 ## Reporting Issues
 163
 164 Please use the `@typescript-eslint/parser` issue template when creating your issue and fill out the information requested as best you can. This will really help us when looking into your issue.
 165
 166 ## License
 167
 168 TypeScript ESLint Parser is licensed under a permissive BSD 2-clause license.
 169
 170 ## Contributing
 171
 172 [See the contributing guide here](../../CONTRIBUTING.md)