syntax-tree/esast

ECMAScript Abstract Syntax Tree format

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.

Contents

• Introduction
  • Where this specification fits
  • ESTree
• Nodes
  • Node
  • RegExpLiteral
  • BigIntLiteral
• Recommendations
• Glossary
• List of utilities
• References
• Security
• Related
• Contribute
• Acknowledgments
• License

Introduction

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

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.

Nodes

Node

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.

RegExpLiteral

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

BigIntLiteral

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

Recommendations

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.

Glossary

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

Child

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

Sibling

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.

• estree-util-attach-comments — attach comments to estree nodes
• estree-util-build-jsx — transform JSX to function calls
• estree-util-is-identifier-name — check if something can be an identifier name
• estree-util-value-to-estree — convert a JavaScript value to an estree expression
• estree-util-to-js — serialize as JavaScript
• estree-util-visit — visit nodes
• esast-util-from-estree — transform from estree
• esast-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.

References

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

Security

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.

Related

• hast — HTML
• mdast — Markdown
• nlcst — Natural language
• xast — XML

Contribute

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.

Acknowledgments

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

License

CC-BY-4.0 © Titus Wormer