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

eslint-ast

v0.4.0

Published

The Extensible Type Definition of ESLint AST

Downloads

8

Readme

TypeScript Types for ESLint AST

npm version Downloads/month Build Status Dependency Status

This package provides TypeScript types for ESLint AST and the utilities to extend the AST types.

💿 Installation

Use npm or a compatible tool.

$ npm install eslint-ast

📖 Usage

■ Using types

There are several type definition files. Those files exports AST node types.

// The latest snapshot. Currently this is ES2021.
import * as latest from "eslint-ast" // or `eslint-ast/latest`

// The living standard, contains the proposals that have arrived at Stage 4.
// This types will be updated in minor releases.
import * as esNext from "eslint-ast/esnext"

// It contains the proposals that have arrived at Stage 3.
// This types will be updated in minor releases.
import * as experimental from "eslint-ast/experimental"

// The specific snapshots.
import * as es2021 from "eslint-ast/es2021"
import * as es2020 from "eslint-ast/es2020"
import * as es2019 from "eslint-ast/es2019"
import * as es2018 from "eslint-ast/es2018"
import * as es2017 from "eslint-ast/es2017"
import * as es2016 from "eslint-ast/es2016"
import * as es2015 from "eslint-ast/es2015"
import * as es5 from "eslint-ast/es5"

■ Defining your own AST

This package provides the utilities to define your own AST types.

  1. Declare the AST definition.
  2. Convert the AST definition to the AST types.
import { AST, NodeRef } from "eslint-ast/util"

// Declare the AST definition.
// This has three properties: `nodes`, `aliases`, and `commonProperties`.
interface MyDefinition {
    // Each node's definition.
    nodes: {
        Program: {
            // `NodeRef< node-name-or-alias >` will be replaced by actual node type later.
            expression: NodeRef<"Expression">
        }
        ConstantValue: {
            value: number
        }
        BinaryExpression: {
            operator: "+" | "-" | "*" | "/"
            left: NodeRef<"Expression">
            right: NodeRef<"Expression">
        }
    }

    // Alias definitions to use `NodeRef`.
    aliases: {
        Expression: "ConstantValue" | "BinaryExpression"
    }

    // You can define common properties for every node.
    // The `parent` and `type` properties are automatically defined.
    commonProperties: {
        range: readonly [number, number]
    }
}

// Convert the AST definition to AST types.
type MyAST = AST<MyDefinition>

// Every types is in the properties of `MyAST`.
type Program = MyAST["Program"] //= { type: "Program"
                                //    parent: null | undefined
                                //    expression: MyAST["Expression"]
                                //    range: readonly [number, number] }

type ConstantValue = MyAST["ConstantValue"] //= { type: "ConstantValue"
                                            //    parent: MyAST["Program"] | MyAST["BinaryExpression"]
                                            //    value: number
                                            //    range: readonly [number, number] }

type BinaryExpression = MyAST["BinaryExpression"] //= { type: "BinaryExpression"
                                                  //    parent: MyAST["Program"] | MyAST["BinaryExpression"]
                                                  //    operator: "+" | "-" | "*" | "/"
                                                  //    left: MyAST["Expression"]
                                                  //    right: MyAST["Expression"]
                                                  //    range: readonly [number, number] }

type Expression = MyAST["Expression"] //= MyAST["ConstantValue"] | MyAST["BinaryExpression"]

■ Extending existing AST

This package provides the utilities to define your own AST types as extended from other existing AST definition.

  1. Declare the differential of AST definition.
  2. Merge the differential and an existing AST definition.
  3. Convert the AST definition to the AST types.
import { Definition as ES2019Definition } from "eslint-ast/es2019-definition"
import { AST, Extends, NodeRef } from "eslint-ast/util"

// Declare the differential of AST definition.
interface BigInt {
    nodes: {
        // Adding a new property into existing node types.
        BooleanLiteral: {
            bigint: undefined
        }
        NullLiteral: {
            bigint: undefined
        }
        NumberLiteral: {
            bigint: undefined
        }
        RegExpLiteral: {
            bigint: undefined
        }
        StringLiteral: {
            bigint: undefined
        }

        // Adding a new node.
        BigIntLiteral: {
            type: "Literal"
            value: bigint | null
            bigint: string
            regex: undefined
            raw: string
        }
    }

    aliases: {
        // Adding the new node into existing aliases.
        Expression: "BigIntLiteral"
        StaticPropertyKey: "BigIntLiteral"
    }
}

// Merge the differential and an existing AST definition.
// I'd like to recommend to use `interface` for readability in VSCode popups.
interface MyDefinition extends Extends<ES2019Definition, BigInt> {}

// Convert the AST definition to the AST types.
type MyAST = AST<MyDefinition>

📰 Release Notes

See GitHub releases.

🚥 Semantic Versioning Policy

If the type of libraries is updated, it causes compile errors in userland in most cases. Therefore, this package declare semantic versioning policy.

Major

The major version bump allows any breaking changes. For example, the following things can happen:

  • Changes exposed files.
  • Changes existing types.
  • Changes the API of eslint-ast/util.
  • Changes the minimum supported TypeScript version.
  • etc...

In particular, changing eslint-ast/latest requires a major bump.

Minor

The minor version bump allows any breaking changes only in eslint-ast/esnext, eslint-ast/esnext-definition, eslint-ast/experimental, eslint-ast/experimental-definition, and eslint-ast/lib/. It doesn't change the types in the other files.

It happens when new proposals arrived at Stage 4 and ESTree was updated.

Patch

The minor version bump allows any breaking changes only in eslint-ast/esnext, eslint-ast/esnext-definition, eslint-ast/experimental, eslint-ast/experimental-definition, and eslint-ast/lib/. It doesn't change the types in the other files.

It happens when bugs found in new types.

❤️ Contributing

Contributing is welcome. Use GitHub issues and pull requests.

Development tools

  • npm test runs tests.
  • npm run build compiles codebase and makes dist/ directory.
  • npm run update-ast updates es*.ts files by the content of es*-definition.ts files.
  • npm version <major|minor|patch> bump a new version and releases it.