# @cparra/apex-reflection

> Provides tools for reflecting Apex code, the language used in Salesforce development.

Latest version **4.0.0** (published 2026-07-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install @cparra/apex-reflection
pnpm add @cparra/apex-reflection
yarn add @cparra/apex-reflection
bun add @cparra/apex-reflection
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-07-05 |
| First published | 2021-09-27 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=22.0.0 |
| Dependencies | 0 |
| Unpacked size | 159.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cesar Parra |
| Maintainers | cparra |
| Keywords | apex, salesforce, reflection, apex-docs, apexdocs, documentation |

## Links

- npm: https://www.npmjs.com/package/@cparra/apex-reflection
- npm.io page: https://npm.io/package/@cparra/apex-reflection

## Alternatives

- [@cantoo/pdf-lib](https://npm.io/package/@cantoo/pdf-lib.md) — 297.9K weekly downloads
- [datatables.net-buttons](https://npm.io/package/datatables.net-buttons.md) — 200.1K weekly downloads
- [@ckeditor/ckeditor5-export-pdf](https://npm.io/package/@ckeditor/ckeditor5-export-pdf.md) — 167.0K weekly downloads
- [scanbot-web-sdk](https://npm.io/package/scanbot-web-sdk.md) — 15.0K weekly downloads
- [@syncfusion/ej2-angular-pdfviewer](https://npm.io/package/@syncfusion/ej2-angular-pdfviewer.md) — 8.8K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2026-07-05
- 4.0.0-beta.6 (beta) — 2026-07-05
- 3.0.0-dev.20260614084225 (dev) — 2026-06-14
- 2.17.0-alpha.0 (alpha) — 2025-01-18
- 4.0.0-beta.5 — 2026-07-04
- 4.0.0-beta.4 — 2026-07-04
- 4.0.0-beta.3 — 2026-07-04
- 4.0.0-beta.2 — 2026-07-04
- 4.0.0-beta.1 — 2026-07-04
- 3.1.0 — 2026-06-24
- 3.0.0 — 2026-06-14
- 2.24.4 — 2026-04-16
- 2.24.3 — 2026-04-08
- 2.24.0 — 2026-03-12
- 2.23.12 — 2026-01-12
- … 114 more at https://npm.io/package/@cparra/apex-reflection/versions

## README

# Apex Reflection

Provides basic reflection for the Apex programming language.

## Installation

```
npm i @cparra/apex-reflection
```

## Usage

This library exposes a single function that handles parsing the body of an Apex top level type (class, interface, or
enum) and returns the result.

```typescript
import { reflect } from "@cparra/apex-reflection";

const classBody = "public with sharing class ExampleClass {}";
const response = reflect(classBody);
```

If you wish to parse an Apex type that comes from a file, you can read the file contents and use that as the source to
reflect

```typescript
import * as fs from 'fs';
import {reflect} from '@cparra/apex-reflection';

const path = './MyClass.cls';
const rawFile = fs.readFileSync(path);
const response = reflect(rawFile.toString());
```

The `reflect` function returns a `ReflectionResult` which contains either the results of the parsed `Type`
(which will either be a `ClassMirror`, an `InterfaceMirror`, or an `EnumMirror`) or a `ParsingError` if the passed in
body was not parsed successfully, with a message indicating where the error occurred.

## Contributing

Even though this library is exposed as a Node.js library, the project's source code is written in Dart. The source can
be found in the `lib/src` directory of the repository.

This package ships the Dart code compiled to a WebAssembly module (`dist/node.wasm`) together with its JS loader
(`dist/node.mjs`), loaded lazily by the thin TypeScript wrapper in `index.mts`. Node.js 22 or newer is required (the
module uses WasmGC). To rebuild the module after changing the Dart source, run from the repository root:

```shell
dart compile wasm lib/src/node/node.dart -o js/node.wasm
```

`npm run build` compiles the TypeScript wrapper and copies the wasm module and its loader into `dist/`.

### Tests

Both the Dart source code and the packaged WebAssembly module must be tested.

The Dart tests live in the repository's `test` directory. The Dart source code must have unit tests testing each
individual Dart file as well as end-to-end tests that verify the overall parsing functionality.

The JS tests live in `__tests__`. These are end-to-end tests that run against the built package (`dist/`), so they
also guard against publishing a stale WebAssembly artifact. Run them with `npm test`.

### JSON serialization

The reflection operation outputs a JSON representation of the Apex type, which is then deserialized on the JS side to
return typed objects.

Serialization is handled through the [json_serializable](https://pub.dev/packages/json_serializable) package, which
helps automatically create the round-trip code for serialization and de-serialization.

When changing any of the model classes with serialization support, to re-build the serialization code run

```shell
dart run build_runner build
```

### Parsing

Parsing is implemented with handwritten [petitparser](https://pub.dev/packages/petitparser) grammars. 
The Apex grammar parses only the declaration structure needed for reflection (bodies are skipped as
balanced blocks), and the Apexdoc grammar is composed into it, so doc comments are parsed in the same single pass. See
the repository README for details.

## Typescript

This library provides its own TS type definition.

---
_Source: https://npm.io/package/@cparra/apex-reflection · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._