kflash / seafox

A blazing fast 100% spec compliant, self-hosted javascript parser written in Typescript

Seafox

A blazing fast 100% spec compliant, self-hosted javascript parser written in Typescript.

Features

• Conforms to the standard ECMAScript® 2021 (ECMA-262 11th Edition) language specification
• Support for additional ECMAScript features for Web Browsers
• Optionally track syntactic node locations
• Emits an ESTree-compatible abstract syntax tree
• Lexical analysis
• No backtracking
• Low memory usage
• Insane performance both on desktop computers and handheld devices
• Twice as fast as other Javascript parsers
• Very well tested (~33 000 unit tests with full code coverage)
• Lightweight - ~84 KB minified

Installation

npm install seafox --save-dev

API

Seafox generates AST according to ESTree AST format, and can be used to perform syntactic analysis (parsing) or lexical analysis (tokenization) 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 Seafox takes an optional options object which allows you to specify whether to parse in script mode (the default) or in module mode.

This is the available options:

{
  // Allow parsing using Module as the goal symbol
  module?: boolean;

  // The flag to enable start and end offsets and line/column location information to each node
  loc: false;

  // Disable web compatibility
  disableWebCompat: false;

  // The flag to attach raw property to each literal and identifier node
  raw: false;

  // Enabled directives
  directives: false;

  // The flag to allow return in the global scope
  globalReturn: false;

  // The flag to enable implied strict mode
  impliedStrict: false;

// Enable non-standard parenthesized expression node
  preserveParens: false;

   // Allows token extraction. Accepts only a function
  onToken: function() {}
}

Example usage:

import { parseScript, parseModule, parse } from './seafox';

parseScript('({x: [y] = 0} = 1)');

parseModule('({x: [y] = 0} = 1)', { directives: true, raw: true });

parse('({x: [y] = 0} = 1)', { module: true });

parse('({x: [y] = 0} = 1)');

Lexical analysis

Lexical analysis can only be done during parsing and accepts only a function type as the option

 parseScript('foo = bar', { onToken: () => {}});

The callback function have 4 arguments.

Arguments	Description
token	The token to be extracted
value	Value of the extracted token
start	Start position of the extracted token
end	End position of the extracted token

The loc option needs to be enabled for start and end. Otherwise this values will be set to undefined

Performance

Seafox is developed for performance and low memory usage, and the parser is about 2x - 4x faster than all other javascript parsers.

seafox's Issues

Seafox Performance

Seafox is build for performance, and this is the current benchmark results.

Variable declarations inside of for loop breaks

When parsing for loops with variable declarations, the type attribute is incorrectly set.

for (const x of y) {

}

AST Output:

{
  "type": "VariableDeclaration",
  "kind": 32,
  "declarations": [
    {
      "type": "VariableDeclarator",
      "id": {
        "type": "Identifier",
        "name": "x"
      },
      "init": null
    }
  ]
}

Expected:

{
  "type": "VariableDeclaration",
  "kind": "const",
  "declarations": [
    {
      "type": "VariableDeclarator",
      "id": {
        "type": "Identifier",
        "name": "x"
      },
      "init": null
    }
  ]
}
```

Await expression can not be a class heritage

async function f() {   class x extends await y { }   }

Per spec: https://tc39.es/ecma262/#prod-ClassHeritage ClassHeritage should be a LeftHandSideExpression. If I am reading correctly, AwaitExpression is not a LeftHandSideExpression.

Importing

[Request] support onToken option like meriyah?

What is Seafox?

This is my private parser code made public. It strictly conforms to the standard ECMAScript® 2020 (ECMA-262 10th Edition) language specification, and can not be used as an drop-in replacement for other parsers.

The main reason for this is that all parsers uses a parse() method - Seafox uses either parseScript or parseModule.

Seafox focus only on performance, and if you are soft hearted and / or can't understand super low level code - this parser isn't for you :)

I would recommend to use the Meriyah parser instead of Seafox if you need a parser that behave like other public parsers, and also if you are in need of performance even the fact that Seafox is 15 - 25 % faster than the mentioned parser.

Confused about the AST related to optional chaining expressions

The following two expressions produce unexpectedly different output structures. I'm confused why this might be the case, and (assuming it's not a bug) how I should logically understand the structure when it comes to rendering. It's not clear, based on the AST, exactly where the optional chain operator should go. Why is c optional in the second example but not the first? Why does a computed property affect the structure so much? Also why is there always a base property? Why not just an array of chaining members?

Note that I'm trying this with Seafox as I was previously trying to do it with Meriyah, but Meriyah was producing an even more confusing structure with a kind of weird backward-nested structure that seems to chain in reverse via nested base properties.

seafox.parse(`a?.b?.[c]`)
seafox.parse(`a?.b?.c`)

Relevant outputs:

{
  "type": "MemberExpression",
  "object": {
    "type": "ChainingExpression",
    "base": {
      "type": "Identifier",
      "name": "a"
    },
    "chain": [
      {
        "type": "MemberChain",
        "computed": false,
        "property": {
          "type": "Identifier",
          "name": "b"
        },
        "optional": true
      }
    ]
  },
  "computed": true,
  "property": {
    "type": "Identifier",
    "name": "c"
  }
}

{
  "type": "ChainingExpression",
  "base": {
    "type": "Identifier",
    "name": "a"
  },
  "chain": [
    {
      "type": "MemberChain",
      "computed": false,
      "property": {
        "type": "Identifier",
        "name": "b"
      },
      "optional": true
    },
    {
      "type": "MemberChain",
      "computed": false,
      "property": {
        "type": "Identifier",
        "name": "c"
      },
      "optional": true
    }
  ]
}

Current released version includes debug logging

I was trying out the released version of seafox (1.6.9) and note that it appears to have shipped with lots of baked-in debug logging (via console.log()). I suspect that this was a mistake and wonder if a new release might be cut with those bits of logging removed.

I have a use-case where I need to perform semantic analysis in the browser and am looking for a combination of performance and bundle size. Seafox looks like a great candidate there!

Reused bit in common flags bit set

I was browsing the source code and stumbled across a bit set that had a duplicate bit set ("set" being the verb here). Is this intentional?

seafox/src/parser/common.ts

Lines 58 to 59 in d5242d0

	CommentStart = 1 << 12,
	DisallowCall = 1 << 12

Parenthesized LHS is not reinterpreted as parethensized destructuring target in some edge cases

([(a) = []] = []) => {}
async ([(a) = []] = []) => {};
function f([(a) = []] = []) {};

should throw

Kataw - alternative JS parser if performance matters

If no need for ESTree, Kataw (work in progress) is the fastest JS parser. See benchmark.

Kataw is an CST.