@semaver/reflector

An extensive way to deal with classes.

About

reflector package does a full examination of TypeScript classes. It provides an extensive mechanism for querying and filtering detailed information about class structure. The package supports the reflection of decorated class members and parameters with the help of the built-in concept of Annotation Decorators. Annotation Decorators are the decoration mechanism for the code annotations in TypeScript. In other words, it provides the possibility to label different class members and parameters. reflector covers sophisticated cases of working with such decorators, like dynamic decoration on runtime and inheritance of decorated class members.

Features

Acquiring detailed class information via annotated class members and parameters.
Static and dynamic annotation (static: via @decorators; dynamic: on runtime, e.g. for third-party libs)
Handling inheritance of annotated class members and parameters with the help of the Decoration Policies.

Requirements

To be able to use @decorator() syntax in Typescript it's required to configure tsconfig.json file. However, it is possible to avoid this by using dynamic decoration (also works for Javascript projects)

{
    "compilerOptions": {
      ...
      "experimentalDecorators": true,
      "emitDecoratorMetadata": true           
    }
}

⚠️ Important! Support of Typescript 5.x decorators will be available after the release of "decorated parameters"

Link → "Differences with Experimental Legacy Decorators"

Installation

$ yarn add @semaver/reflector --peer
$ npm install @semaver/reflector

⚠️ Important! Please, pay attention, that this package has a peer dependency to @semaver/core library.

⚠️ Important! Please, install the library as peer dependency if possible.

Get Started

To get familiar with Reflector API, we will go through simple examples.

Examples Setup: We are trying to develop software that will automatically add getters & setters to the class properties. Let's have a look at how the reflector package and its built-in Annotation Decorators can help us with it.

Examples Setup Preparation

Since our sample software should add getters & setters to the class property, let's define an example method that we can use for this purposes:

//Example function how to add accessors to the class property
function addAccessors<T extends object = object>(key: keyof T, obj: T): void {
  const privateKey: keyof T = "_" + key.toString() as keyof T;

  Object.defineProperty(obj, privateKey, {
    value: obj[key],
    writable: true
  });

  Object.defineProperty(obj, key, {
    get: () => {
      console.log("GET: " + key.toString());
      return obj[privateKey];
    },
    set: (value) => {
      console.log("SET: " + key.toString());
      obj[privateKey] = value;
    },
  });
}

To add accessors to the class, we need to define a couple of sample classes on which we will test our code:

class Shape {
    public x: number;
    public y: number;
    public color: string;

    public constructor(x: number, y: number, color: string) {
        this.x = x;
        this.y = y;
        this.color = color;
    }

    public draw(): void {
        console.log("Let's imagine that we are drawing smth here!");
    }
}

class Circle extends Shape{
    public radius: number;

    public constructor (x: number, y: number, color: string, radius: number) {
        super(x, y, color);
        this.radius = radius;
    }
}

To simplify our code and to show the whole power of the built-in Annotation Decorators of the reflector package, we create an annotation decorator. It will be used to mark the properties that have to be updated with accessors.

import {
    Decorator,
    DecoratorFn
} from "@semaver/reflector";

function accessors(): DecoratorFn {
    return Decorator.build(new AccessorsDecorator());
}

class AccessorsDecorator extends Decorator {
}

The final preparation step is to annotate our sample class properties with the @accessors annotation decorator:

import {accessors} from "../decorators/AccessorsDecorator";

class Shape {
  @accessors()
  public x: number;

  @accessors()
  public y: number;

  @accessors()
  public color: string;

  public constructor(x: number, y: number, color: string) {
    this.x = x;
    this.y = y;
    this.color = color;
  }

  public draw(): void {
    console.log("Let's imagine that we are drawing smth here!");
    }
}

Now, we are all set to explore the Reflector possibilities!

Example 1: How to get class members with Reflector API

To apply our logic of adding accessors to the property we can use Reflector API. It will get us the properties from the class. We can do that in many ways:

via the property name one by one;
as a group of all annotated class properties;
via the Reflector Query API to get the an array of the all annotated class properties.

Example 1.1 Get Property By Name

ℹ️ More information on Reflector API and how to get other class members and parameters can be found here: Get Class Members and Paramters

import {Property, Reflector} from "@semaver/reflector";

