ANTLR4 TypeScript Runtime (antlr4ng)

Common errors

• TS2339: Property '_ctx' does not exist on type 'Parser'. Did you mean 'context'?

  cause Accessing an old, renamed internal member of `Parser` or `Recognizer`.
  fix Replace `parser._ctx` with `parser.context`. Similarly, change `_errHandler` to `errorHandler`, `_input` to `inputStream`, and `_interp` to `interpreter`.

• TypeError: Class constructor CharStream cannot be invoked without 'new'

  cause Attempting to use `require()` for the `antlr4ng` package, which is an ESM-only library and relies on ES2022+ features, or incorrect CJS interop.
  fix Ensure your project is configured for ES Modules and use `import { CharStream } from 'antlr4ng';` instead of `const { CharStream } = require('antlr4ng');`.

• Error: Cannot find module './generated/ExpressionLexer'

  cause The import path for generated files is incorrect, or the `.js` extension is missing when running in an ESM Node.js environment.
  fix Verify the relative path to your `generated` folder. For ESM in Node.js, ensure the import statement includes the `.js` extension: `import { ExpressionLexer } from './generated/ExpressionLexer.js';`

• SyntaxError: Private field '#field' must be declared in an enclosing class

  cause Running `antlr4ng` in a JavaScript environment that does not support ES2022 (ES13) features, specifically private class fields (`#field`).
  fix Upgrade your Node.js runtime to version 16.x or newer, or ensure your build tools (e.g., Babel, TypeScript compiler) are configured to transpile to a target that supports ES2022 or higher.

Warnings

• breaking The `antlr4ng` runtime requires ES2022 (ES13) or newer JavaScript environments, utilizing features like static initialization blocks and private class fields (`#field`). Older JavaScript runtimes (e.g., Node.js < 16) will fail.
  Fix: Ensure your Node.js version is 16.x or higher, or configure your bundler/TypeScript compiler to target `ES2022` or higher.
• breaking Migration from other ANTLR4 JavaScript runtimes requires adjusting code due to `antlr4ng`'s stricter TypeScript nullability. Many previously implicitly nullable members are now explicitly typed as nullable, aligning with Java runtime behavior.
  Fix: Implement explicit null checks (`if (member !== null)`) or use TypeScript's non-null assertion operator (`member!`) where appropriate, prioritizing safety.
• breaking Several internal parser and recognizer member variables have been renamed for consistency with TypeScript conventions (e.g., `_ctx` to `context`, `_errHandler` to `errorHandler`, `_input` to `inputStream`, `_interp` to `interpreter`).
  Fix: Update references to these renamed members throughout your custom parser logic, error handlers, or visitor/listener implementations.
• gotcha This `antlr4ng` runtime is designed to be used with parsers generated by the `antlr-ng` tool. While it implements ANTLR4, direct compatibility with parsers generated by the original ANTLR4 JavaScript target might not be guaranteed due to numerous bug fixes and internal changes.
  Fix: Always use the `antlr-ng` tool to generate your lexer and parser files for optimal compatibility with the `antlr4ng` runtime.
• gotcha When importing generated lexer/parser/visitor files in an ESM Node.js environment, the `.js` extension must be explicitly included in the import path, even if the source file is `.ts`.
  Fix: Change `import { MyLexer } from './MyLexer';` to `import { MyLexer } from './MyLexer.js';` for generated files.

Install

• npm install antlr4ng npm
• yarn add antlr4ng yarn
• pnpm add antlr4ng pnpm

Imports

• CharStream
  wrong:

  const { CharStream } = require("antlr4ng");

  correct:

  import { CharStream } from "antlr4ng";

  The `antlr4ng` package is an ES Module (ESM) and requires an `import` statement. It mandates ES2022+ features for its internal implementation.
• CommonTokenStream
  wrong:

  const { CommonTokenStream } = require("antlr4ng");

  correct:

  import { CommonTokenStream } from "antlr4ng";

  Part of the core `antlr4ng` runtime for managing tokens from a lexer, typically used in conjunction with a `CharStream`.
• ExpressionLexer
  wrong:

  import { ExpressionLexer } from "antlr4ng";
  import { ExpressionLexer } from "./generated/ExpressionLexer";

  correct:

  import { ExpressionLexer } from "./generated/ExpressionLexer.js";

  Lexer, parser, and visitor classes are generated by the `antlr-ng` tool into user-defined paths. When using Node.js with ESM, the `.js` extension must be explicitly included in the import path.
• Parser
  wrong:

  const { Parser } = require("antlr4ng");

  correct:

  import { Parser } from "antlr4ng";

  The base class for generated parsers, often extended for custom logic. It follows ESM import rules and ES2022+ requirements.

Quickstart

Demonstrates parsing a simple arithmetic expression using generated lexer and parser, highlighting basic setup with `CharStream` and `CommonTokenStream` from `antlr4ng`.

import { CharStream, CommonTokenStream } from "antlr4ng";
import { ExpressionLexer } from "./generated/ExpressionLexer.js";
import { ExpressionParser } from "./generated/ExpressionParser.js";

const input = "1 + 2 * 3";
const inputStream = CharStream.fromString(input);
const lexer = new ExpressionLexer(inputStream);
const tokenStream = new CommonTokenStream(lexer);
const parser = new ExpressionParser(tokenStream);

// Optionally configure error handling or listeners
// parser.removeErrorListeners();
// parser.addErrorListener(new MyErrorListener());

const tree = parser.start();

// To demonstrate visitor usage (assuming MyVisitor is defined):
// import { ExpressionVisitor } from "./generated/ExpressionVisitor.js";
// import { AddContext } from "./generated/ExpressionParser.js"; // Example context type
//
// class MyVisitor extends ExpressionVisitor<number> {
//   public visitAdd = (ctx: AddContext): number => {
//     // Assuming visit is implemented for other rule contexts
//     return this.visit(ctx.expression(0)) + this.visit(ctx.expression(1));
//   };
//   // ... implement other visit methods
//   protected defaultResult(): number { return 0; }
//   protected aggregateResult(aggregate: number, nextResult: number): number { return nextResult; }
// }
// const result = new MyVisitor().visit(tree);
// console.log(`Parse tree successfully created. Visitor result: ${result}`);
console.log("Parse tree successfully created.");