@apexdevtools/apex-parser 5.0.0-beta.5 → 5.1.0-beta.1

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # apex-parser - Changelog
 
-## 5.0.0
+## 5.1.0-beta.1
+
+- Allow functions in `GROUP BY` clause of SOQL queries
+- Support Apex bind variables (`:expr`) in SOSL `WITH DIVISION` clause
+- Support fully-qualified enum values in switch `when` clauses, e.g. `when MyClass.MyEnum.VALUE`
+  - `whenLiteral` now matches `qualifiedName` in place of `id`, so bare enum values like `when VALUE` now parse as `WhenLiteral > qualifiedName > id` rather than `WhenLiteral > id` (AST shape change for tree-walking consumers)
+- Support multi-line string literals (Salesforce Summer '26), e.g. `String json = '''<NL>{...}<NL>''';`
+  - New `MultilineStringLiteral` token, accepted alongside `StringLiteral` in literal/SOQL/SOSL contexts.
+  - Body must start on a new line after the opening `'''`, matching platform behaviour. Malformed forms like `'''abc'''` continue to lex as legacy `StringLiteral` tokens (`''`, `'abc'`, `''`); apex-ls consumes this pattern to surface a targeted diagnostic (apex-ls#443).
+- Fix `npm run check` failing with `ERR_REQUIRE_ESM` on Node 20+ by switching the script from `require()` to dynamic `import()` (the package is `"type": "module"`).
+- Update npm package build output to publish separate ESM, CommonJS, browser, and TypeScript declaration artifacts through the package `exports` map.
+
+## 5.0.0 - 2026-04-21
 
 ## General
 

package/README.md

@@ -1,6 +1,6 @@
 # apex-parser
 
-Parser for Salesforce Apex (including Triggers & inline SOQL/SOQL). This is based on an [ANTLR4](https://www.antlr.org/) grammar, see [`antlr/BaseApexParser.g4`](./antlr/BaseApexParser.g4). Currently packaged for Java and JavaScript/TypeScript targets.
+Parser for Salesforce Apex (including triggers and inline SOQL/SOSL). This is based on an [ANTLR4](https://www.antlr.org/) grammar, see [`antlr/BaseApexParser.g4`](./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.
 
@@ -19,10 +19,30 @@ The packages include ANTLR4 generated types plus optional extras for convenience
 ### NPM
 
 ```sh
-# Optionally install `antlr4` to use runtime types
 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:
+
+```typescript
+import { ApexParserFactory } from "@apexdevtools/apex-parser";
+```
+
+CommonJS consumers can use `require`:
+
+```javascript
+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:
@@ -35,7 +55,12 @@ npm i @apexdevtools/apex-parser
 ### Explore Parse Tree (TypeScript)
 
 ```typescript
-import { ApexParserFactory, ApexParserBaseVisitor } from "@apexdevtools/apex-parser";
+import {
+  ApexParserBaseListener,
+  ApexParserBaseVisitor,
+  ApexParseTreeWalker,
+  ApexParserFactory,
+} from "@apexdevtools/apex-parser";
 
 const parser = ApexParserFactory.createParser("public class Hello {}");
 
@@ -57,6 +82,32 @@ 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:
+
+```typescript
+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:
+
+```java
+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:
@@ -73,7 +124,7 @@ To parse the API format there is an alternative parser rule, `soslLiteralAlt`, t
 
 - JDK 11+ (for ANTLR tool)
 - Maven
-- NodeJS LTS
+- Node.js ^20.19.0, ^22.13.0, or >=24
 
 ### Building