//Create Reflector instance
const shapeReflector: Reflector<Shape> = Reflector.from(Shape);

//Get property by name
const xProperty: Property = shapeReflector.getProperty("x", false);

// Method to add accessors to the property, example implementation can be found in Examples Setup Preparation
addAccessors(xProperty.getName() as keyof object, Shape.prototype);

//Check if setter & getter are executed
const myShape : Shape = new Shape(3,4, "red"); //CONSOLE: SET x
console.log(myShape.x); // CONSOLE: GET: x; 3

Example 1.2: Get Annotated Properties

ℹ️ Detailed information on how to create and use Annotation Decorators can be found here: Annotation Decorators

import {Reflector} from "@semaver/reflector";

//Create Reflector instance
const shapeReflector: Reflector = Reflector.from(Shape);

//Get all decorated properties
shapeReflector.getDecoratedProperties().forEach(prop => {
  // Method to add accessors to the property, example implementation can be found in Examples Setup Preparation
  addAccessors(prop.getName() as keyof object, Shape.prototype);
});

//Check if setter & getter are executed
const myShape: Shape = new Shape(3, 4, "red"); //CONSOLE: SET x; SET y; SET color
console.log(myShape.x); // CONSOLE: GET: x; 3

Example 1.3: Get Property By Query

ℹ️ More information on Reflector API and how to query annotated class members and parameters can be found here: Query Class Members and Parameters

import {
    ByMemberType,
    ClassMember,
    DecoratedElementType,
    QueryExecutor,
    Reflector
} from "@semaver/reflector";

//Create Reflector instance
const shapeReflector: Reflector<Shape> = Reflector.from(Shape);

//Create query instance
const query: QueryExecutor<Shape> = shapeReflector.query();

//Filter query to get all properties (get all class members that have "PROPERTY" type)
const byMemberTypeQuery: QueryExecutor<Shape> = query.filter(ByMemberType.from(DecoratedElementType.PROPERTY));

//Get the result from the query as an array of properties
const members: ClassMember[] = byMemberTypeQuery.members().all<ClassMember<Shape>>();

//Method to add accessors to the property, example implementation can be found in Examples Setup Preparation
members.forEach(prop => addAccessors(prop.getName() as keyof object, Shape.prototype));

//Check if setter & getter are executed
const myShape : Shape = new Shape(3,4, "red"); //CONSOLE: SET x; SET y; SET color
console.log(myShape.x); // CONSOLE: GET: x; 3

Example 2: How to work with annotation decorator policies

Annotation Decorators unlock the power of Decoration Policies, which we will investigate in this and further examples.

ℹ️ Detailed information on all available Decoration Policies and their properties can be found here: Decoration Policies

We agreed to add accessors to the class properties. So we can limit our @accessors annotation to the class properties only. This can be done with the help of Access Policy, which we need to configure for the annotation decorator:

import {
    Decorator,
    DecoratorFn,
    MetadataAccessPolicy,
} from "@semaver/reflector";

function accessors(): DecoratorFn {
    return Decorator.build(new AccessorsDecorator());
}

class AccessorsDecorator extends Decorator {
  //Add Access Policy and configure it to make annotation available to class properties only
    public getAccessPolicy(): MetadataAccessPolicy {
        return MetadataAccessPolicy.PROPERTY;
    }
}

Now we add the @accessors annotation to the Shape class properties and draw() method to make sure that @accessors will be just ignored on everything that is not a class property:

class Shape {
  @accessors()
  public x: number;

  @accessors()
  public y: number;

  @accessors()
  public color: string;

  public constructor(x: number, y: number, color: string) {
    this.x = x;
    this.y = y;
    this.color = color;
  }

  //This annotation is not allowed by Access Policy, so will be just ignored
  @accessors()
    public draw(): void {
        console.log("Let's imagine that we are drawing smth here!");
    }
}

So let's check, that Reflector will see 3 annotated Shape class properties but won't find any annotated method:

import {reflector} from "@semaver/reflector";

//Create Reflector instance
const shapeReflector: Reflector<Shape> = Reflector.from(Shape);

//Check that Reflector sees 3 decorated properties
console.log(shapeReflector.getDecoratedProperties()); // CONSOLE: [Property, Property, Property]

//Check that Reflector sees any decorated methods
console.log(shapeReflector.getDecoratedMethods()); // CONSOLE: []

