klam

Structured framework built on top of Restify

Getting Started

All you have to do is to clone the project and run the following command:

$ npm install

Once, all of the packages are installed, you're good to go! Simply, start the server:

$ node server

However, if you're deploying over production, you have to use the start script provided inside package.json.

$ npm start

Guide

Adding New Endpoint

All the endpoints resides in /app/endpoints directory. The each endpoint file would be named based upon the plural of the resource i.e users, books, authors etc.

Let's assume, you want to add a new API resource called doctors. All you have to first do is to follow these steps:

• Create a file called doctors.js inside /app/endpoints.
• Edit server.js and add doctors into endpoints' array i.e ['entry', 'users', 'doctors'].
• Modify your doctors.js initialize like this:

// IIFE function
(function() {
    'use strict';
    
    var Lib = require('../lib');
    
    module.exports = function(di) {
        var router = di.select('router'),
            models = di.select('models'),
            Doctor = models.Doctor; // assuming `Doctor` is your `mongoose` model.
         
         
        var Endpoint = {
            create: function(req, res, next) {
                // Do something here.
                // ....
                // ....
                return next();  // Do not forget to do this, so the audit tail could work fine.
            }
        };   
        
        
        /**
         * @api {post} /doctors Create a new Doctor
         * @apiName CreateDoctor
         * @apiGroup Doctors
         * @apiDescription 
         * 
         * Creates a new Doctor in Database and returns the created document.
         * 
         * @apiVersion 1.0.0
         * @apiParam    {String}    firstname   Firstname of the Doctor.
         * @apiParam    {String}    lastname    Lastname of the Doctor.
         * @apiParamExample {json} Request-Example:
         *     {
         *       "firstname": "Foo",
         *       "lastname": "Bar"
         *     }
         * 
         * 
         * @apiSuccess (201) {String} _id   Unique ID of a Doctor.
         * @apiSuccess (201) {String} firstname Firstname of the Doctor.
         * @apiSuccess (201) {String} lastname  Lastname of the Doctor.
         * 
         * @apiSuccessExample {json} Success-Response:
         *      HTTP/1.1 201 OK
         *      {
         *          "_id": "ObjectId(.....)",
         *          "firstname": "Hamza",
         *          "lastname": "Waqas"
         *      }
         *
         */
        router.post('/', Endpoint.create);
        
        // Return the router context.
        return router;
    };
}());

The documentation block is important as it helps to generate documentation at any stage of the project.

Library - Search

The helper module of Search allows you to make performance oriented searches over derived datasets. You could directly require search module from /lib directory or use existing (if created) object of Library = require('../lib').

Search.index

Binary search driven replacement of indexOf that is linear.

var lib = require('../lib'),
    Search  = lib.Search;
    
var index = Search.index([1, 2, 3, 4, 5, 6], 3);    // It should be `2`

Library - Async

Async is superset of async module. It brings all of the functions available in async but also few custom written methods helping the special scenarios.

Async.search

.search will try to use async.parallel in background to make binary search over 2 slices of data. This method is only recommended if you have ~10K of records and where ms really matters.

var lib = require('../lib'),
    async = lib.Async;
    
async.search([1, 2, 3, 4, 5, ..., 999999], 87987, function(err, idx) {
    // `err` only if error occured.
    // `err` would be removed in sooner release.
    
    // `idx` is 87986 (index of the desired value).
});

Modules

We're using few of the unified modules at our core to support the concept. Please, keep in loop before using any extra-module that is already getting done by custom module and/or pre-selected module.

• congregate
• Shipit
• clue
• paperdi
• mongoose
• redis / hiredis
• fs-extra
• q
• fast.js (called Library.K)
• bunyan
• mocha
• frisby
• async
• chalk
• klass

Generate Documentation

We're using apiDoc at the moment to generate the documentation. Once, you are done with adding new endpoint- please run the following command:

$ apidoc -i /path/to/project/and/endpoints/dir -o docs/

Testing

To execute unit (BDD / TDD) tests, you could use the typical command provided by npm:

$ npm test

And, to execute the functional tests (testing API endpoints), run the following command:

$ npm run-script functional

Deployment

Deploying to N amount of environment based hosts would be easy through Shipit. All we have to do is to configure our production, shadow and staging instances into shipitfile.js and then use the relevant command to deploy the hot-fresh code.

Clustering

To cluster our application and shard it across every core of the OS, we're using congregate at the moment. It helps us spin the app across cores and lossly coupled from our actual application code.

Licence

MIT