npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@es-joy/jsdoc-eslint-parser

v0.21.1

Published

Parser to support JavaScript with JSDoc comments and types available as AST

Downloads

87

Readme

@es-joy/jsdoc-eslint-parser

This project has not been well-tested and should be considered experimental.

This project aims to allow full @babel/eslint-parser configuration, but with comment-parser-based AST for JSDoc blocks and jsdoctypeparser AST for JSDoc types within those blocks.

There is also a @es-joy/jsdoc-eslint-parser/typescript.js parser which builds on @typescript-eslint/parser.

It is hoped that this may spur development of official ESTree acceptance of such AST.

You can run our lint-test script for an example.

Use cases

  1. Using no-restricted-syntax to prohibit certain comment or comment type AST
  2. Supplying comment or comment-type aware query selectors to contexts in eslint-plugin-jsdoc

Approach for attaching AST

In using the Babel ESLint parser, AST is produced which has the tokens on Program expected by ESLint as well as the range array expected on each Node.

We add comment AST--or, rather, JSDocBlock AST--by adding a jsdoc property to each item of the @babel/eslint-parser-parsed code which does not have a suitable ancestor to hold the comment block. We correspondingly update the visitor keys to ensure that for every key's array of visitable properties, jsdoc is added, so it can be separately traversable. We also ensure the comment-parser and jsdoctypeparser visitor keys are added to our parser's visitor keys.

And we add a parent for each Node so that our getJSDocComment method can find its way around (see below).

The tricky part with the jsdoc property comes in with determining which JSDoc should be associated with a given Node. In jsdoccomment, we have a getJSDocComment method, originally begun by ESLint itself to determine where that should be expected.

This detection of the comment for a given structure is not a trivial matter. For example, with:

/* A */
const /* B */ aFunc = /* C */ function () {};

... for the function expression, we might look for the JSDoc Block at point C or B first, but then if not present, look for it at point A. The getJSDocComment method uses such an algorithm, and we call this in our parser currently on each node. If there is no JSDoc block at point B or C, the node for the aFunc VariableDeclaration node should get the JSDoc Block at point A added instead of the FunctionExpression getting it.

Although abstractly, it may appear a better fit with FunctionExpression, the practical purposes of finding JSDoc blocks relates more to position and code generation, which should be easiest to work with if in a position closest to its actual location.

Note that the AST produced is described in the jsdoccomment project. Additionally, this parser adds to Program nodes, a jsdocBlocks property (corresponding to comments though for unattached comment blocks only), along with a commentsIndex integer proprerty to reflect the index to which this JSDoc block corresponds with the comments array.

Installation

npm i -D @es-joy/jsdoc-eslint-parser

Parser options

mode (Defaults to "jsdoc")

The jsdoctypeparser mode, jsdoc, typescript, closure, or permissive. The latter is not generally recommended.

maxLines (default: 1) and minLines (default: 0)

Determines how far up in terms of lines from a structure, we should allow the finding of comment blocks.

indent (default: "")

This is currently exposed but should probably not be changed and may be removed in the future. It indicates the indent to be used when parsing comments. (That may need to be auto-detected in the future.)

sourceType (defaults to @babel/eslint-parser's default)

For indicating script or module

babelOptions (default: none)

Extra options to pass on to Babel (if not using the typescript parser).

...parserOptions (default: none)

Any other options are passed onto the parser.

Changelog

The changelog can be found on the CHANGES.md.

Authors and license

Brett Zamir and contributors.

MIT License, see the included LICENSE-MIT.md file.