fabrix-app / spool-annotations

Spool: Annotations

spool-annotations

📦 Add Route, Policy and custom annotations support for Fabrix applications

Intallation

With fab cli :

npm install -g @fabrix/fab-cli
fab spool spool-annotations

With npm (you will have to create config file manually) :

npm install --save @fabrix/spool-annotations

Configuration

First you need to add this spool to your main configuration :

// config/main.ts

export const annotations = {
   // ...

   spools: [
      // ...
      require('@fabrix/spool-annotations').AnnotationsSpool,
      // ...
   ]
   // ...
}

Then :

// config/annotations.ts
export const annotations = {
  policy: true,//enable policy annotations
  route: true,//enable route annotations
  pathToScan: './api/controllers',//or ./api for hmvc
  customAnnotations: null, //Add your custom annotations here, require('./annotations') for example

}

Usage

Route

A route added with annotation will replace any previous route set under config/routes.ts (for a same path).

module.exports = class DefaultController extends Controller {

  /**
   * Return some info about this application
   * @Route("GET /default/info") or @Route({method: ["GET"], path: "/default/info"})
   */
  info (request, reply) {
    reply.json(this.app.services.DefaultService.getApplicationInfo())
  }
}

You can also use @METHOD for defining new routes.

module.exports = class DefaultController extends Controller {

  /**
   * Return some info about this application
   * @GET('/default/info')
   * @HEAD('/default/info')
   * @OPTIONS('/default/info')
   * @POST('/default/info')
   * @PUT('/default/info')
   * @PATCH('/default/info')
   * @DELETE('/default/info')
   */
  info (request, reply) {
    reply.json(this.app.services.DefaultService.getApplicationInfo())
  }
}

A more complex sample with validation.

module.exports = class DefaultController extends Controller {

  /**
   * Return some info about this application
   * @GET(path:{'/default/info'}, config: { validate: {
   * query: { infos: Joi.sring().required() }
   * }})
   */
  info (request, reply) {
    reply.json(this.app.services.DefaultService.getApplicationInfo())
  }
}

See hapijs tutorial on validation and joi schema validation for more complex with validate object.

Policy

A policy added with annotation will be added to policies set under config/policies.ts.

module.exports = class DefaultController extends Controller {

  /**
   * Return some info about this application
   * @Policy("Default.auth") or @Policy(["Default.auth", "Default.acl"])
   */
  info (request, reply) {
    reply.json(this.app.services.Defaultervice.getApplicationInfo())
  }
}

Custom

Create your own annotation like this :

'use strict'
const Annotation = require('ecmas-annotations').Annotation

export class MyCustomAnnotation extends Annotation {

    /**
     * The possible targets
     *
     * (Annotation.CONSTRUCTOR, Annotation.PROPERTY, Annotation.METHOD)
     *
     * @type {Array}
     */
    static get targets() {
      return [Annotation.METHOD]
    }

    /**
     * The function to call when annotations are find
     *
     * @type {Function}
     */
    handler(app, annotation) {
      //Do whatever you want when annotation is found
    }

    /**
     * File path
     *
     * @type {String}
     * @required
     */
    static get path() {
      return __filename
    }

}

Now I can add @MyCustomAnnotation("It works") on methods.

License

MIT