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

astravel

v0.6.1

Published

ESTree-compliant AST walker and modifier.

Downloads

4,427

Readme

Astravel

NPM Version Build Status Coverage devDependency Status Greenkeeper

👟 A tiny and fast ESTree-compliant AST walker and modifier.

Key features

  • Works on ESTree-compliant ASTs (JavaScript version 13 (2022)), such as the ones produced by Meriyah.
  • Out-of-the-box functions such as source code comments insertion for Astring.
  • Extensible with custom nodes.
  • No dependencies and small footprint.

Installation

Install with the Node Package Manager:

npm install astravel

Alternatively, checkout this repository and install the development dependencies to build the module file:

git clone https://github.com/davidbonnet/astravel.git
cd astravel
npm install

Usage

The astravel module exports the following items:

defaultTraveler

⬅️ traveler

⚠️ Deprecated in favor of ES6 class notation.

This object describes a basic AST traveler. It contains the following methods:

  • go(node, state): Travels through the provided AST node with a given state (an object that can be of any type) by recursively calling this method.
  • find(predicate, node, state) ➞ { node, state }?: Returns { node, state } for which predicate(node, state) returns truthy, starting at the specified AST node and with the provided state. Otherwise, returns undefined.
  • [NodeType](node, state): Method handler for a specific NodeType.
  • makeChild(properties) ➞ traveler: Returns a custom AST traveler that inherits from this traveler with its own provided properties and the property super that points to this traveler.

makeTraveler()

➡️ (properties) ⬅️ traveler

⚠️ Deprecated in favor of ES6 class notation.

This function is similar to astravel.defaultTraveler.makeChild: it returns a traveler that inherits from the defaultTraveler with its own provided properties and the property super that points to the defaultTraveler object. These properties should redefine the traveler's behavior by implementing the go(node, state) method and/or any node handler.

When redefining the go method, make sure its basic functionality is kept by calling the parent's go method to keep traveling through the AST:

const customTraveler = makeTraveler({
  go: function (node, state) {
    // Code before entering the node
    console.log('Entering ' + node.type)
    // Call the parent's `go` method
    this.super.go.call(this, node, state)
    // Code after leaving the node
    console.log('Leaving ' + node.type)
  },
})

To skip specific node types, the most effective way is to replace the corresponding node handlers with a function that does nothing:

import { makeTraveler } from 'astravel'

const ignore = Function.prototype
const customTraveler = makeTraveler({
  FunctionDeclaration: ignore,
  FunctionExpression: ignore,
  ArrowFunctionExpression: ignore,
})

attachComments()

➡️ (ast, comments) ⬅️ ast

This function attaches a list of comments to the corresponding nodes of a provided ast and returns that same ast. The ast is modified in-place and only the nodes getting comments are augmented with a comments and/or a trailingComments array property.

Each comment should be an object with the following properties:

  • type: "Line" or "Block"
  • value: Comment string value
  • start: Comment starting character offset number
  • end: Comment ending character offset number
  • loc: Location object with start and end properties containing one-based line number and zero-based column number properties.

The following examples show how to obtain a proper list of comments of a given source code and how to attach them on the generated ast:

Usage with Meriyah
import { parse } from 'meriyah'
import { attachComments } from 'astravel'

const comments = []
const ast = parse(code, {
  // Comments are stored in this array
  onComment: comments,
})
// Attach comments on the AST
attachComments(ast, comments)
Usage with Acorn
import { parse } from 'acorn'
import { attachComments } from 'astravel'

const comments = []
const ast = parse(code, {
  // This ensures that the `loc` property is present on comment objects
  locations: true,
  onComment: comments,
})
attachComments(ast, comments)

The algorithm assumes that comments are not put in exotic places, such as in-between function arguments, and proceeds as follows:

  • For a given statement, it stores all comments right above it and on the same line to it's right side in a comments property.
  • If a comment block is at the beginning of a code block, it is attached to that code block.
  • Comments not followed by any statement in a code block are attached as trailingComments to that code block.

In this example, the comments tell to which statement they are attached:

// Attached to the variable declaration just below
const point = {
  // Attached to the property definition just below
  x: 0,
  y: 0, // Attached to the property definition on its left
}
/*
Attached to the function declaration just below.
*/
function add(a, b) {
  /*
   Attached to the function body because it is the first comment block.
   */
  return a + b // Attached to the return statement on its left
  // Trailing comment attached as such to the function body
}
// Trailing comment attached as such to the program body