yaap

yaap

npm install yaap
12 downloads in the last week
16 downloads in the last month

Yaap

Yaap is a generic annotation processor for javascript. It can be used to implement cross-cutting concerns and inject additional aspect oriented code.

It integrates with wire.js (part of cujo.js), which enables Spring-style wiring (i.e. dependency injection) of your javascript applications. With the yaap/wire plugin, @Autowired applications are possible

It also integrates with Express.js to achieve a SpringMVC-style framework for webapps.

Remark: This is an experimentational library and should not be used in production.

An overview of out-of-the-box supported annotations is available here

Installation

Installation for node: npm install yaap

Articles

Example

The Yaap-library can process annotated javascript-objects. One simply defines the object adds annotations and let Yaap process it.

The library already includes some so-called annotation processors, e.g. @NotNull or @Default, which injects a default value in case of a missing or null-argument.

var logger = {
    log: function(message, /*@Default("INFO")*/ level){
        console.log(level + ": " + message);
    }
};
yaap.process(logger);

The level-parameter is annotated with @Default. Calling yaap.process scans and enables attached annotations.

logger.log("hello world"); //will print "INFO: hello world"

Annotations in Javascript

Javascript does not have annotations, but at specific positions, comments are saved and can be retrieved during runtime. This library allow to retrieve and parse annotations placed at these positions.

Right now, Yaap supports class-annotations, parameter-annotations and function-annotations:

var obj = {
    "@Autowired": {"myBean": "bean"},

    fn: function(message, /*@Default("INFO")*/ level) /*@NotNull*/{
        console.log(level + ": " + message);
    }
};

@Default here is an parameter-annotation while @NotNull is a function-annotation. (@NotNull can also be used as parameter-annotation though). @Autowired is an example for a classbased annotation.

Processors

Yaap is no library of pre-defined annotations for javascript. It should be an extensible foundation to process your own annotations easily. All need to be done is to register your processor. The rest is taken care of by Yaap.

var myProcessor = {
    annotation: "@NotNull",
    processFunction: function(object, fnDescription, annotationParams, configuration){...    },
    processParameter: function(object, fnDescription, annotatedParameters, configuration){...},
    processClass: function(object, annotatedParameters, configuration){...}
}
yaap.register(myProcessor);

After registering your processor, processFunction will be called, if a function is annotated with the according annotation. processParameter is called, if an annotated parameter is found and processClass, if a class-annotation is found.

Remark: You can either define all or some of these functions, depending on where you want to allow your annotation to be placed.

More information on how to create custom annotation processors are available here.

wire.js Integration

To use @Autowired (and annotations in general) in wire.js, simply add it as a plugin:

var wire = require("wire");
wire({
    level: "INFO",
    logger: {create:  './Logger'},

    plugins: [
        {module: "yaap/wire"}
    ]
}, {require: require}).then(function(ctx){
    ctx.logger.log("message");
}, console.error);

Everything else is done by yaap, so you can start use your annotations:

//Logger.js

module.exports = {
  log: function(message, /*@Autowire*/ level){
        console.log(level + ": " + message);
    }
}

level references the value in the wire-context (with value "INFO") now.

Remark: Yaap/wire uses the parameter name to autowire. You can also supply a reference name with /*@Autowire("level")*/

Remark: You can also annotate the whole function with @Autowire so every parameter will be autowired by name.

Constructors

The yaap/wire plugin will be called after the bean was created. That means, the constructor itself will not be affected by annotations.

As a workaround, use a @PostConstruct-annotation together with the class-based @Autowired

Express.js integration

There are also out-of-the-box annotations included for creating webapps in a springMVC-like manner. More information on how to setup this integration is available here A simple example of a service:

MyService.prototype = {
    index: function ()/*@GET*/ {
        return 'index';
    },

    submit: function (name, age)/*@POST @Param*/ {
     var msg = (age < 18)? "You are too young" : "You are welcome!";
     return {view:'greet', model:{name: name, msg: msg}};
    }
};

As known from SpringMVC, the returned values determine, which view will be called and with what parameters. More details on this in my blogpost.

npm loves you