{"id":14635,"library":"is-reference","title":"is-reference AST Node Identification","description":"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.","status":"active","version":"3.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/Rich-Harris/is-reference","tags":["javascript","ast","estree","acorn","typescript"],"install":[{"cmd":"npm install is-reference","lang":"bash","label":"npm"},{"cmd":"yarn add is-reference","lang":"bash","label":"yarn"},{"cmd":"pnpm add is-reference","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `is_reference` function is a default export. Attempting to destructure it as a named import will result in `undefined`.","wrong":"import { is_reference } from 'is-reference';","symbol":"is_reference","correct":"import is_reference from 'is-reference';"},{"note":"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.","wrong":"import is_reference from 'is-reference'; // In CJS-only environments","symbol":"is_reference (CommonJS)","correct":"const is_reference = require('is-reference');"}],"quickstart":{"code":"import { parse } from 'acorn';\nimport { walk } from 'estree-walker';\nimport is_reference from 'is-reference';\n\nconst identifiers = [];\nconst references = [];\n\n// Using ecmaVersion to support modern syntax for the AST parsing\nconst ast = parse(`\n  const x = 1;\n  let y = x + obj.prop;\n  function foo(param) { console.log(param, y); }\n  foo(x);\n`, { ecmaVersion: 2020 });\n\nwalk(ast, {\n\tenter(node, parent) {\n\t\tif (node.type === 'Identifier') identifiers.push(node);\n\t\tif (is_reference(node, parent)) references.push(node);\n\t}\n});\n\nconsole.log('All Identifiers:', identifiers.map(node => node.name).join(', '));\n// Expected: All Identifiers: x, y, x, obj, prop, foo, param, console, log, param, y, foo, x\n\nconsole.log('References:', references.map(node => node.name).join(', '));\n// Expected: References: x, y, x, obj, foo, param, console, log, param, y, foo, x\n","lang":"typescript","description":"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."},"warnings":[{"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()`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: is_reference is not a function"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'type') (or similar error related to accessing properties of `parent`)"}],"ecosystem":"npm"}