OZ-Decorators

These decorators classes helps you focus on your logic and hides the issues regarding decorators.

With this module you can decorate classes, methods, members and accessors (properties with get and or set).

• API
• Usage
  • Add behavior to method
  • Add functionality to class
  • Dispatcher class

API

// Decorates the code (class, function) and returns afactory method to an instance of the specified DecoratorBase (any argument will be passed to the constructor)

// usage: @decorate(MergeClassesDecorator)(ConsoleLogger, ExtraLog)
export default function decorate(decoratorCtor: Constructor<BaseDecorator>)

// Shared decorator API (no need to implement, next classes are the real bases)
interface BaseDecorator {
  decorate(...args: any[]): any
}

// base for decorating classes
abstract class ClassDecorator {
  // Once decorated, this method is called with new class construtcor (cls parameter).
  // Here is where the class modification should take place
  protected abstract onCreated(cls: Constructor)
}

type DecoratingMethodHandler = (target: any, propertyKey: string, descriptor: PropertyDescriptor, ...args: any[]) => any

type WrapingMethodHandler = (key: string, invoker : Function, ...args: InputParameter[]) => void

// class to decorate a field member 
class MemberDecorator  {
  
  constructor(
    onDecoratingMethod: DecoratingMethodHandler, // called when decorated
    wrapingGetMethod: WrapingMethodHandler, // wrapping method for getting member value
    wrapingSetMethod?: WrapingMethodHandler // wrapping method for setting member value
    ) {...}
}

// class to decorate a accessor (property with get and or set)
class AccessorDecorator {
  
  constructor(
    onDecoratingMethod: DecoratingMethodHandler, // called when decorated
    wrapingGetMethod: WrapingMethodHandler, // wrapping method for getting member value
    wrapingSetMethod?: WrapingMethodHandler // wrapping method for setting member value
    ) {...}
}

// class to decorte methods (functions)
class MethodDecorator {
  constructor(
    onDecoratingMethod: DecoratingMethodHandler, // called when decorated
    wrapingMethod?: WrapingMethodHandler, // extends the calling of the decorated method
    ...args:any[]
  ) {...}
}

// class to decorte methods parameters (functions arguments)
class MethodParameterDecorator {

  // can be overriden
  /*virtual*/ onParamMetaData(
    paramName: string, 
    methodName: string,  
    index: number // parameter's index in the arguments list
  )
}

Usage

Add behavior to method

To wrap method with extra behavior you can use MethodDecorator This is how to add log on methods

function onDecorating(target: any, propertyKey: string, descriptor: PropertyDescriptor) : any {
}

function wrapingMethod(key: string, invoker : Function, ...args:InputParameter[]){
  console.log(`calling ${key} in wrapingMethod`)
  invoker()  
}

class Test {
  @decorate(MethodDecorator)(onDecorating, wrapingMethod)
  foo() {
    console.log('foo')
  }
}

Now let's call it

let t = new Test()
t.foo()

output will be

calling foo in wrapingMethod
foo

Add functionality to class

Here is how to add log functionality to Test class.

First, we'll declare a class that will have the logging functionality

class Logger {
  log(level: number, message: string) {
    console.log(`${level}: ${message}`)
  }

  logDebug(message: string) {
    this.log(0, message)
  }

  logWarn(message: string) {
    this.log(1, message)
  }

  logError(message: string) {
    this.log(2, message)
  }
}

For ease of use (and 'compile time' error), we'll merge types:

interface Test extends Logger {}

Now let's decorate Test class (merge it with Logger):

@decorate(ClassMixinDecorator)(Logger)
class Test {
  @decorate(MethodDecorator)(onDecorating, wrapingMethod)
  foo() {
    console.log('foo')
    this.logDebug('debugging foo')
  }
}

We'll get:

calling foo in wrapingMethod
foo
0: debugging foo

Dispatcher class

Here is how to use decorators and Dispatcher class to dispatch actions in run-time:

First we'll declare an Action class like so:

class Action {
  id: number

  inputParam1?: string
  inputParam2?: string
}

Now let's declare a dispatcher class that will call methods accordingly.

Two methods must be defined:

1. getKey - this returns the key from the dispatched object
2. getParamFromDispatched - this returns a value from the dispatched object to be injected to a parameter on the target method.

class ActionDispatcher extends Dispatcher<number, Action> {
  
  protected getKey(obj: Action): number {
    return obj.id
  }
  
  protected getParamFromDispatched(meta: InputParameter, obj: Action) {
    return obj[meta.name]
  }
}

Method will be "dispatchable" after decorating with @classDispacher().

Actual dispatched methods can be private.

@classDispacher()
class ActionDispatcher {

  ...

  @methodDispatcher(1)
  private action1() {
    console.log("in action1")
  }

  @methodDispatcher(2)
  private action2(@paramDispatcher() inputParam1: string) {
    console.log(`in action2: ${inputParam1}`)
  }

  @methodDispatcher()
  private defaultAction(@paramDispatcher() inputParam1: string,
    @paramDispatcher() inputParam2: string) {
    console.log(`in defaultAction: ${inputParam1}, ${inputParam2}`)
  }
}

Usage:

let ad = new ActionDispatcher()

ad.dispatch({ id:1 }) // action1 will be invoked

ad.dispatch({ id:2, inputParam1: 'value2' })  // action2 will be invoked with 'value2' injected to inputParam1 parameter

ad.dispatch({ id: 100, inputParam1: 'value101', inputParam2: 'value102' }) // defaultAction will be invoked

output:

in action1
in action2: value2
in defaultAction: value101, value102