is-reference AST Node Identification

3.0.3 · active · verified Sun Apr 19

is-reference is a focused utility designed to accurately determine whether a given JavaScript Abstract Syntax Tree (AST) node, specifically an `Identifier`, constitutes a 'reference' in the context of scope analysis. This is crucial for tools like bundlers, minifiers, and linters that need to differentiate between identifiers that refer to a variable binding (e.g., `console.log(foo)`) and those that are property names (e.g., `obj.foo`). The package is currently at version 3.0.3 and appears to follow an infrequent release cadence, driven by the needs of projects like Rollup. Its primary differentiator is its precise definition of a 'reference' within the ESTree specification, distinguishing it from simply being an `Identifier` node. It ships with TypeScript types, ensuring type-safe usage in modern JavaScript environments.

Common errors

```
TypeError: is_reference is not a function
```
cause This error occurs when `is_reference` is incorrectly imported as a named export (e.g., `import { is_reference } from 'is-reference';`) or when a CommonJS `require()` call fails to resolve the default export correctly, typically in an ESM-first package.

fix Ensure you are using the correct default import syntax: `import is_reference from 'is-reference';`. If in a CommonJS environment, verify that your tooling or Node.js version supports ESM interop for default exports, or consider bundling.
```
TypeError: Cannot read properties of undefined (reading 'type') (or similar error related to accessing properties of `parent`)
```
cause This indicates that the `parent` argument passed to `is_reference` was `undefined`, `null`, or not a valid AST node object, preventing the function from inspecting the parent's properties to determine the context of the child node.

fix Always pass a valid AST `parent` node to `is_reference(node, parent)`. If you are at the root of the AST (e.g., a `Program` node), its `parent` would typically be `null` or `undefined`, and `is_reference` expects to handle this case, but for any child node, a correct parent must be provided by your AST traversal logic.

Warnings

breaking Version 3.0.0 and above are primarily distributed as ES Modules (ESM). This means `require()` syntax may not work directly or correctly in Node.js environments without specific configuration (e.g., `type: 'module'` in package.json for consumer projects) or a transpilation step. Previous major versions might have supported CommonJS more directly.
Fix: Ensure your project is configured for ES Modules (e.g., `"type": "module"` in your `package.json`). Use `import is_reference from 'is-reference';` and adjust your build or runtime environment to handle ESM correctly. For older CJS environments, consider bundling or using dynamic `import()`.
gotcha The `is_reference` function strictly requires both the AST `node` and its `parent` node as arguments to provide context. Passing only the `node` or an incorrect `parent` will lead to incorrect results or runtime errors, as the parent's type and structure are crucial for accurate reference determination.
Fix: Always provide both the `node` and its `parent` to the `is_reference` function: `is_reference(node, parent)`. If using an AST walker, ensure it provides the parent context, such as `estree-walker`'s `enter(node, parent)` callback.
gotcha It's a common misconception that every `Identifier` AST node represents a 'reference'. `is-reference` specifically distinguishes identifiers that *refer* to a variable binding (e.g., `x` in `let y = x;`) from those that are purely property keys (e.g., `prop` in `obj.prop`) or other non-referencing syntax. It's designed for scope analysis, not general identifier finding.
Fix: Understand the precise definition of a 'reference' as documented by `is-reference`. If you need to find all `Identifier` nodes regardless of their referencing status, you should directly check `node.type === 'Identifier'` rather than relying solely on `is_reference`.

Install

npm install is-reference npm
yarn add is-reference yarn
pnpm add is-reference pnpm

Imports

is_reference
wrong:
```
import { is_reference } from 'is-reference';
```
correct:
```
import is_reference from 'is-reference';
```
The `is_reference` function is a default export. Attempting to destructure it as a named import will result in `undefined`.
is_reference (CommonJS)
wrong:
```
import is_reference from 'is-reference'; // In CJS-only environments
```
correct:
```
const is_reference = require('is-reference');
```
While CommonJS `require` might work via Node.js's ESM interop for default exports, the package is primarily designed and published as an ES Module since v3. Direct ESM `import` is recommended for modern projects.

Quickstart

Demonstrates how to parse an AST using Acorn, walk it with estree-walker, and identify 'reference' nodes using `is-reference`, distinguishing them from mere identifier occurrences within the AST.

import { parse } from 'acorn';
import { walk } from 'estree-walker';
import is_reference from 'is-reference';

const identifiers = [];
const references = [];

// Using ecmaVersion to support modern syntax for the AST parsing
const ast = parse(`
  const x = 1;
  let y = x + obj.prop;
  function foo(param) { console.log(param, y); }
  foo(x);
`, { ecmaVersion: 2020 });

walk(ast, {
	enter(node, parent) {
		if (node.type === 'Identifier') identifiers.push(node);
		if (is_reference(node, parent)) references.push(node);
	}
});

console.log('All Identifiers:', identifiers.map(node => node.name).join(', '));
// Expected: All Identifiers: x, y, x, obj, prop, foo, param, console, log, param, y, foo, x

console.log('References:', references.map(node => node.name).join(', '));
// Expected: References: x, y, x, obj, foo, param, console, log, param, y, foo, x

view raw JSON →