kraken-js API brainstorm

0-index.js

'use strict';

var kraken = require('kraken-js'),
    otherapp = require('./lib/otherapp');

var delegate, myapp;

delegate = { /* delegate ... */ };

/**
 * First example drops `create` method, making the `kraken` object a factory
 * as an implicit `create`. The provided name is used elsewhere to fetch the
 * application instance containing references to the express app and config.
 */
myapp = kraken('myapp1');
myapp.use('/', delegate);
myapp.use('/foo', otherapp);
myapp.listen(function (err, server) {
    err && throw err;
});

// -or-

/**
 * Second example continues to use `create`, but REQUIRES it to construct
 * a valid `myapp` and register it in the global kraken cache.
 */
myapp = kraken('myapp2').create('/', delegate);
myapp.use('/foo', otherapp);
myapp.listen(function (err, server) {
    err && throw err;
});

// -or-

/**
 * Third example changes the `create` API to only accept a name, making `use`
 * exclusively for mounting express apps and delegates
 */
myapp = kraken.create('myapp3');
myapp.use('/', delegate);
myapp.use('/foo', otherapp);
myapp.listen(function (err, server) {
    err && throw err;
});


/**
 * No name is an implicit global instance, which could be referenced
 * via just invoking kraken again:
 *    var myapp = kraken();
 * 
 * PS: This part feels dirty
 */
myapp = kraken().create('/', delegate);
myapp.listen(function (err, server) {
    err && throw err;
});

1-elsewhere.js

'use strict';

var kraken = require('kraken-js'),
    myapp = kraken('myapp1');

/**
 * Once an application has been created it can be fetched from the
 * global kraken instance, along with references to express app and config.
 */
app = myapp.app;
config = myapp.config;

module.exports = function () {
    config.get('some:setting');
};

2-example1-high-fidelity.js

'use strict';

var kraken = require('kraken-js'),
    otherapp = require('./lib/otherapp');

/**
 * config method implementation for hooking in to async config.
 * Assigned to the app instance below.
 */
function doconfig(config, callback) {
    // stuff...
    callback(null, config);
}


var myapp = kraken('myapp', /* '/baseroute'? */);

myapp.on('listening', function (server) {
    console.log('listening on ', server.address().port);
});

myapp.on('error', function (err) {
    console.error(err);
});

myapp.on('close', function (server) {
    console.log('closed');
    process.exit(0);
});

myapp.on('middleware:before:session', function (eventargs) {
    eventargs.app.use(function logpath(req, res, next) {
        console.log(req.path);
        next();
    });
});

myapp.onconfig = doconfig;
myapp.use('/foo', otherapp);
myapp.listen(function (server) {
    
    // Implementation detail: This behavior would be moved internally and
    // hooked up with shutdown middleware.
    process.on('SIGINT', function () {
        myapp.emit('disconnecting', server);
        myapp.close();
    });
    
});

3-proposed-api.md

Factory

kraken - Returns an application instance.

Application Instance

Properties

• app
• config
• onconfig

Methods (inherits from EventEmitter)

• use
• listen
• close

Events

• listening
• error
• close
• disconnecting
• middleware:*

4-config-only.js

'use strict';

var kraken = require('kraken-js');
kraken('myapp').listen();

5-mountable.js

'use strict';

var express = require('express'),
    kraken = require('kraken');
    
    
var app = express();
app.use(kraken());
app.listen();