kabam-kernel

KabamKernel for building express.js applications with plugins

npm install kabam-kernel
36 downloads in the last week
75 downloads in the last month

Kabam Kernel Build Status

Kabam-Kernel is an application container / factory for creating applications using MEAN stack

It provides an interface for creating reusable, decoupled components that extend application functionality. By dividing your application into such components you achieve greater testability and higher configurability. The project also includes built-in components for commonly used user management functionality such as sign up, sign in and OAuth integration.

Disclaimer

The project is under active development. Things break often and core interfaces aren't stabilized yet.

Example

var kabamKernel = require('kabam-kernel');
// instantiate kabam-kernel providing config object
var kernel = kabamKernel({FOO:"BAR"});
kernel.usePlugin({
  routes: function(kernel) {
    kernel.app.get('/', function(req, res) {
      res.send('Hello World');
    });
  }
});

// start listening on 3000 port by default
kernel.start();

This might seem as a lot of code for the Hello World, but Kabam-Kernel can be used for much more than just extending express.js routes.

Ideology

There were two main reasons behind creating Kabam-Kernel:

  • ability to easily develop, configure and test certain pieces of application functionality in a group of developers without breaking stuff.
  • ability to reuse certain modules in many application or creating instances of the same application but with different modules (for example REST and WebSocket interfaces with the same business logic)

So given that the instantiation of majority of web applications can be narrowed down to 5 phases:

  1. Configuration
  2. Instantiation of services (DB connections, redis, etc...)
  3. Instantiation of the app itself
  4. Middleware configuration
  5. Registering routes with business logic itself

We created an interface for developing Kabam-Kernel plugins which allows to hook up to all the phases above and extend the app.

Complete plugin example

Lets say we have a file named foo.js with the following content:

var redis = require('redis');
// name of the plugin
exports.name = 'foo-plugin';
// services that will be added to the kernel, in this case we add redis client
exports.core = {
    redis: redis.createClient(),
    someNumber: 42
}
// a plugin can also add models to the application
exports.model = {
  Cats: function (mongoose, config) {
    var CatsSchema = new mongoose.Schema({
      'nickname': String
    });

    CatsSchema.index({
      nickname: 1
    });
    return CatsSchema;
  }
}
// extend express js application
exports.app = function (kernel) {
  kernel.app.set('someValue', 42);
};

// add passport.js strategy
exports.strategy = function (kernel) {
  return new LinkedInStrategy({
      // reading config values from kernel.config 
    consumerKey: kernel.config.passport.LINKEDIN_API_KEY,
    consumerSecret: kernel.config.passport.LINKEDIN_SECRET_KEY,
    callbackURL: kernel.config.hostUrl + 'auth/linkedin/callback'
  }, function (token, tokenSecret, profile, done) {
    var email = profile.emails[0].value;
    // using of the built-in models
    kernel.model.User.linkEmailOnlyProfile(email, done);
  });
};

// a list of middleware components that will be added to the app
exports.middleware = [
  function (kernel) {
    return function (request, response, next) {
      request.model.Cats.count({name: 'Grumpy'}, function (err, numberOfCats) {
          // using someNumber that were added to the kernel before
        if (numberOfCats > kernel.someNumber) {
          request.getSum = kernel.getSum; //DI of core methods or values
          next();
        } else {
          response.send(500, 'There is not enough cats called "Grumpy" to run this application!');
        }
      });
    };
  }
];

// configure routes for the express.js application
exports.routes = function(kabam){
  kabam.app.get('/kittens',function(request,response){
    kabam.model.Cats.find({},function(err,cats){
      if(err) throw err;
      response.json(cats);
    });
  });

  // adding routes fo the passport strategy configured above
  kabam.app.get('/auth/linkedin', kabam.passport.authenticate('linkedin'));
  kabam.app.get('/auth/linkedin/callback', kabam.passport.authenticate('linkedin', { failureRedirect: '/' }),
    function (req, res) {
      res.redirect('/');
    });
};

We can now extend our app by including the plugin above with one simple line of code

kernel.usePlugin(require('foo'));

API Documentation

Current API documentation for the Kabam-Kernel and core plugins can be found at http://cd.monimus.com:8080/

Kabam-Kernel instance methods

  1. extendCore('fieldName',function(config){...}) or extendCore('fieldName', 'someValue') or extendCore(function(core){...})- extend kernel object. Extends kernel with new services.

  2. extendStrategy - extend authorization means of application by custom Passport.js strategies module.

  3. extendModel(ModelName,function(mongoose, config){...}) - extend application mongoose models.

  4. extendApp(['development','staging','production','otherEnviroment'],function(core){...}) - set global application parameters, for example template engines, locals and other settings. First argument (array of enviroments) is OPTIONAL

  5. extendMiddleware(['development','staging','production','otherEnviroment'],'/middlewarePath',function(core){...}) - set application middleware. This function can be executed multiple times, the middleware components applied in order they were declared by this function. First argument (array of enviroments), and the second one (the path where to use middleware, the default is "/") are OPTIONAL

  6. extendRoutes(function(core){...}) - add custom routes to application.

  7. usePlugin("kabam-plugin-foo") or usePlugin(pluginObj) - use plugin as an object or npm package. See more on how to create a plugin for details.

  8. start - start the Kabam application in way desired.

  9. startCluster - start the Kabam application in way desired as a Cluster.
npm loves you