@cparra/apex-reflection 0.1.1-alpha.8 → 1.1.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

@@ -0,0 +1,256 @@
+import {ClassMirror, InterfaceMirror, reflect} from '../index';
+
+describe('Enum Reflection', () => {
+  test('Simple, single line declaration', () => {
+    const enumBody = 'enum MyEnumName {}';
+    const result = reflect(enumBody).typeMirror;
+    expect(result.type_name).toBe('enum');
+    expect(result.name).toBe('MyEnumName');
+  });
+
+  test('Multi-line declaration with values', () => {
+    const enumBody = `
+    enum MyEnumName {
+      VALUE_1,
+      VALUE2
+    }
+    `;
+    const result = reflect(enumBody).typeMirror;
+    expect(result.type_name).toBe('enum');
+    expect(result.name).toBe('MyEnumName');
+  });
+
+  test('With doc comments', () => {
+    const enumBody = `
+    /**
+     * My enum description
+     */
+    enum MyEnumName {
+      VALUE_1,
+      VALUE2
+    }
+    `;
+    const result = reflect(enumBody).typeMirror;
+    expect(result.docComment.description).toBe('My enum description');
+  });
+});
+
+describe('Interface Reflection', () => {
+  test('Single line interface definition', () => {
+    const interfaceBody = 'interface MyInterface{}';
+    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).typeMirror;
+    expect(result.access_modifier).toBe('private');
+  });
+
+  test('Can have access modifier', () => {
+    const interfaceBody = 'public interface MyInterface{}';
+    const result = reflect(interfaceBody).typeMirror;
+    expect(result.access_modifier).toBe('public');
+  });
+
+  test('Can have a sharing modifier', () => {
+    const interfaceBody = 'public with sharing interface MyInterface{}';
+    const result = reflect(interfaceBody) as InterfaceMirror;
+    expect(result.sharingModifier).toBe('withSharing');
+  });
+
+  test('Can have methods', () => {
+    const interfaceBody = `
+      public with sharing interface MyInterface{
+        void method1();
+      }
+    `;
+    const result = reflect(interfaceBody) as InterfaceMirror;
+    expect(result.methods.length).toBe(1);
+    expect(result.methods[0].name).toBe('method1');
+  });
+
+  test('Can have extend other interfaces', () => {
+    const interfaceBody = `
+      public with sharing interface MyInterface extends Interface2 {
+        void method1();
+      }
+    `;
+    const result = reflect(interfaceBody) as InterfaceMirror;
+    expect(result.extended_interfaces.length).toBe(1);
+    expect(result.extended_interfaces[0]).toBe('Interface2');
+  });
+
+  test('Can have annotations', () => {
+    const interfaceBody = `
+      @NamespaceAccessible
+      public with sharing interface MyInterface{
+        void method1();
+      }
+    `;
+    const result = reflect(interfaceBody) as InterfaceMirror;
+    expect(result.annotations.length).toBe(1);
+    expect(result.annotations[0].name).toBe('namespaceaccessible');
+  });
+});
+
+describe('Class reflection', () => {
+  test('Single line class definition', () => {
+    const classBody = 'class MyClass{}';
+    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).typeMirror;
+    expect(result.access_modifier).toBe('private');
+  });
+
+  test('Can have access modifier', () => {
+    const interfaceBody = 'public class MyClass{}';
+    const result = reflect(interfaceBody).typeMirror;
+    expect(result.access_modifier).toBe('public');
+  });
+
+  test('Can have a sharing modifier', () => {
+    const classBody = 'public with sharing class MyClass{}';
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.sharingModifier).toBe('withSharing');
+  });
+
+  test('Can have a class modifier', () => {
+    const classBody = 'public with sharing abstract class MyClass{}';
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.classModifier).toBe('abstract');
+  });
+
+  test('Can extend a class', () => {
+    const classBody = 'public with sharing class MyClass extends Class2 {}';
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.extended_class).toBe('Class2');
+  });
+
+  test('Can implement interfaces', () => {
+    const classBody = 'public with sharing class MyClass implements Interface1, Interface2 {}';
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.implemented_interfaces.length).toBe(2);
+    expect(result.implemented_interfaces[0]).toBe('Interface1');
+    expect(result.implemented_interfaces[1]).toBe('Interface2');
+  });
+
+  test('Can have properties', () => {
+    const classBody = `
+    public with sharing class MyClass {
+      public String Prop1 { get; set; }
+      public Integer Prop2 { get; set; }
+    }
+    `;
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.properties.length).toBe(2);
+    expect(result.properties[0].type).toBe('String');
+    expect(result.properties[0].name).toBe('Prop1');
+    expect(result.properties[1].type).toBe('Integer');
+    expect(result.properties[1].name).toBe('Prop2');
+  });
+
+  test('Can have fields', () => {
+    const classBody = `
+    public with sharing class MyClass {
+      private String var1, var2;
+    }
+    `;
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.fields.length).toBe(2);
+    expect(result.fields[0].type).toBe('String');
+    expect(result.fields[1].type).toBe('String');
+    expect(result.fields[0].name).toBe('var1');
+    expect(result.fields[1].name).toBe('var2');
+  });
+
+  test('Can have constructors', () => {
+    const classBody = `
+    public with sharing class MyClass {
+      public MyClass() {}
+      public MyClass(String var1) {}
+    }
+    `;
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.constructors.length).toBe(2);
+    expect(result.constructors[0].parameters.length).toBe(0);
+    expect(result.constructors[0].access_modifier).toBe('public');
+    expect(result.constructors[1].parameters.length).toBe(1);
+    expect(result.constructors[1].parameters[0].name).toBe('var1');
+    expect(result.constructors[1].parameters[0].type).toBe('String');
+    expect(result.constructors[1].access_modifier).toBe('public');
+  });
+
+  test('Can have methods', () => {
+    const classBody = `
+    public with sharing class MyClass {
+      public static String method1() {
+        return '';
+      }
+      
+      private void method2(){}
+    }
+    `;
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.methods.length).toBe(2);
+    expect(result.methods[0].memberModifiers.length).toBe(1);
+    expect(result.methods[0].memberModifiers[0]).toBe('static');
+    expect(result.methods[0].access_modifier).toBe('public');
+    expect(result.methods[0].type).toBe('String');
+    expect(result.methods[0].name).toBe('method1');
+
+    expect(result.methods[1].memberModifiers.length).toBe(0);
+    expect(result.methods[1].access_modifier).toBe('private');
+    expect(result.methods[1].type).toBe('void');
+    expect(result.methods[1].name).toBe('method2');
+  });
+
+  test('Can have inner enums', () => {
+    const classBody = `
+    public with sharing class MyClass {
+      public enum MyEnum {}
+    }
+    `;
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.enums.length).toBe(1);
+    expect(result.enums[0].access_modifier).toBe('public');
+    expect(result.enums[0].name).toBe('MyEnum');
+  });
+
+  test('Can have inner interfaces', () => {
+    const classBody = `
+    public with sharing class MyClass {
+      public interface MyInterface {
+        void method1();
+        void method2();
+      }
+    }
+    `;
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.interfaces.length).toBe(1);
+    expect(result.interfaces[0].name).toBe('MyInterface');
+    expect(result.interfaces[0].methods.length).toBe(2);
+  });
+
+  test('Can have inner classes', () => {
+    const classBody = `
+    public with sharing class MyClass {
+      public class MyClass {
+        public void method1();
+        public void method2();
+      }
+    }
+    `;
+    const result = reflect(classBody) as ClassMirror;
+    expect(result.classes.length).toBe(1);
+    expect(result.classes[0].name).toBe('MyClass');
+    expect(result.classes[0].methods.length).toBe(2);
+  });
+});

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;
@@ -40,14 +40,17 @@ export interface ParameterMirror {
     docComment?: DocComment;
 }
 export interface MethodMirror {
+    access_modifier: string;
     annotations: Annotation[];
     name: string;
     memberModifiers: string[];
     type: string;
     parameters: ParameterMirror[];
     docComment?: DocComment;
+    group?: string;
 }
 export interface PropertyMirror {
+    access_modifier: string;
     annotations: Annotation[];
     name: string;
     memberModifiers: string[];
@@ -55,34 +58,46 @@ export interface PropertyMirror {
     docComment?: DocComment;
 }
 export interface FieldMirror {
+    access_modifier: string;
     annotations: Annotation[];
     name: string;
     memberModifiers: string[];
     type: string;
     docComment?: DocComment;
+    group?: string;
 }
 export interface ConstructorMirror {
     access_modifier: string;
     annotations: Annotation[];
     parameters: ParameterMirror[];
     docComment?: DocComment;
+    group?: string;
+}
+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 {
     annotations: Annotation[];
     name: string;
-    type_name: string;
+    type_name: TypeName;
     access_modifier: string;
     docComment?: DocComment;
 }
-declare type TypeName = 'class' | 'interface' | 'enum';
-declare type Type = InterfaceMirror | ClassMirror | EnumMirror;
 export interface InterfaceMirror {
     annotations: Annotation[];
     name: string;
     type_name: TypeName;
     methods: MethodMirror[];
     extended_interfaces: string[];
+    access_modifier: string;
     docComment?: DocComment;
+    sharingModifier?: string;
 }
 export interface ClassMirror {
     string: any;
@@ -90,8 +105,8 @@ export interface ClassMirror {
     name: string;
     type_name: TypeName;
     methods: MethodMirror[];
-    sharingModifier: string;
-    classModifiers: string[];
+    sharingModifier?: string;
+    classModifier?: string;
     extended_class?: string;
     implemented_interfaces: string[];
     properties: PropertyMirror[];
@@ -100,6 +115,7 @@ export interface ClassMirror {
     enums: EnumMirror[];
     interfaces: InterfaceMirror[];
     classes: ClassMirror[];
+    access_modifier: string;
     docComment?: DocComment;
 }
 export {};

package/index.js

@@ -3,6 +3,6 @@ exports.__esModule = true;
 exports.reflect = void 0;
 var lib = require('./out');
 function reflect(declarationBody) {
-    return lib.reflect(declarationBody);
+    return JSON.parse(lib.reflect(declarationBody));
 }
 exports.reflect = reflect;

package/index.ts

@@ -1,7 +1,7 @@
 const lib = require('./out');
 
-export function reflect(declarationBody: string): Type {
-  return lib.reflect(declarationBody) as Type;
+export function reflect(declarationBody: string): ReflectionResult {
+  return JSON.parse(lib.reflect(declarationBody)) as ReflectionResult;
 }
 
 export interface ParamAnnotation {
@@ -53,6 +53,7 @@ export interface ParameterMirror {
 }
 
 export interface MethodMirror {
+  access_modifier: string;
   annotations: Annotation[];
   name: string;
   memberModifiers: string[];
@@ -62,14 +63,17 @@ export interface MethodMirror {
 }
 
 export interface PropertyMirror {
+  access_modifier: string;
   annotations: Annotation[];
   name: string;
   memberModifiers: string[];
   type: string;
   docComment?: DocComment;
+  group?: string;
 }
 
 export interface FieldMirror {
+  access_modifier: string;
   annotations: Annotation[];
   name: string;
   memberModifiers: string[];
@@ -84,34 +88,48 @@ export interface ConstructorMirror {
   docComment?: DocComment;
 }
 
+export interface ReflectionResult {
+  typeMirror?: Type;
+  error?: ParsingError;
+}
+
+export interface ParsingError {
+  message: string;
+}
+
+// Types
+
+type TypeName = 'class' | 'interface' | 'enum';
+export type Type = InterfaceMirror | ClassMirror | EnumMirror;
+
 export interface EnumMirror {
   annotations: Annotation[];
   name: string;
-  type_name: string;
+  type_name: TypeName;
   access_modifier: string;
   docComment?: DocComment;
+  group?: string;
 }
 
-type TypeName = 'class' | 'interface' | 'enum';
-type Type = InterfaceMirror | ClassMirror | EnumMirror;
-
 export interface InterfaceMirror {
   annotations: Annotation[];
   name: string;
   type_name: TypeName;
   methods: MethodMirror[];
   extended_interfaces: string[];
+  access_modifier: string;
   docComment?: DocComment;
+  sharingModifier?: string;
+  group?: string;
 }
 
 export interface ClassMirror {
-  string;
   annotations: Annotation[];
   name: string;
   type_name: TypeName;
   methods: MethodMirror[];
-  sharingModifier: string;
-  classModifiers: string[];
+  sharingModifier?: string;
+  classModifier?: string;
   extended_class?: string;
   implemented_interfaces: string[];
   properties: PropertyMirror[];
@@ -120,5 +138,7 @@ export interface ClassMirror {
   enums: EnumMirror[];
   interfaces: InterfaceMirror[];
   classes: ClassMirror[];
+  access_modifier: string;
   docComment?: DocComment;
+  group?: string;
 }

package/jest.config.js

@@ -0,0 +1,11 @@
+// eslint-disable-next-line no-undef
+module.exports = {
+  roots: ["<rootDir>/."],
+  testMatch: [
+    "**/__tests__/**/*.+(ts|tsx|js)",
+    "**/?(*.)+(spec|test).+(ts|tsx|js)",
+  ],
+  transform: {
+    "^.+\\.(ts|tsx)$": "ts-jest",
+  },
+};