Standardize and document configuration options

Author: Kai Cataldo

README.md

@@ -13,16 +13,75 @@
 
 <br>
 
-## Usage
-
-This parser is somewhat generic and robust, it could be used to power any use-case which requires taking TypeScript source code and producing an ESTree-compatiable AST.
+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-compatiable AST.
 
 In fact, it is already used within these hyper-popular open-source projects to power their TypeScript support:
 
 - [ESLint](https://eslint.org), the pluggable linting utility for JavaScript and JSX
   - See [typescript-eslint-parser](https://github.com/eslint/typescript-eslint-parser) for more details
 - [Prettier](https://prettier.io), an opinionated code formatter
 
+## Usage
+
+Install:
+
+```
+npm i typescript-estree --save
+```
+
+And in your Node.js code:
+
+```javascript
+const parser = require("typescript-estree");
+const ast = parser.parse(code);
+```
+
+There is a second argument to `parse()` that allows you to specify various options:
+
+```javascript
+const parser = require("typescript-estree");
+// Optional second options argument with the following default settings
+const ast = parser.parse(code, {
+
+    // 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
+    jsx: false,
+
+    tolerant: false,
+
+    source: null,
+
+    /*
+     * 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
+});
+```
+
 ## Supported TypeScript Version
 
 We will always endeavor to support the latest stable version of TypeScript.

parser.js

@@ -38,7 +38,7 @@ function resetExtra() {
     tolerant: false,
     errors: [],
     strict: false,
-    ecmaFeatures: {},
+    jsx: false,
     useJSXTextNode: false,
     log: console.log
   };
@@ -82,9 +82,8 @@ function generateAST(code, options) {
       extra.errors = [];
     }
 
-    if (options.ecmaFeatures && typeof options.ecmaFeatures === 'object') {
-      // pass through jsx option
-      extra.ecmaFeatures.jsx = options.ecmaFeatures.jsx;
+    if (typeof options.jsx === 'boolean' && options.jsx) {
+      extra.jsx = options.jsx;
     }
 
     /**
@@ -126,7 +125,7 @@ function generateAST(code, options) {
 
   // Even if jsx option is set in typescript compiler, filename still has to
   // contain .tsx file extension
-  const FILENAME = extra.ecmaFeatures.jsx ? 'estree.tsx' : 'estree.ts';
+  const FILENAME = extra.jsx ? 'estree.tsx' : 'estree.ts';
 
   const compilerHost = {
     fileExists() {
@@ -165,7 +164,7 @@ function generateAST(code, options) {
     {
       noResolve: true,
       target: ts.ScriptTarget.Latest,
-      jsx: extra.ecmaFeatures.jsx ? 'preserve' : undefined
+      jsx: extra.jsx ? 'preserve' : undefined
     },
     compilerHost
   );