is-reference

library3.0.3jsnpmunverified

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.

serialization

npm install is-reference

github ↗package ↗

INSTALL

IMPORT

SIG · IS-REFERENCE

is-reference

serializationjavascriptv3.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

is_reference

✓ import is_reference from 'is-reference';

✗ 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)

✓ const is_reference = require('is-reference');

✗ import is_reference from 'is-reference'; // In CJS-only environments

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.

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

Debug

Known issues

breakingVersion 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()`.

affects: >=3.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaIt'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`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: is_reference is not a function

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`)

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.

Upgrade

Version history

3.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/Rich-Harris/is-reference ↗

packagehttps://www.npmjs.com/package/is-reference ↗