apex-parser

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.

The grammar aims to match the platform compiler. Where it deliberately does not, the difference is recorded in Differences From Salesforce Behaviour.

Installation

Maven

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

NPM

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.

Usage

ApexParser entry points to access tree:

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

Explore Parse Tree (TypeScript)

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());

Capturing syntax errors

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 quoting

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.

Development

Prerequisites

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

Building

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

Testing

Unit Tests

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

System Tests

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.

Source & Licenses

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.