README.md

ts-aspect

A simplistic library for Aspect Oriented Programming (AOP) in TypeScript. Aspects can be injected on pointcuts via regular expressions for a class or object.

One application of AOP is the encapsulation of cross-cutting concerns, like logging, and keep the original business logic clean. Although a powerful tool, it should be used with care as it hides logic and complexity.

Installation

To get started, install ts-aspect with npm.

npm install ts-aspect

Using with NestJS

ts-aspect can also be used together with NestJS. An example can be seen here.

Usage

An aspect can be injected to the target class instance or object via

function addAspect(target: any, methodName: string, advice: Advice, aspect: Aspect): void

or

function addAspectToPointcut(target: any, pointcut: string, advice: Advice, aspect: Aspect): void

The aspect parameter is the actual behavior that extends the target code. When the aspect is about to be executed is defined by the advice parameter. Currently, the following advices are available:

• Before
• After
• Around
• AfterReturn
• TryCatch
• TryFinally

For example, the AfterReturn enables you to access the return value of the original function and execute additional logic on it (like logging). Finally, the pointcut parameter describes the where - so basically for which functions the aspect should be executed. For this a regular expression can be used.

If an aspect is called, it creates a new context. The context itself is defined as

export type AspectContext = {
    target: any;            // injected object
    methodName: string;     // the name of the injected function
    functionParams: any[];  // parameters passed to the call of the injected function
    returnValue: any;       // only set for the AfterReturn-Aspect
    error: any;             // only set for the TryCatch-Aspect when an error is thrown
};

Aspects await the execution of asynchronous functions - and are asynchronous themselves in this case. This enables an aspect for the advices Advice.After, Advice.AfterReturn and at the second execution of Advice.Around to work with the resolved return value of the injected function.

Also, ts-aspect provides a method decorator to attach an aspect to a all instances of a class in a declarative manner:

function UseAspect(advice: Advice, aspect: Aspect | (new () => Aspect)): MethodDecorator

Example

Assume the following aspect class which simply logs the current aspect context passed to it to the console:

class LogAspect implements Aspect{
    function execute(ctx: AspectContext): void {
        console.log(ctx);
    }
};

Also, we create the following Calculator class:

class Calculator {
    public add(a: number, b: number) {
        return a + b;
    }

    public subtract(a: number, b: number) {
        return a - b;
    }

    public divide(a: number, b: number) {
        if(b === 0){
            throw new Error('Division by zero!');
        }
        return a / b;
    }

    public multiply(a: number, b: number) {
        return a * b;
    }
};

Now the logArgsAspect can be injected to an instance of Calculator. In the following example, the aspect is supposed to be executed before running the actual business logic:

const calculator = new Calculator();
addAspectToPointcut(calculator, '.*', Advice.Before, new LogAspect());

By defining the pointcut as '.*', the aspect is executed when calling any of the functions of the respective Calculator instance. Therefore, a call to

calculator.add(1, 2);

should output

{
  target: Calculator {},
  methodName: 'add',
  functionParams: [1, 2],
  returnValue: null,
  error: null
}

And further calls to other functions like

calculator.subtract(1, 2);
calculator.divide(1, 2);
calculator.multiply(1, 2);

should result in the same output (except for the changing methodName).

An aspect can also be applied in case an exception occurs in the target code:

const calculator = new Calculator();
addAspect(calculator, 'divide', Advice.TryCatch, new LogAspect());
calculator.divide(1, 0);

In this case, the divide function throws the division by zero exception. Due to Advice.TryCatch the error is being caught and control is handed over to the aspect, which logs the error as well as both input parameters of the divide function call.
Note: Because the aspect does not rethrow the exception implicitly, the handling will stop here. Rethrowing the error in the aspect is necessary if it is supposed to be handled elsewhere.

UseAspect

In addition, aspects can be added to a all class instances in a declarative manner by using the decorator UseAspect. Based on the Calculator example above, lets add another LogAspect to the add method so that the result gets logged to the console as well:

class Calculator {
    @UseAspect(Advice.AfterReturn, LogAspect)
    public add(a: number, b: number) {
        return a + b;
    }
    // ...
}

const calculator = new Calculator();
calculator.add(1300, 37);

The aspect passed to the decorator can be either a class which provides a constructor with no arguments or an instance of an aspect.