Acorn Loose Parser

Common errors

• TypeError: Cannot read properties of undefined (reading 'type') (or similar property access error)

  cause A downstream AST processing tool or custom traversal logic expects a fully valid ESTree structure but encounters dummy nodes or partially formed nodes generated by `acorn-loose`'s error recovery, which lack expected properties.
  fix Before accessing properties, validate nodes using `isDummy(node)` or implement more robust checks for node existence and expected structure. Be prepared for malformed subtrees resulting from error recovery.

• SyntaxError: Unexpected token (X:Y)

  cause Attempting to parse malformed JavaScript code directly with the strict `acorn` parser (or another strict parser) instead of leveraging the error-tolerant `acorn-loose`.
  fix Implement a fallback mechanism: first try parsing with `acorn.parse()`, and if it throws a `SyntaxError`, then re-attempt parsing the same code with `acorn-loose.parse()`.

• ModuleNotFoundError: Cannot find module 'acorn-loose' or 'acorn'

  cause The package (or its dependency) is not installed, or there's a mismatch in import syntax (e.g., using CommonJS `require` in an ESM context or vice-versa without proper tooling/configuration).
  fix Ensure `acorn-loose` and `acorn` are installed (`npm install acorn-loose acorn`). Verify your `tsconfig.json` (for TypeScript) or `package.json` `type` field and adjust import statements accordingly (ESM `import` or CommonJS `require`).

Warnings

• gotcha acorn-loose may mis-parse valid but weirdly indented files due to its error-recovery mechanisms treating whitespace as significant in some contexts. This can lead to an incorrect AST for otherwise valid code.
  Fix: Always attempt to parse with the strict `acorn` parser first for known valid code, and only fall back to `acorn-loose` for error recovery when a `SyntaxError` is encountered.
• gotcha The parser inserts 'dummy' identifier nodes with the name "✖" as placeholders for syntactically incomprehensible parts of the input. Downstream tools must be designed to explicitly handle or skip these placeholder nodes.
  Fix: Utilize the `isDummy(node)` utility function to identify and gracefully handle or skip these placeholder nodes during AST traversal or processing to prevent unexpected errors.
• gotcha acorn-loose relies on the `acorn` package for its tokenizer. Mismatched major versions between `acorn` and `acorn-loose` could lead to unexpected parsing behavior or runtime errors.
  Fix: Ensure that your installed versions of `acorn` and `acorn-loose` are compatible. Ideally, install both as peer dependencies or use versions released in close proximity to avoid conflicts.

Install

• npm install acorn-loose npm
• yarn add acorn-loose yarn
• pnpm add acorn-loose pnpm

Imports

• parse
  wrong:

  const acornLoose = require('acorn-loose'); const ast = acornLoose.parse(...)

  correct:

  import { parse } from 'acorn-loose'

  For ESM environments, prefer named import. CommonJS users can access `parse` as a method on the default export (`acornLoose.parse`).
• LooseParser
  wrong:

  const { Parser } = require('acorn-loose')

  correct:

  import { LooseParser } from 'acorn-loose'

  Use the named export `LooseParser` to extend its functionality with plugins via `LooseParser.extend()`. Available in both ESM and CJS.
• isDummy
  wrong:

  acornLoose.isDummy(node)

  correct:

  import { isDummy } from 'acorn-loose'

  A utility function to check if an AST node was inserted as a placeholder by the error-tolerant parser. Available as a named export in ESM and CJS.

Quickstart

Demonstrates parsing invalid JavaScript code with `acorn-loose` after a strict parse failure, identifying dummy nodes, and regenerating potentially malformed code using `astring`.

import { parse, isDummy } from 'acorn-loose';
import { parse as strictParse } from 'acorn'; // Recommended peer dependency for strict parsing
import { generate } from 'astring'; // A common AST utility for code generation

const invalidCode = `
  function example(arg1, arg2,) { // Trailing comma in params is okay in ES2017+
    if (true { // Missing parenthesis and closing brace
      return "hello";
  `;

let ast;
try {
  // Always attempt strict parsing first for valid code
  strictParse(invalidCode, { ecmaVersion: 2020, sourceType: 'module' });
} catch (e: any) {
  console.log('Strict parser failed as expected:', e.message.split('\n')[0]);
  // Fallback to acorn-loose for error-tolerant parsing of malformed code
  ast = parse(invalidCode, { ecmaVersion: 2020, sourceType: 'module' });
  console.log('AST generated by acorn-loose (first few nodes):', JSON.stringify(ast.body.slice(0, 2), null, 2));

  let dummyCount = 0;
  // Simple traversal to find dummy nodes (a dedicated AST walker like acorn.walk is recommended for full traversal)
  function traverse(node: any) {
    if (node && typeof node === 'object') {
      if (isDummy(node)) {
        dummyCount++;
      }
      for (const key in node) {
        // Avoid circular references and properties that may not contain nodes (e.g., 'parent')
        if (Object.prototype.hasOwnProperty.call(node, key) && key !== 'parent' && typeof node[key] === 'object') {
          traverse(node[key]);
        }
      }
    }
  }
  traverse(ast);
  console.log(`Found ${dummyCount} dummy nodes in the AST.`);
  console.log('Attempting to regenerate code (may be malformed due to error recovery):\n', generate(ast));
}