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.
- Introduction
- Nodes
- Recommendations
- Glossary
- List of utilities
- References
- Security
- Related
- Contribute
- Acknowledgments
- License
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.
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 compliantsyntax 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.
See the unist list of utilities for more utilities.
estree-util-attach-comments— attach comments to estree nodesestree-util-build-jsx— transform JSX to function callsestree-util-is-identifier-name— check if something can be an identifier nameestree-util-value-to-estree— convert a JavaScript value to an estree expressionestree-util-to-js— serialize as JavaScriptestree-util-visit— visit nodesesast-util-from-estree— transform from estreeesast-util-from-js— parse from JavaScript
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.
- unist: Universal Syntax Tree. T. Wormer; et al.
- JavaScript: ECMAScript Language Specification. Ecma International.
- JSON The JavaScript Object Notation (JSON) Data Interchange Format, T. Bray. IETF.
- Web IDL: Web IDL, C. McCormack. W3C.
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 contributing.md in syntax-tree/.github for
ways to get started.
See support.md 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.