estree-util-attach-comments

What is estree-util-attach-comments?

The estree-util-attach-comments package is a utility for attaching comments to nodes in an ESTree-compliant abstract syntax tree (AST). This is particularly useful for tools that need to preserve comments when transforming or analyzing JavaScript code.

What are estree-util-attach-comments's main functionalities?

Attach comments to AST nodes

This feature allows you to attach comments to the corresponding nodes in an AST. The code sample demonstrates parsing JavaScript code with Acorn, collecting comments, and then attaching those comments to the AST nodes using estree-util-attach-comments.

const { attachComments } = require('estree-util-attach-comments');
const acorn = require('acorn');
const comments = [];
const ast = acorn.parse('const x = 42; // a comment', {
  onComment: comments
});
attachComments(ast, comments);
console.log(ast);

Other packages similar to estree-util-attach-comments

recast

Recast is a JavaScript syntax tree transformer, specifically designed to work with ESTree-compliant ASTs. It can parse, transform, and print JavaScript code while preserving comments. Compared to estree-util-attach-comments, Recast offers a more comprehensive set of features for code transformation and comment preservation.

babel

Babel is a widely-used JavaScript compiler that can transform ES6+ code into backwards-compatible JavaScript. It includes a powerful parser (Babylon) and a set of tools for manipulating ASTs. Babel also preserves comments during transformations, making it a more feature-rich alternative to estree-util-attach-comments for complex code transformations.

esprima

Esprima is a high-performance, standard-compliant ECMAScript parser that produces ESTree-compliant ASTs. It can also collect comments during parsing. While Esprima does not directly attach comments to AST nodes, it can be used in conjunction with other tools like estree-util-attach-comments to achieve similar functionality.

README

estree-util-attach-comments

estree utility attach semistandard comment nodes (such as from acorn) to the nodes in that tree.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • attachComments(tree, comments)
• Types
• Compatibility
• Contribute
• License

What is this?

This package is a utility that you can use to embed comment nodes inside a tree. This is useful because certain estree parsers give you an array (espree and acorn) whereas other estree tools expect comments to be embedded on nodes in the tree.

This package uses one comments array where each comment has leading and trailing fields, as applied by acorn, but does not support the slightly different non-standard comments made by espree.

When should I use this?

You can use this package when working with comments from Acorn and later working with a tool such as recast or Babel.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install estree-util-attach-comments

In Deno with esm.sh:

import {attachComments} from 'https://esm.sh/estree-util-attach-comments@3'

In browsers with esm.sh:

<script type="module">
  import {attachComments} from 'https://esm.sh/estree-util-attach-comments@3?bundle'
</script>

Use

Say our document x.js contains:

/* 1 */ function /* 2 */ a /* 3 */(/* 4 */ b) /* 5 */ {
  /* 6 */ return /* 7 */ b + /* 8 */ 1 /* 9 */
}

…and our module example.js looks as follows:

import fs from 'node:fs/promises'
import {parse} from 'acorn'
import {attachComments} from 'estree-util-attach-comments'
import recast from 'recast'

const code = String(await fs.readFile('x.js'))
const comments = []
const tree = parse(code, {
  sourceType: 'module',
  ecmaVersion: 'latest',
  onComment: comments
})

attachComments(tree, comments)

console.log(recast.print(tree).code)

Yields:

/* 1 */
function /* 2 */
a(
    /* 3 */
    /* 4 */
    b
) /* 5 */
{
    /* 6 */
    return (
        /* 7 */
        b + /* 8 */
        1
    );
}/* 9 */

👉 Note: the lines are added by recast in this case. And, some of these weird comments are off, but they’re pretty close.

API

This package exports the identifier attachComments. There is no default export.

attachComments(tree, comments)

Attach semistandard estree comment nodes to the tree.

This mutates the given tree. It takes comments, walks the tree, and adds comments as close as possible to where they originated.

Comment nodes are given two boolean fields: leading (true for /* a */ b) and trailing (true for a /* b */). Both fields are false for dangling comments: [/* a */]. This is what recast uses too, and is somewhat similar to Babel, which is not estree but instead uses leadingComments, trailingComments, and innerComments arrays on nodes.

The algorithm checks any node: even recent (or future) proposals or nonstandard syntax such as JSX, because it ducktypes to find nodes instead of having a list of visitor keys.

The algorithm supports loc fields (line/column), range fields (offsets), and direct start / end fields.

Parameters

• tree (Program) — tree to attach to
• comments (Array<EstreeComment>) — list of comments

Returns

Nothing (undefined).

Types

This package is fully typed with TypeScript. It exports no additional types.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, estree-util-attach-comments@^3, compatible with Node.js 16.

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

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

License

MIT © Titus Wormer