Example 3: How to work with annotation decorator inheritance

As classes in TS support inheritance, Annotation Decorators support it as well for the same class member and parameter. It is regulated via Inheritance Decoration Policies: Collision Policy, Not-Existence Policy, Appearance Policy.

We will see how it works on the example of Not-Existence Policy. It defines the behavior of the decorator, if it does NOT EXIST in the child class, but EXISTS in its direct parent class for the same class member or argument.

Not-Existence Policy has 2 values:

SKIP - decorator from the direct parent class is not used for the child class;
APPLY - decorator from the direct parent class is used for the child class.

In our original example: Shape class is a parent class and Circle is a child class. We assume that we want Circle class to also have inherited properties annotated, so the Not-Existence Policy should be set to APPLY. To make this happen, we need to add it to the @accessors annotation decorator:

import {
   Decorator,
   DecoratorFn,
   MetadataAccessPolicy,
   MetadataNotExistencePolicy,
   PrimitiveMetadataAccessPolicy
} from "@semaver/reflector";

function accessors(): DecoratorFn {
   return Decorator.build(new AccessorsDecorator());
}

class AccessorsDecorator extends Decorator {
   public getAccessPolicy(): MetadataAccessPolicy {
       return MetadataAccessPolicy.PROPERTY;
   }

   // Add Not-Existence Policy to enforce the inheritance of the annotations for inherited properties
   public getNotExistencePolicy(access: PrimitiveMetadataAccessPolicy): MetadataNotExistencePolicy {
       return MetadataNotExistencePolicy.APPLY;
   }
}

ℹ️ Not-Existence Policy: APPLY is actually the default value for this policy. So there is no need to redefine it again in AccessorsDecorator class, cause it will be default behavior anyway. But we are doing it in this example for better visibility and understanding.

Now we can check that even without setting anything explicitly in the Circle class, Reflector can see inherited properties as annotated, so we can get them and apply our update with accessors logic:

import {Reflector} from "@semaver/reflector";

//Create Reflector instance
const circleReflector: Reflector<Circle> = Reflector.from(Circle);

//Get decorated properties in Circle via Not-Existence Policy
circleReflector.getDecoratedProperties().forEach(prop => {
 // Method to add accessors to the property, example implementation can be found in Examples Setup Preparation
 addAccessors(prop.getName() as keyof object, Circle.prototype);
});

//Check if setter & getter are executed
const myCircle: Circle = new Circle(3, 4, "red", 5);//CONSOLE: SET x; SET y; SET color
console.log(myCircle.x);// CONSOLE: GET: x; 3

Example 4: How to get all annotated properties in all classes

As a final step, we need to make our approach to update class properties with accessors as general as possible, so it will be good not to rely on concrete classes and property names. reflector package gives us such possibility. It has centralized storage for the decorated classes(classes that contain decorated members and parameters), called ClassTable.

ℹ️ Detailed information on ClassTable and how to get all decorated classes can be found here: Get All Decorated Classes

We can see how it works in our Shape-Circle example. We need to add the @accessors annotation to the Circle.radius property, to cover all existing properties:

class Circle extends Shape {
  @accessors()
  public radius: number;

  public constructor(x: number, y: number, color: string, radius: number) {
    super(x, y, color);
    this.radius = radius;
  }
}

Now we can check how all properties in both classes will be seen by Reflector and we can update them with accessors:

import {Reflector} from "@semaver/reflector";

// Reflect has direct access to the ClassTable from where it can get all decorated classes
Reflector.getClassTable().getClasses().forEach(cls => {

  //Create Reflector instance
  const reflector: Reflector = Reflector.from(cls);

  //Get all decorated properties from the class
  reflector.getDecoratedProperties().forEach(prop => {
    // Method to add accessors to the property, example implementation can be found in Examples Setup Preparation
    addAccessors(prop.getName() as keyof object, cls.prototype);
  });
});

//Check if setter & getter are executed
const myShape: Shape = new Shape(3, 4, "red");//CONSOLE: SET x; SET y; SET color
console.log(myShape.x);// CONSOLE: GET: x; 3

const myCircle: Circle = new Circle(3, 4, "red", 5);//CONSOLE: SET x; SET y; SET color; SET: radius
console.log(myCircle.radius);// CONSOLE: GET: radius; 5

