babylon

Babylon is a JavaScript parser used in Babel.

• The latest ECMAScript version enabled by default (ES2017).
• Comment attachment.
• Support for JSX and Flow.
• Support for experimental language proposals (accepting PRs for anything at least stage-0).

Credits

Heavily based on acorn and acorn-jsx, thanks to the awesome work of @RReverser and @marijnh.

Significant diversions are expected to occur in the future such as streaming, EBNF definitions, sweet.js integration, interspatial parsing and more.

API

babylon.parse(code, [options])

babylon.parseExpression(code, [options])

parse() parses the provided code as an entire ECMAScript program, while parseExpression() tries to parse a single Expression with performance in mind. When in doubt, use .parse().

Options

• allowImportExportEverywhere: 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.

• allowReturnOutsideFunction: By default, a return statement at the top level raises an error. Set this to true to accept such code.

• allowSuperOutsideMethod: TODO

• sourceType: Indicate the mode the code should be parsed in. Can be either "script" or "module".

• sourceFilename: Correlate output AST nodes with their source filename. Useful when generating code and source maps from the ASTs of multiple input files.

• startLine: 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.

• plugins: Array containing the plugins that you want to enable.

• strictMode: TODO

Output

Babylon generates AST according to Babel AST format. It is based on ESTree spec with the following deviations:

• Literal token is replaced with StringLiteral, NumericLiteral, BooleanLiteral, NullLiteral, RegExpLiteral
• Property token is replaced with ObjectProperty and ObjectMethod
• MethodDefinition is replaced with ClassMethod
• Program and BlockStatement contain additional directives field with Directive and DirectiveLiteral
• ClassMethod, ObjectProperty, and ObjectMethod value property's properties in FunctionExpression is coerced/brought into the main method node.

AST for JSX code is based on Facebook JSX AST with the addition of one node type:

• JSXText

Semver

Babylon follows semver in most situations. The only thing to note is that some spec-compliancy bug fixes may be released under patch versions.

For example: We push a fix to early error on something like #107 - multiple default exports per file. That would be considered a bug fix even though it would cause a build to fail.

Example

require("babylon").parse("code", {
  // parse in strict mode and allow module declarations
  sourceType: "module",

  plugins: [
    // enable jsx and flow syntax
    "jsx",
    "flow"
  ]
});

Plugins

• jsx
• flow
• doExpressions
• objectRestSpread
• decorators (Based on an outdated version of the Decorators proposal. Will be removed in a future version of Babylon)
• classProperties
• exportExtensions
• asyncGenerators
• functionBind
• functionSent
• dynamicImport

Changelog

6.16.0 (2017-02-23)

:rocket: New Feature

ESTree compatibility as plugin (#277) (Daniel Tschinder)

We finally introduce a new compatibility layer for ESTree. To put babylon into ESTree-compatible mode the new plugin estree can be enabled. In this mode the parser will output an AST that is compliant to the specs of ESTree

We highly recommend everyone who uses babylon outside of babel to use this plugin. This will make it much easier for users to switch between different ESTree-compatible parsers. We so far tested several projects with different parsers and exchanged their parser to babylon and in nearly all cases it worked out of the box. Some other estree-compatible parsers include acorn, esprima, espree, flow-parser, etc.

To enable estree mode simply add the plugin in the config:

{
  "plugins": [ "estree" ]
}

If you want to migrate your project from non-ESTree mode to ESTree, have a look at our Readme, where all deviations are mentioned.

Add a parseExpression public method (#213) (jeromew)

Babylon exports a new function to parse a single expression

import { parseExpression } from 'babylon';

const ast = parseExpression('x || y && z', options);

The returned AST will only consist of the expression. The options are the same as for parse()

Add startLine option (#346) (Raphael Mu)

A new option was added to babylon allowing to change the intial linenumber for the first line which is usually 1. Changing this for example to 100 will make line 1 of the input source to be marked as line 100, line 2 as 101, line 3 as 102, ...

Function predicate declaration (#103) (Panagiotis Vekris)

Added support for function predicates which flow introduced in version 0.33.0

declare function is_number(x: mixed): boolean %checks(typeof x === "number");

Allow imports in declare module (#315) (Daniel Tschinder)

Added support for imports within module declarations which flow introduced in version 0.37.0

declare module "C" {
  import type { DT } from "D";
  declare export type CT = { D: DT };
}

:eyeglasses: Spec Compliancy

Forbid semicolons after decorators in classes (#352) (Kevin Gibbons)

This example now correctly throws an error when there is a semicolon after the decorator:

class A {
@a;
foo(){}
}

Keywords are not allowed as local specifier (#307) (Daniel Tschinder)

Using keywords in imports is not allowed anymore:

import { default } from "foo";
import { a as debugger } from "foo";

Do not allow overwritting of primitive types (#314) (Daniel Tschinder)

In flow it is now forbidden to overwrite the primitve types "any", "mixed", "empty", "bool", "boolean", "number", "string", "void" and "null" with your own type declaration.

Disallow import type { type a } from … (#305) (Daniel Tschinder)

The following code now correctly throws an error

import type { type a } from "foo";

Don't parse class properties without initializers when classProperties is disabled and Flow is enabled (#300) (Andrew Levine)

Ensure that you enable the classProperties plugin in order to enable correct parsing of class properties. Prior to this version it was possible to parse them by enabling the flow plugin but this was not intended the behaviour.

If you enable the flow plugin you can only define the type of the class properties, but not initialize them.

Fix export default async function to be FunctionDeclaration (#324) (Daniel Tschinder)

Parsing the following code now returns a FunctionDeclaration AST node instead of FunctionExpression.

export default async function bar() {};

:nail_care: Polish

Improve error message on attempt to destructure named import (#288) (Brian Ng)

:bug: Bug Fix

Fix negative number literal typeannotations (#366) (Daniel Tschinder)

Ensure takeDecorators is called on exported class (#358) (Brian Ng)

ESTree: correctly change literals in all cases (#368) (Daniel Tschinder)

Correctly convert RestProperty to Assignable (#339) (Daniel Tschinder)

Fix #321 by allowing question marks in type params (#338) (Daniel Tschinder)

Fix #336 by correctly setting arrow-param (#337) (Daniel Tschinder)

Fix parse error when destructuring set with default value (#317) (Brian Ng)

Fix ObjectTypeCallProperty static (#298) (Dan Harper)

:house: Internal

Fix generator-method-with-computed-name spec (#360) (Alex Rattray)

Fix flow type-parameter-declaration test with unintended semantic (#361) (Alex Rattray)

Cleanup and splitup parser functions (#295) (Daniel Tschinder)

chore(package): update flow-bin to version 0.38.0 (#313) (greenkeeper[bot])

Call inner function instead of 1:1 copy to plugin (#294) (Daniel Tschinder)

Update eslint-config-babel to the latest version 🚀 (#299) (greenkeeper[bot])

Update eslint-config-babel to the latest version 🚀 (#293) (greenkeeper[bot])

devDeps: remove eslint-plugin-babel (#292) (Kai Cataldo)

Correct indent eslint rule config (#276) (Daniel Tschinder)

Fail tests that have expected.json and throws-option (#285) (Daniel Tschinder)

:memo: Documentation

Update contributing with more test info [skip ci] (#355) (Brian Ng)

Update API documentation (#330) (Timothy Gu)

Added keywords to package.json (#323) (Dmytro)

AST spec: fix casing of RegExpLiteral (#318) (Mathias Bynens)