Awesome
estree-util-attach-comments
estree utility attach semistandard comment nodes (such as from acorn) to the nodes in that tree.
Contents
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 tocomments
(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.