ANTLR4 TypeScript Runtime (antlr4ng)

3.0.16 verified Sun Apr 19 auth: no javascript

antlr4ng is an alternative, TypeScript-first runtime for ANTLR4 grammars, specifically designed to be used with the `antlr-ng` parser generation tool. Currently stable at version `3.0.16`, it receives frequent point releases addressing bugs and introducing minor enhancements. Unlike the original ANTLR4 JavaScript runtime, `antlr4ng` operates identically across Node.js and browser environments and is built with strict TypeScript nullability checks. It requires an ES2022 (ES6) compatible runtime for features like static initialization blocks and private class fields. While implementing nearly all features of the Java ANTLR4 runtime, it notably omits the `UnbufferedCharStream` class. Developers migrating from other ANTLR4 JavaScript runtimes will need to adjust code for stricter null handling and renamed internal members.

Common errors

error 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.

error 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 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';

error 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

yarn add antlr4ng

pnpm add antlr4ng

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.");