Example 5: How to annotate class dynamically

In the previous examples, we were working with statically annotated classes. The Reflector API gives us the possibility to annotate class members and parameters dynamically during run-time (e.g. for some library class).

ℹ️ Detailed information on dynamic class annotation can be found here: Decorate Class Members & Parameters Dynamically

Let's try it on our basic sample class Shape without any static annotations:

class Shape {
    public x: number;
    public y: number;
    public color: string;

    public constructor(x: number, y: number, color: string) {
        this.x = x;
        this.y = y;
        this.color = color;
    }

    public draw(): void {
        console.log("Let's imagine that we are drawing smth here!");
    }
}

To do this, we only need to call the addDecorator() method of the Reflector with the annotation decorator method accessors() as a parameter:

import {Reflector} from "@semaver/reflector";

//Create Reflector instance
const shapeReflector: Reflector<Shape> = Reflector.from(Shape);

shapeReflector.getProperty("x").addDecorator(accessors());
shapeReflector.getProperty("y").addDecorator(accessors());
shapeReflector.getAccessor("color").addDecorator(accessors());

Reflector Documentation

Reflector API
Annotation Decorators
Architectural Notes

Reflector API

The main goal of the reflection is to provide information about class structure. The reflector package gives you the possibility to access class members and parameters directly by name or query annotated structural items by some condition. The annotations HAVE TO be built on the Annotation Decorators mechanism, that is provided by this package, otherwise class members and parameters won't be visible to the Reflector.

ℹ️ Annotation Decorators is the decoration mechanism for the code annotations in TypeScript. It provides the possibility to label different class members and parameters. How to create and use annotation decorators can be found here: Annotation Decorators

To get access to the Reflector API, the Reflector object has to be created. It can be done in 2 ways:

with reflected class type;
with reflected class instance.

const someReflector1: Reflector = Reflector.from(SomeClass);
// or
const instance: SomeClass = new SomeClass();
const someReflector2: Reflector = Reflector.from(instance);

ℹ️ Method from() takes 2 parameters: 1. class type/instance 2. autoSync parameter(boolean: true/false). The autoSync parameter is used for the dynamic decoration. Its default value is false, which means that the Reflector will ignore dynamically added/removed decorators. When autoSync is set to true, it will make the Reflector automatically synchronize its state and see all changes that are made by dynamic decoration. More details on dynamic decoration can be found at Decorate Class Members & Parameters Dynamically.

Reflected Types

There are four class member types and one parameter type, that Reflector can acquire:

enum ClassMemberType {
    CONSTRUCTOR = "CONSTRUCTOR",
    PROPERTY = "PROPERTY",
    ACCESSOR = "ACCESSOR",
    METHOD = "METHOD",
}

enum ParameterType {
    PARAMETER = "PARAMETER",
}

The reflected type is a wrapper class under the relevant language construction, that helps to properly encapsulate necessary information about the requested class member or parameter.

ℹ️ More details on reflected types can be found at Reflected Types Architecture.

@semaver/reflector

@semaver/reflector

About

Features

Requirements

Installation

Get Started

Examples Setup Preparation

Example 1: How to get class members with Reflector API

Example 1.1 Get Property By Name

Example 1.2: Get Annotated Properties

Example 1.3: Get Property By Query

Example 2: How to work with annotation decorator policies

Example 3: How to work with annotation decorator inheritance

Example 4: How to get all annotated properties in all classes

Example 5: How to annotate class dynamically

Reflector Documentation

Reflector API

Reflected Types

Get Class Members and Paramters

Query Class Members and Parameters

Filter Class Members and Parameters

Custom Filters

Decorate Class Members and Parameters Dynamically

Get All Decorated Classes

Annotation Decorators

Create Annotation Decorators

STEP 1: Define Decorator Function

STEP 2: Define Decorator Class

[OPTIONAL] STEP 3: Define Decoration Policies

[OPTIONAL] STEP 4: Define Decorator Paramters

Use Annotation Decorators

Decoration Policies

Access Policy

Same-Target-Multi-Usage Policy

Collision Policy

Not-Existence Policy

Appearance Policy

Architectural Notes

Reflected Types Architecture

Behind the Scene of Annotation Decorators

Annotation Decorators Usage for Constructor Parameters

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads