From ca6578113278bd69c9566c6f755afffe5c72aaf3 Mon Sep 17 00:00:00 2001 From: Avi Vahl Date: Fri, 15 Jun 2018 01:04:49 +0300 Subject: [PATCH 1/5] @babel/parser: expose a TypeScript definition file from package This allows the new parser package to be used in TypeScript projects, with static type checking and auto-completions. IDEs like VSCode will use this to show auto completions even in JavaScript projects, which is a huge benefit to users wanting to use the parser directly. This PR follows the auto-generated .d.ts that was added to @babel/types in #7101 - took outdated DefinitelyTyped babylon .d.ts and updated it using new site's documentation. - added "typings" folder to package, with the new .d.ts - connected new .d.ts via package.json's "types" field. also adjusted "files" so folder will be published. - definition file uses TypeScript 2.9's new `import('package').Type` syntax. --- packages/babel-parser/package.json | 4 +- .../babel-parser/typings/babel-parser.d.ts | 102 ++++++++++++++++++ 2 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 packages/babel-parser/typings/babel-parser.d.ts diff --git a/packages/babel-parser/package.json b/packages/babel-parser/package.json index 6878e25f4f..e1d4a54adb 100644 --- a/packages/babel-parser/package.json +++ b/packages/babel-parser/package.json @@ -15,9 +15,11 @@ ], "repository": "https://github.com/babel/babel/tree/master/packages/babel-parser", "main": "lib/index.js", + "types": "typings/babel-parser.d.ts", "files": [ "bin", - "lib" + "lib", + "typings" ], "engines": { "node": ">=6.0.0" diff --git a/packages/babel-parser/typings/babel-parser.d.ts b/packages/babel-parser/typings/babel-parser.d.ts new file mode 100644 index 0000000000..9736b7a2ef --- /dev/null +++ b/packages/babel-parser/typings/babel-parser.d.ts @@ -0,0 +1,102 @@ +// Type definitions for @babel/parser +// Project: https://github.com/babel/babel/tree/master/packages/babel-parser +// Definitions by: Troy Gerwien +// Marvin Hagemeister +// Avi Vahl +// TypeScript Version: 2.9 + +export function parse(code: string, opts?: BabelParserOptions): import('@babel/types').File; +export function parseExpression(input: string, options?: BabelParserOptions): import('@babel/types').Expression; + +export interface BabelParserOptions { + /** + * By default, import and export declarations can only appear at a program's top level. + * Setting this option to true allows them anywhere where a statement is allowed. + */ + allowImportExportEverywhere?: boolean; + + /** + * By default, await use is not allowed outside of an async function. + * Set this to true to accept such code. + */ + allowAwaitOutsideFunction?: boolean; + + /** + * By default, a return statement at the top level raises an error. + * Set this to true to accept such code. + */ + allowReturnOutsideFunction?: boolean; + + allowSuperOutsideMethod?: boolean; + + /** + * Indicate the mode the code should be parsed in. + * Can be one of "script", "module", or "unambiguous". Defaults to "script". + * "unambiguous" will make @babel/parser attempt to guess, based on the presence + * of ES6 import or export statements. + * Files with ES6 imports and exports are considered "module" and are otherwise "script". + */ + sourceType?: 'script' | 'module' | 'unambiguous'; + + /** + * Correlate output AST nodes with their source filename. + * Useful when generating code and source maps from the ASTs of multiple input files. + */ + sourceFilename?: string; + + /** + * By default, the first line of code parsed is treated as line 1. + * You can provide a line number to alternatively start with. + * Useful for integration with other source tools. + */ + startLine?: number; + + /** + * Array containing the plugins that you want to enable. + */ + plugins?: PluginName[]; + + /** + * Should the parser work in strict mode. + * Defaults to true if sourceType === 'module'. Otherwise, false. + */ + strictMode?: boolean; + + /** + * Adds a ranges property to each node: [node.start, node.end] + */ + ranges?: boolean; + + /** + * Adds all parsed tokens to a tokens property on the File node. + */ + tokens?: boolean; +} + +export type PluginName = + 'estree' | + 'jsx' | + 'flow' | + 'flowComments' | + 'typescript' | + 'doExpressions' | + 'objectRestSpread' | + 'decorators' | + 'decorators-legacy' | + 'classProperties' | + 'classPrivateProperties' | + 'classPrivateMethods' | + 'exportDefaultFrom' | + 'exportNamespaceFrom' | + 'asyncGenerators' | + 'functionBind' | + 'functionSent' | + 'dynamicImport' | + 'numericSeparator' | + 'optionalChaining' | + 'importMeta' | + 'bigInt' | + 'optionalCatchBinding' | + 'throwExpressions' | + 'pipelineOperator' | + 'nullishCoalescingOperator'; From adbf2a15f967946a77811e625a268df3acf71ab3 Mon Sep 17 00:00:00 2001 From: Avi Vahl Date: Fri, 15 Jun 2018 01:12:58 +0300 Subject: [PATCH 2/5] Clearer naming of interfaces --- packages/babel-parser/typings/babel-parser.d.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/babel-parser/typings/babel-parser.d.ts b/packages/babel-parser/typings/babel-parser.d.ts index 9736b7a2ef..2ca40431bb 100644 --- a/packages/babel-parser/typings/babel-parser.d.ts +++ b/packages/babel-parser/typings/babel-parser.d.ts @@ -5,10 +5,10 @@ // Avi Vahl // TypeScript Version: 2.9 -export function parse(code: string, opts?: BabelParserOptions): import('@babel/types').File; -export function parseExpression(input: string, options?: BabelParserOptions): import('@babel/types').Expression; +export function parse(code: string, options?: ParserOptions): import('@babel/types').File; +export function parseExpression(input: string, options?: ParserOptions): import('@babel/types').Expression; -export interface BabelParserOptions { +export interface ParserOptions { /** * By default, import and export declarations can only appear at a program's top level. * Setting this option to true allows them anywhere where a statement is allowed. @@ -54,7 +54,7 @@ export interface BabelParserOptions { /** * Array containing the plugins that you want to enable. */ - plugins?: PluginName[]; + plugins?: ParserPlugin[]; /** * Should the parser work in strict mode. @@ -73,7 +73,7 @@ export interface BabelParserOptions { tokens?: boolean; } -export type PluginName = +export type ParserPlugin = 'estree' | 'jsx' | 'flow' | From 4cdfee768bc816b2e4f03c1bb4e44b9a25475184 Mon Sep 17 00:00:00 2001 From: Avi Vahl Date: Fri, 15 Jun 2018 02:42:32 +0300 Subject: [PATCH 3/5] Add jsdocs to parse() and parseExpression() also change parameter name to match docs --- packages/babel-parser/typings/babel-parser.d.ts | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/babel-parser/typings/babel-parser.d.ts b/packages/babel-parser/typings/babel-parser.d.ts index 2ca40431bb..983399e2d3 100644 --- a/packages/babel-parser/typings/babel-parser.d.ts +++ b/packages/babel-parser/typings/babel-parser.d.ts @@ -5,8 +5,15 @@ // Avi Vahl // TypeScript Version: 2.9 +/** + * Parse the provided code as an entire ECMAScript program. + */ export function parse(code: string, options?: ParserOptions): import('@babel/types').File; -export function parseExpression(input: string, options?: ParserOptions): import('@babel/types').Expression; + +/** + * Parse the provided code as a single Expression. + */ +export function parseExpression(code: string, options?: ParserOptions): import('@babel/types').Expression; export interface ParserOptions { /** From 0e8830f3a84ee05a30cd1fe9d560dc6b2c582c3c Mon Sep 17 00:00:00 2001 From: Avi Vahl Date: Fri, 15 Jun 2018 02:46:02 +0300 Subject: [PATCH 4/5] Fix unneeded uppercasing in comment --- packages/babel-parser/typings/babel-parser.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/babel-parser/typings/babel-parser.d.ts b/packages/babel-parser/typings/babel-parser.d.ts index 983399e2d3..d3be84edb2 100644 --- a/packages/babel-parser/typings/babel-parser.d.ts +++ b/packages/babel-parser/typings/babel-parser.d.ts @@ -11,7 +11,7 @@ export function parse(code: string, options?: ParserOptions): import('@babel/types').File; /** - * Parse the provided code as a single Expression. + * Parse the provided code as a single expression. */ export function parseExpression(code: string, options?: ParserOptions): import('@babel/types').Expression; From 6893b7e7d2d60bfc86554834704a16760e168aed Mon Sep 17 00:00:00 2001 From: Sven Sauleau Date: Mon, 3 Sep 2018 08:09:26 +0200 Subject: [PATCH 5/5] fix: [skip ci] consistent naming --- packages/babel-parser/typings/babel-parser.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/babel-parser/typings/babel-parser.d.ts b/packages/babel-parser/typings/babel-parser.d.ts index d3be84edb2..752fc365f0 100644 --- a/packages/babel-parser/typings/babel-parser.d.ts +++ b/packages/babel-parser/typings/babel-parser.d.ts @@ -8,12 +8,12 @@ /** * Parse the provided code as an entire ECMAScript program. */ -export function parse(code: string, options?: ParserOptions): import('@babel/types').File; +export function parse(input: string, options?: ParserOptions): import('@babel/types').File; /** * Parse the provided code as a single expression. */ -export function parseExpression(code: string, options?: ParserOptions): import('@babel/types').Expression; +export function parseExpression(input: string, options?: ParserOptions): import('@babel/types').Expression; export interface ParserOptions { /**