JavaScript Identifier Regular Expression

Common errors

• TypeError: identifierRegex is not a function

  cause Attempting to use the `identifierRegex` function directly as a `RegExp` object without calling it first (e.g., `identifierRegex.test('foo')`). The function returns a RegExp instance.
  fix Call `identifierRegex()` to obtain the regular expression object: `identifierRegex().test('foo')`.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a CommonJS (CJS) environment without proper configuration (e.g., without `'type': 'module'` in `package.json` for Node.js).
  fix Ensure your project is configured as an ES module by adding `'type': 'module'` to your `package.json`, or use a bundler that transpiles ES modules to CJS for older environments. This package requires Node.js >=18, which has robust ESM support.

• My regex isn't matching anything in a longer string (e.g., 'foo bar').

  cause The default `exact` option is `true`, meaning the regex tries to match the entire input string. `'foo bar'` is not a single, exact identifier.
  fix Set the `exact` option to `false` when you want to find identifiers within a larger string: `identifierRegex({ exact: false }).test('foo bar')`.

Warnings

• gotcha When running the regex against untrusted user input in a server context, it is strongly recommended to give the regex a timeout (e.g., using `super-regex`) to prevent potential Regular Expression Denial of Service (ReDoS) attacks. While the package maintainer does not consider ReDoS a direct vulnerability for this specific package, it's a critical security consideration for user-facing applications.
  Fix: Integrate with a regex timeout library like `super-regex` when processing untrusted input.
• gotcha The regex will NOT match properties of the global object like `globalThis`, `Infinity`, `NaN`, and `undefined` as valid identifiers. While these are JavaScript built-ins, the library's design choice is to exclude them from identifier matching, which might surprise users expecting a broader match.
  Fix: If you need to match these global properties specifically, you will need to augment the result of `identifierRegex()` with additional patterns or handle them separately.
• gotcha The default `exact` option for `identifierRegex()` is `true`. This means the regex will only match if the entire input string is a valid JavaScript identifier. If you intend to find or extract identifiers from within a larger string (e.g., `'foo bar'.match(identifierRegex())`), you must explicitly set `{ exact: false }`.
  Fix: Pass `{ exact: false }` to the `identifierRegex` function when matching substrings: `identifierRegex({ exact: false }).test('foo bar')`.

Install

• npm install identifier-regex npm
• yarn add identifier-regex yarn
• pnpm add identifier-regex pnpm

Imports

• identifierRegex
  wrong:

  const identifierRegex = require('identifier-regex');

  correct:

  import identifierRegex from 'identifier-regex';

  This package is primarily designed for ES modules. While CommonJS might work with transpilation, direct `require` is not the recommended or native approach since Node.js >=18 engine requirement.
• RegExp instance
  wrong:

  identifierRegex.test('foo');

  correct:

  const myIdentifierRegex = identifierRegex();

  The `identifierRegex` function *returns* a new `RegExp` instance each time it's called. You must call it to get the regex object to use `test()`, `match()`, etc.
• identifierRegex with options
  wrong:

  import { identifierRegex } from 'identifier-regex';

  correct:

  import identifierRegex from 'identifier-regex';
  const looseRegex = identifierRegex({ exact: false });

  The package exports a default function. Attempting a named import for `identifierRegex` will result in an error. Options are passed as an object to the function call.

Quickstart

Demonstrates importing the `identifierRegex` function, using it to test strings for identifier validity (including reserved words), and extracting identifiers from longer strings with the `exact: false` option, while also showing it returns a `RegExp` instance.

import identifierRegex from 'identifier-regex';

// Basic usage: testing if a string is a valid identifier
console.log("Is 'foo' a valid identifier?", identifierRegex().test('foo'));
//=> true

console.log("Is '1kg' a valid identifier?", identifierRegex().test('1kg'));
//=> false (Identifiers cannot start with a number)

console.log("Is 'await' a valid identifier?", identifierRegex().test('await'));
//=> false (Reserved word)

// Using 'exact: false' to find identifiers within a larger string
const textWithIdentifiers = 'function _myVar_($param1) { const $var2 = 1; }';
const identifiersInText = textWithIdentifiers.match(identifierRegex({ exact: false, global: true }));
console.log(`Identifiers found in "${textWithIdentifiers}":`, identifiersInText);
//=> ['_myVar_', '$param1', '$var2']

// Demonstrate that calling identifierRegex() returns a RegExp instance
const myRegexInstance = identifierRegex();
console.log('Type of returned value:', typeof myRegexInstance);
console.log('Is it a RegExp instance?', myRegexInstance instanceof RegExp);