Skip to content

ECMAScript Abstract Syntax Tree format

Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



11 Commits

Repository files navigation


ECMAScript Abstract Syntax Tree format.

esast is a specification for representing JavaScript as an abstract syntax tree. It implements the unist spec.

This document may not be released. See releases for released documents. The latest released version is 1.0.0.



This document defines a format for representing ECMAScript as an abstract syntax tree. Development of esast started in February 2021. This specification is written in a Web IDL-like grammar.

Where this specification fits

esast extends unist, a format for syntax trees, to benefit from its ecosystem of utilities. There is one important difference with other implementations of unist: children are added at fields other than the children array and the children field is not used.

esast relates to ESTree in that the first is a superset of the latter. Any tool that accepts an ESTree also supports esast.

esast relates to JavaScript, other than that it represents it, in that it has an ecosystem of utilities for working with compliant syntax trees in JavaScript. However, esast is not limited to JavaScript and can be used in other programming languages.

esast relates to the unified project in that esast syntax trees are used throughout its ecosystem.


ESTree is great but it is missing some things:

  • Trees can’t be roundtripped through JSON.parse(JSON.stringify(s)), leading to cache troubles
  • Columns are 0-indexed, whereas most text editors display 1-indexed columns, leading to a tiny discrepancy or some math to display warnings
  • There is no recommendation for range-based positional info, leading implementations to scatter them in different places
  • There is no safe space for metadata, leading implementations to scatter them in different places
  • There are no recommendations for how to handle JSX, comments, or raw values

These are minor nits, which is why esast is a superset.



extend interface Node <: UnistNode {}

All esast nodes inherit from unist’s Node and are otherwise the same as their ESTree counterparts, with the exception of RegExpLiteral and BigIntLiteral.


The regex field on RegExpLiteral must be used whereas the value field of such literals should be null and must be ignored.


The bigint field on BigIntLiteral must be used whereas the value field of such literals should be null and must be ignored.


For JSX, follow the JSX extension maintained in facebook/jsx.

For type annotations, follow the Type annotations extension maintained in estree/estree.

raw fields (added by most parsers) should not be used: they create an extra source of truth, which is often not maintained.

start, end, and range fields should not be used.

comments should not be added on nodes other that Program. When adding comments, use the 'Block' (for /**/) or 'Line' (for //) types. Do not use leading or trailing fields on comment nodes.

tokens should not be used.


See the unist glossary but note of the following deviating terms.


Node X is child of node Y, if X is either referenced directly or referenced in an array at a field on node Y.


Node X is a sibling of node Y, if X and Y have the same parent (if any) and X and Y are both referenced in an array at a field on node Y.

List of utilities

See the unist list of utilities for more utilities.

Please use either estree-util- (if it works with all ESTrees, preferred) or esast-util- (if it uses on esast specific features) as a prefix.

See also the estree topic on GitHub.



As esast represents JS, and JS can open you up to a bunch of problems, esast is also unsafe. Always be careful with user input.



See in syntax-tree/.github for ways to get started. See for ways to get help. Ideas for new utilities and tools can be posted in syntax-tree/ideas.

A curated list of awesome syntax-tree, unist, mdast, esast, xast, and nlcst resources can be found in awesome syntax-tree.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.


The initial release of this project was authored by @wooorm.


CC-BY-4.0 © Titus Wormer