Parser for Salesforce Apex (including triggers and inline SOQL/SOSL). This is based on an ANTLR4 grammar, see antlr/BaseApexParser.g4. Currently packaged for Java and JavaScript/TypeScript targets.

The packages include ANTLR4 generated types plus optional extras for convenience. The TypeScript package exports type aliases for ANTLR types, while both packages have abstractions like ApexParserFactory and ApexErrorListener. There are minimal examples below and in the test classes.

<dependency>
    <groupId>io.github.apex-dev-tools</groupId>
    <artifactId>apex-parser</artifactId>
    <version><!-- version --></version>
</dependency>

npm i @apexdevtools/apex-parser

The npm package ships multiple JavaScript outputs:

• ESM for modern Node and bundlers, selected by import.
• CommonJS for require.
• A browser ESM bundle, selected by browser-aware bundlers.
• TypeScript declarations for the root package and exported subpaths.

These are exposed through the package exports map, so most consumers should import from the package name rather than from dist paths:

import { ApexParserFactory } from "@apexdevtools/apex-parser";

CommonJS consumers can use require:

const { ApexParserFactory } = require("@apexdevtools/apex-parser");

The browser bundle includes the parser APIs, but excludes Node-only file checking helpers such as check and checkProject.

ApexParser entry points to access tree:

• compilationUnit(), a class file.
• triggerUnit(), a trigger file.
• anonymousUnit(), an apex script file.
• query(), a raw SOQL query.

import {
  ApexParserBaseListener,
  ApexParserBaseVisitor,
  ApexParseTreeWalker,
  ApexParserFactory,
} from "@apexdevtools/apex-parser";

const parser = ApexParserFactory.createParser("public class Hello {}");

/*
 * Use a visitor. Return value and manual control.
 */
class Visitor extends ApexParserBaseVisitor<any> {}

const visitor = new Visitor();
visitor.visit(parser.compilationUnit());


/*
 * Or walk with listener. Enter/exit operations - for whole tree.
 */
class Listener extends ApexParserBaseListener {}

const listener = new Listener();
ApexParseTreeWalker.DEFAULT.walk(listener, parser.compilationUnit());

Lexer errors (e.g. invalid string escape sequences) are only reported to listeners attached to the lexer, while parser errors are only reported to listeners attached to the parser. To capture both from a single listener, use createLexerAndParser, which wires the listener to both:

import { ApexParserFactory, ApexErrorListener } from "@apexdevtools/apex-parser";

class MyListener extends ApexErrorListener {
  apexSyntaxError(line: number, column: number, msg: string): void {
    console.log(`${line}:${column} ${msg}`);
  }
}

const { parser } = ApexParserFactory.createLexerAndParser(source, new MyListener());
parser.compilationUnit();

The Java API is equivalent:

ApexErrorListener listener = new MyListener();
LexerAndParser pair = ApexParserFactory.createLexerAndParser(
  CharStreams.fromString(source), listener);
pair.getParser().compilationUnit();

SOSL FIND uses ' as a quoting character when embedded in Apex, in the API braces are used:

Find {something} RETURNING Account

To parse the API format there is an alternative parser rule, soslLiteralAlt, that you can use instead of soslLiteral. See SOSLParserTest for some examples of how these differ.

• JDK 11+ (for ANTLR tool)
• Maven
• Node.js ^20.19.0, ^22.13.0, or >=24

The outer package contains scripts to build both distributions:

# Run once - prepare for dev (installs deps, runs antlr gen)
npm run init

# Run antlr gen, compile and test
npm run build

Or you can setup and later build each distribution separately:

npm run init:npm
npm run build:npm

npm run init:jvm
npm run build:jvm

More options for testing:

# From ./npm
npm run build
npm test
# File and test name regex filtering
npm test -- ApexParserTest -t Expression

# From ./jvm
mvn test

The system tests use a collection of sample projects located in the apex-samples repository. Follow the README instructions in apex-samples to checkout the submodules at the version tag used by the build workflow. Both packages must be built beforehand, as the js system test spawns the jar as well.

To run the tests:

# Set SAMPLES env var to samples repo location
export SAMPLES=<abs path to apex-samples>

# From root dir
npm run build
npm run systest

System test failures relating to the snapshots may highlight regressions. Though if an error is expected or the samples have changed, instead use npm run systest:update to update the snapshots, then commit the changes.

All the source code included uses a 3-clause BSD license. The only third-party component included is the Apex Antlr4 grammar originally from Tooling-force.com, although this version used is now markedly different from the original.