estree-util-scope

estree utility to check what’s defined in a scope.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • Scope
  • Visitors
  • createVisitors()
• Examples
  • Example: just the top scope
• Compatibility
• Related
• Security
• Contribute
• License

What is this?

This package is a utility that tracks what’s defined in a scope.

When should I use this?

If you are walking an estree already and want to find out what’s defined, use this. If you have more complex scoping needs, see eslint-scope.

Install

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

npm install estree-util-scope

In Deno with esm.sh:

import {createVisitors} from 'https://esm.sh/estree-util-scope@1'

In browsers with esm.sh:

<script type="module">
  import {createVisitors} from 'https://esm.sh/estree-util-scope@1?bundle'
</script>

Use

Say we have the following example.js:

/**
 * @import {Program} from 'estree'
 */

import {Parser} from 'acorn'
import {createVisitors} from 'estree-util-scope'
import {walk} from 'estree-walker'

const tree = /** @type {Program} */ (
  Parser.parse('import {a} from "b"; const c = 1', {
    ecmaVersion: 'latest',
    sourceType: 'module'
  })
)
const visitors = createVisitors()

walk(tree, {enter: visitors.enter, leave: visitors.exit})

console.log(visitors.scopes.at(-1))

…now running node example.js yields:

{ block: false, defined: [ 'a', 'c' ] }

API

Scope

Scope.

Fields

• block (boolean) — whether this is a block scope or not; blocks are things made by for and try and if; non-blocks are functions and the top-level scope
• defined (Array<string>) — identifiers that are defined in this scope

Visitors

State to track what’s defined; contains enter, exit callbacks you must call and scopes.

Fields

• enter ((node: Node) => undefined) — callback you must call when entering a node
• exit ((node: Node) => undefined) — callback you must call when exiting (leaving) a node
• scopes ([topLevel: Scope, ...rest: Scope[]]) — list of scopes; the first scope is the top-level scope; the last scope is the current scope

createVisitors()

Create state to track what’s defined.

Parameters

There are no parameters.

Returns

State (Visitors).

Examples

Example: just the top scope

Sometimes, you only care about a top-scope. Or otherwise want to skip a node. How to do this depends on how you walk the tree. With estree-walker, you can skip by calling this.skip.

/**
 * @import {Program} from 'estree'
 */

import {Parser} from 'acorn'
import {createVisitors} from 'estree-util-scope'
import {walk} from 'estree-walker'

const tree = /** @type {Program} */ (
  Parser.parse(
    'function a(b) { var c = 1; if (d) { var e = 2 } }; if (f) { var g = 2 }',
    {ecmaVersion: 'latest'}
  )
)
const visitors = createVisitors()

walk(tree, {
  enter(node) {
    visitors.enter(node)

    if (
      node.type === 'ArrowFunctionExpression' ||
      node.type === 'FunctionDeclaration' ||
      node.type === 'FunctionExpression'
    ) {
      this.skip()
      visitors.exit(node) // Call the exit handler manually.
    }
  },
  leave: visitors.exit
})

console.log(visitors.scopes.at(-1))

…yields:

{ block: false, defined: [ 'a', 'g' ] }

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-scope@1, compatible with Node.js 16.

Related

Security

This package is safe.

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