Cherow

A very fast, standards-compliant, self-hosted ECMAScript parser with high focus on both performance and stability.

It strictly follows the ECMAScript® 2018 Language Specification and should parse according to these specifications.

Demo and Benchmark

Features

• Full support for ECMAScript® 2017 (ECMA-262 8th Edition)
• Full support for all stage 3 proposals via option
• Emits an ESTree-compatible abstract syntax tree.
• Optimzed for handheld devices
• Early error tolerant parsing
• Skips hashbang comment nodes by default
• Skips BOM (U+FEFF) by default
• Optional tracking of syntax node location (index-based and line-column)
• Very well tested (~54 000 unit tests with full code coverage))
• 95% Test262 Test coverage

ESNext features

Stage 3 features support. These need to be enabled with the next option.

• Import()
• Class Fields
• Numeric Separators
• Private methods and fields
• Optional catch binding
• JSON Superset
• BigInt
• Import.meta

API

Cherow generates AST according to ESTree AST format, and can be used to perform syntactic analysis (parsing) of a JavaScript program, and with ES2015 and later a JavaScript program can be either a script or a module and this is achieved by choosing parseScript function to parse a script and parseModule function to parse a module.

Here is a quick example:

cherow.parseScript('const fooBar = 123;', { ranges: true});

This will return when serialized in json:

{
    "type": "Program",
    "sourceType": "script",
    "body": [
        {
            "type": "VariableDeclaration",
            "declarations": [
                {
                    "type": "VariableDeclarator",
                    "init": {
                        "type": "Literal",
                        "value": 123,
                        "start": 15,
                        "end": 18
                    },
                    "id": {
                        "type": "Identifier",
                        "name": "fooBar",
                        "start": 6,
                        "end": 12
                    },
                    "start": 6,
                    "end": 18
                }
            ],
            "kind": "const",
            "start": 0,
            "end": 19
        }
    ],
    "start": 0,
    "end": 19
}

Options

Both methods accept the following options, none required:

Option	Description
comments	Create a top-level comments array containing all comments
early	Create a top-level error array containing all "skipped" early errors
loc	Set to true to append line/column offsets to each node
ranges	Set to true to append start and end offsets to each node
impliedStrict	Set to true to allow implied strict mode
next	Set to true to enable stage 3 support
plugins	Array containing the parameterized plugins that you want to enable
source	Correlate output AST nodes with their source filename
raw	Set to true to attach raw property to each literal node

Comments

Single line, multiline and HTML comments are supported by Cherow, and the parser can be instructed to collect comments by setting the comments option to true.

A top-level comments array containing all comments will be attached to the root node (Program), and the type of each comment can either be SingleLine for a single-line comment (//) or MultiLine for a MultiLineComment (/* */).

HTML comments is not a part of the ECMAScript specifications, and the way Cherow deals with them deviates slightly from other parsers. In Cherow HTMLOpen are used for a HTML open comments (<!--) and HTMLClose for a HTML close comment (-->). In other ECMAScripts parsers both are seen as a single-line comment .

Early error tolerant parsing

The tolerant algorithm used by Cherow deviates slightly from both Esprima and Acorn due to the parsers complexity, and it's primarily for early errors, and other errors that are basically valid syntax but just not allowed.

A top-level errors array containing all "skipped" early errors will be attached to the root node (Program),

// function a(){ break b; }

{
              body: [
                {
                  async: false,
                  body: {
                    body: [
                      {
                        label: {
                          name: 'b',
                          type: 'Identifier'
                        },
                        type: 'BreakStatement'
                      },
                    ],
                    type: 'BlockStatement'
                 },
                  expression: false,
                  generator: false,
                  id: {
                    name: 'a',
                    type: 'Identifier',
                  },
                  params: [],
                  type: 'FunctionDeclaration',
                },
              ],
              earlyErrors: [
                {
                  column: 21,
                  description: 'Undefined label "b"',
                  index: 21,
                  lineNumber: 1,
                },
              ],
              sourceType: 'script',
              type: 'Program'
            }

Bug reporting

If you caught a bug, don't hesitate to report it in the issue tracker. From the moment I respond to you, it will take maximum 30 minutes before the bug is fixed. Note that I will try to respond to you within one hour. Sometimes it can take a bit longer. I'm not allways online. And if I find out it will take more then 30 minutes to solve your issue, you will be notified.

I know how irritating it can be if you are writing code and encounter bugs in your dependencies. And even more frustrating if you need to wait weeks or days.

Contribution

If you feel something could've been done better, please do feel free to file a pull request with the changes.

Read our guidelines here