@cparra/apex-reflection 0.1.1-alpha.9 → 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# 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.
+
+The Dart source code is transpiled to JS by `dart2js` through the default [grinder](https://pub.dev/packages/grinder)
+workflow within `tool/grind.dart`.
+
+To generate the JS files first set up `grinder` locally by following that package's instructions through its pub.dev
+listing, and then you can simply run `grind`. That build takes care of combining the output with `preamble/preamble.js`
+to achieve compatibility with Node.js. The resulting file is `js/apex-reflection-node/out.js`.
+
+### Tests
+
+Both the Dart source code and the JS output must be tested.
+
+The Dart tests live in the `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 `js/apex-reflection-node/__tests__`. These are end-to-end tests that ensure that the transpiled JS
+code is working as intended.
+
+### 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
+
+```
+pub run build_runner build
+```
+
+### Parsing
+
+The parsing algorithm relies on using ANTLR4 and its Dart target. Currently `dart2js` is not able to transpile the
+source from the `antrl4` library hosted in pub.dev, so we rely on a local copy that fixes the transpilation issues,
+which lives in `lib/antrl4-4.9.2`.
+
+To generate the Antlr4 Apex output run:
+
+```
+antlr4 -Dlanguage=Dart lib/src/antlr/grammars/apex/ApexLexer.g4 lib/src/antlr/grammars/apex/ApexParser.g4 -o lib/src/antlr/lib/apex/
+```
+
+To generate the Antlr4 Apexdoc output run:
+
+```
+antlr4 -Dlanguage=Dart lib/src/antlr/grammars/apexdoc/ApexdocLexer.g4 lib/src/antlr/grammars/apexdoc/ApexdocParser.g4 -o lib/src/antlr/lib/apexdoc/
+```
+
+## Typescript
+
+This library provides its own TS type definition.

package/__tests__/end-to-end.test.ts

@@ -3,7 +3,7 @@ import {ClassMirror, InterfaceMirror, reflect} from '../index';
 describe('Enum Reflection', () => {
   test('Simple, single line declaration', () => {
     const enumBody = 'enum MyEnumName {}';
-    const result = reflect(enumBody);
+    const result = reflect(enumBody).typeMirror;
     expect(result.type_name).toBe('enum');
     expect(result.name).toBe('MyEnumName');
   });
@@ -15,7 +15,7 @@ describe('Enum Reflection', () => {
       VALUE2
     }
     `;
-    const result = reflect(enumBody);
+    const result = reflect(enumBody).typeMirror;
     expect(result.type_name).toBe('enum');
     expect(result.name).toBe('MyEnumName');
   });
@@ -30,7 +30,7 @@ describe('Enum Reflection', () => {
       VALUE2
     }
     `;
-    const result = reflect(enumBody);
+    const result = reflect(enumBody).typeMirror;
     expect(result.docComment.description).toBe('My enum description');
   });
 });
@@ -38,20 +38,20 @@ describe('Enum Reflection', () => {
 describe('Interface Reflection', () => {
   test('Single line interface definition', () => {
     const interfaceBody = 'interface MyInterface{}';
-    const result = reflect(interfaceBody);
+    const result = reflect(interfaceBody).typeMirror;
     expect(result.type_name).toBe('interface');
     expect(result.name).toBe('MyInterface');
   });
 
   test('When no access modifier is defined it is private', () => {
     const interfaceBody = 'interface MyInterface{}';
-    const result = reflect(interfaceBody);
+    const result = reflect(interfaceBody).typeMirror;
     expect(result.access_modifier).toBe('private');
   });
 
   test('Can have access modifier', () => {
     const interfaceBody = 'public interface MyInterface{}';
-    const result = reflect(interfaceBody);
+    const result = reflect(interfaceBody).typeMirror;
     expect(result.access_modifier).toBe('public');
   });
 
@@ -99,20 +99,20 @@ describe('Interface Reflection', () => {
 describe('Class reflection', () => {
   test('Single line class definition', () => {
     const classBody = 'class MyClass{}';
-    const result = reflect(classBody);
+    const result = reflect(classBody).typeMirror;
     expect(result.type_name).toBe('class');
     expect(result.name).toBe('MyClass');
   });
 
   test('When no access modifier is defined it is private', () => {
     const classBody = 'class MyClass{}';
-    const result = reflect(classBody);
+    const result = reflect(classBody).typeMirror;
     expect(result.access_modifier).toBe('private');
   });
 
   test('Can have access modifier', () => {
     const interfaceBody = 'public class MyClass{}';
-    const result = reflect(interfaceBody);
+    const result = reflect(interfaceBody).typeMirror;
     expect(result.access_modifier).toBe('public');
   });
 

package/index.d.ts

@@ -1,4 +1,4 @@
-export declare function reflect(declarationBody: string): Type;
+export declare function reflect(declarationBody: string): ReflectionResult;
 export interface ParamAnnotation {
     bodyLines: string[];
     paramName: string;
@@ -70,6 +70,13 @@ export interface ConstructorMirror {
     parameters: ParameterMirror[];
     docComment?: DocComment;
 }
+export interface ReflectionResult {
+    typeMirror?: Type;
+    error?: ParsingError;
+}
+export interface ParsingError {
+    message: string;
+}
 declare type TypeName = 'class' | 'interface' | 'enum';
 export declare type Type = InterfaceMirror | ClassMirror | EnumMirror;
 export interface EnumMirror {

package/index.ts

@@ -1,7 +1,7 @@
 const lib = require('./out');
 
-export function reflect(declarationBody: string): Type {
-  return JSON.parse(lib.reflect(declarationBody)) as Type;
+export function reflect(declarationBody: string): ReflectionResult {
+  return JSON.parse(lib.reflect(declarationBody)) as ReflectionResult;
 }
 
 export interface ParamAnnotation {
@@ -87,6 +87,15 @@ export interface ConstructorMirror {
   docComment?: DocComment;
 }
 
+export interface ReflectionResult {
+  typeMirror?: Type;
+  error?: ParsingError;
+}
+
+export interface ParsingError {
+  message: string;
+}
+
 // Types
 
 type TypeName = 'class' | 'interface' | 'enum';
@@ -112,7 +121,6 @@ export interface InterfaceMirror {
 }
 
 export interface ClassMirror {
-  string;
   annotations: Annotation[];
   name: string;
   type_name: TypeName;