JSPM

Basic Usage

'use strict';

var express = require('express'),
    kraken = require('kraken-js');

var app = express();
app.use(kraken());
app.listen(8000);

API

kraken([options])

All kraken-js configuration settings are optional.

• basedir (String, optional) - specify the working directory for kraken-js to use.
• onconfig (Function, optional) - provides an asynchronous hook for loading additional configuration. Signature: function (config, cb) { /* ... */ }
• protocols (Object, optional) - protocol implementations for use when processing configuration. For more information on protocols see shortstop.
• uncaughtException (Function, optional) - Handler for uncaughtException errors. See the endgame module for defaults.

Features

Environment-aware Configuration

Using environment suffixes, configuration files are applied and overridden according to the current environment as set by NODE_ENV. The application looks for a ./config directory relative to the basedir and recursively scans for all JSON files contained therein. JSON files without a suffix or with an environment suffix that matches the current env are processed an loaded. Additionally, JSON configuration files may contain comments.

Valid NODE_ENV values are undefined or dev[elopment], test[ing], stag[e|ing], prod[uction]. Simply add the suffix for a file to have it read only in that environment, e.g. config/app-development.json.

Dynamic Configuration Values

Powered by shortstop, configuration files can contain values that are resolved at runtime. Default shortstop protocol handlers include:

• path:{path} - resolves the provided value against the application basedir.
• file:{path} - loads the contents of the specified file.
• base64:{data} - converts the base64-encoded value to a buffer.

Configuration-based Middleware

Middleware is completely configuration-based. meddleware is used internally to read, resolve, and register middleware with your express application.

Safe startup and shutdown

TODO

Configuration-based express Settings

Since express instances are themselves config objects, the convention is to set values on the app instance for use by express internally as well as other code across the application. kraken-js allows you to configure express via JSON. Any properties are supported, but kraken-js defaults include:

{
    "express": {
        "env": "", // NOTE: `env` is managed by the framework. This value will be overwritten.
        "x-powered-by": false,
        "trust proxy": false,
        "jsonp callback name": null,
        "json replacer": null,
        "json spaces": 0,
        "case sensitive routing": false,
        "strict routing": false,
        "view cache": true,
        "view engine": null,
        "views": "path:./views",
        "route": "/"
    }
}

Additional notes:

• The env setting will be set to the environment value as derived by kraken-js, so what is put here will be overwritten at runtime.
• Set the view engine property to the one of the view engines property names (see the section View Engine Configuration) to enable it for template rendering.
• The optional view property is a special case in which you can set a path to a module which exports a constructor implementing the view API as defined by the module express/lib/view. If set, kraken-js will attempt to load the specified module and configure express to use it for resolving views. For example:

{
    "express": {
        "view": "path:./lib/MyCustomViewResolver"
    }
}

View Engine Configuration

kraken-js looks to the view engines config property to understand how to load and initialize renderers. The value of the view engines property is an object mapping the desired file extension to engine config settings. For example:

{
    "view engines": {
        "jade": {
            "module": "consolidate"
        },
        "html": {
            "name": "ejs",
            "module": "ejs",
            "renderer": "renderFile"
        },
        "dust": {
            "module": "adaro",
            "renderer": {
                "method": "dust",
                "arguments": [{ "cache": false }]
            }
        },
        "js": {
            "module": "adaro",
            "renderer": {
                "method": "js",
                "arguments": [{ "cache": false }]
            }
        }
    }
}

The available engine configuration options are:

• module (String) - This is the node module that provides the renderer implementation. The value can be the name of a module installed via npm, or it can be a module in your project referred to via file path, for example "module": "path:./lib/renderer".
• name (String, optional) - Set this if the name of the rendering engine is different from the desired file extension. For example, you chose to use ejs, but want to use the "html" file extension for your templates. Additionally, if the renderer function exported by the module is not the file extension and a "renderer" property is not defined, this value will be used.
• renderer (String|Object, optional) - The renderer property allows you to explicitly identify the property or the factory method exported by the module that should be used when settings the renderer. Set the value to a String to identify that the renderer is exported by that name, or an object with the properties "method" and "arguments" to identify a factory method. For example, using ejs you could set this property to "renderFile" or "__express" as the ejs module exports a renderer directly.

Events

kraken-js adds support for the following events to your express app instance:

• start - the application has started and is ready to accept requests.
• shutdown - the application is shutting down, no longer accepting requests.
• stop - the http server is no longer connected or the shutdown timeout has expired.
• error -

Tests

$ npm test

Coverage

$ npm run-script cover && open coverage/lcov-report/index.html
```