Skip to content
Very fast and lightweight, standards-compliant, self-hosted javascript parser with high focus on both performance and stability
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Update config.yml Jan 4, 2019
.github docs(*): add contributing.md (#165) Jul 4, 2018
.vscode chore: add vs code debugging config Jan 14, 2019
bench chore(bench): fix type errors / small tweaks Mar 16, 2019
media chore(all): move back to single repo structure Dec 10, 2018
scripts
src refactor(cherow): fixed regex edge cases Mar 19, 2019
test refactor(cherow): simplified context masks and ported tests from expe… Mar 12, 2019
.editorconfig
.gitignore chore(benchmark): add initial jsbench setup Feb 16, 2019
.npmrc chore: add .npmrc to enable lock explicitly Dec 23, 2018
.prettierignore chore: add ignored files Dec 28, 2018
LICENSE.md updated license Nov 9, 2017
README.md Update README.md Mar 3, 2019
package-lock.json refactor(cherow): added Unicode 12 support Mar 8, 2019
package.json
prettier.config.js refactor(cherow): linting Jan 18, 2019
tsconfig.json
tslint.json

README.md

Cherow

NPM version Gitter chat CircleCI Coverage Status Commitizen friendly Code Quality: Javascript Total Alerts

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

Demo and Benchmark

Features

  • Conforms to the standard ECMAScript® 2020 (ECMA-262 10th Edition) language specification (draft)
  • Support stage 3 proposals via option.
  • Support for parsing with and without web compability (AnnexB)
  • Support to only parse expressions
  • Experimental feature support via option.
  • Optionally track syntactic node locations
  • Emits an ESTree-compatible abstract syntax tree.
  • Very well tested (~25 000 unit tests with full code coverage))
  • Supports all module loaders
  • Lightweight - ~72 KB minified

ESNext features

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

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.

The parse method exposed by Cherow takes an optional options object which allows you to specify whether to parse in script mode (the default) or in module mode.

Here is a quick example to parse a script:

cherow.parseScript('foo = bar');

// or

cherow.parse('x = async() => { for await (x of xs); }');

This will return when serialized in json:

{
    body: [{
        expression: {
            left: {
                name: 'x',
                type: 'Identifier'
            },
            operator: '=',
            right: {
                async: true,
                body: {
                    body: [{
                        await: true,
                        body: {
                            type: 'EmptyStatement',
                        },
                        left: {
                            name: 'x',
                            type: 'Identifier',
                        },
                        right: {
                            name: 'xs',
                            type: 'Identifier',
                        },
                        type: 'ForOfStatement',
                    }],
                    type: 'BlockStatement'
                },
                expression: false,
                generator: false,
                id: null,
                params: [],
                type: 'ArrowFunctionExpression'
            },
            type: 'AssignmentExpression'
        },
        type: 'ExpressionStatement'
    }],
    sourceType: 'script',
    type: 'Program'
}

The API also allows you to use Cherow as a stand-alone expression parser and let you parse your code in either script or module goal code.

cherow.parseExpression('foo', { ranges: true });

This will return when serialized in json:

 {
      end: 3,
      name: 'foo',
      start: 0,
      type: 'Identifier'
    }

Options

The second argument allows you to specify various options:

Option Description
module Enable module syntax
ranges Append start and end offsets to each node
globalReturn Allow return in the global scope
globalAwait Allow await in the global scope
webcompat Enable web compability (AnnexB)
impliedStrict Enable strict mode initial enforcement
next Enable stage 3 support (ESNext)
experimental Enable experimental features
parenthesizedExpr Enable non-standard parenthesized expression node
raw Attach raw property to each literal node and identifier node
directives Enable directive prologue to each literal node
onComment Accept either callback or array to collect comment
onToken Accept either callback or array and returns each found token

Experimental features

Cherow aim to support the same experimental features as found in V8 when enabling the 'experimental' flag. However. An exception has been made for the numeric separators proposal. It's currently pending on Stage 2 after being "degraded" from Stage 3. The future of this proposal seems uncertain at the moment and will not be implemented.

Also the proposal-decorators are constantly changing so at current stage this will not be implemented.

Nightly builds

It's available on NPM.

Contributing

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

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 60 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 60 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.

Rationale

Existing parsers have many issues with them:

  • Acorn is the most commonly used tool out there because of its support for recent ES standards, but it's slow and it often is too permissive in what it accepts. It's also not optimized for handheld devices.

  • Esprima is a little faster than Acorn, but it's almost never updated, and their test suite has too many invalid tests. It also doesn't support recent ES standards.

  • Babylon is tightly coupled to Babel, and is comparatively very slow.

Most of these parsers would not fare any chance against the official Test262 suite, and fail a substantial number of them.

We figured we could try do better. We are used in plural form because Cherow is developed by a main developer and two others "behind the scenes" that contributes with their knowledge whenever it's necessary.


Cross-browser testing provided by:

BrowserStack

You can’t perform that action at this time.