roux


A simple, event-driven, parallel-processing, highly-opinionated API framework for node.js.


Roux is...

$3

Require Roux, and start it, that's it. Now you've got a RESTful JSON API running with many built-in features.

$3

Roux is not an MVC framework. Nor is it an MVVM. It's an event-driven API framework purpose-built to take advantage of the things Node.js does well, and to utilize server-resources as efficiently as possible. Rather than a typical server-to-router-to-controller setup...

``
Server > Routing Table > Controller > Model > Response
`

...Roux revolves around event emission and binding instead.

`
Server > event > Handler(s) > event(s) > Model(s) > event(s) > Response
`

When an incoming http request is received, the server emits an event which triggers any service-handlers that may be listening. These handlers process the request data then (may or may not) emit an event which triggers CRUD operations in models. Once all the triggered-events have fired and finished processing, the server sends a response to the user.

$3

Roux utilizes Node's clustering utilities to make optimal use of all available CPUs. Event listeners can each run on their own fork, so that multipe event handlers can process requests in parallel. This optimizes the speed at which a user receives the server response, and allows the server to support a large number of connections and processes.

$3

Roux encourages a few key principles: statelessness, readability, useability, testabilitiy, and standards-conformance. As such, this framework is opinionated as to how you structure your code and your services.

Roux encourages the creation of functional, immutable, context-independent handlers, and object-oriented, CRUD-focused models. It encourages general-purpose, exportable code, and minimal app-specific procedure. Chained callbacks are discouraged, closures are avoided, and promises are used sparingly. Anything that encourages state is eschewed in favor of decoupled, parallel, idempotent procedures.

Roux supports structured, static services with clean, semantic, consistent paths. It enforces proper use of HTTP status codes and headers, and handles a number of best-practices (like rate-limiting and api-versioning) automatically behind the scenes.

Built in Features

Roux attempts to handle the use-cases that most APIs have in common, so that you can focus on writing only your app-specific code. Here are some of the features Roux out of the box:

* API versioning
* Environment-dependant configuration
* Debugging mode with verbose output
* Caching of GET requests
* Rate-limiting
* CORS and JSONP support
* HTTPS support
* Automatic timeouts

Getting Started

$3

`bash
npm install roux --save
`

$3

Sample directory structure

`
package.json
config.js
index.js
/handlers
/widget.js
/...
/models
/widget.js
/...
/test
/...
`

Sample index.js:

`js
// Require Roux
var api = require('roux');

// Start your API
api.start();
`

Sample config.js:

`js
var environments = {
localhost: {
server: {
port: 9999
}
},
staging: {
server: {
port: 80
}
},
production: {
server: {
port: 443
https: true
}
}
};

module.exports = environments;

`
For a full list of configuration options, read the Wiki

$3

Sample handlers/widget.js:

`js
var api = require('roux');
var handler = new api.handler();

// Define the services, methods, and api-versions the handler should bind to
handler.bindTo('/widget', 'GET', ['1.1', '1.2'], 'start');

// Primary logic for the handler
handler.functions.start = function(req,res){

var parameters = {};
// Do stuff here. Namely, fill in the parameters based on info in the req object

// Trigger the widget model to perform a CRUD operation
handler.triggerModel('widget', 'read', parameters);

// End the handler
handler.end();
};

// Export the handler
module.exports = handler;
`

$3

Sample models/widget.js:

`js
var mongoose = require('mongoose');
var api = require('roux');
var model = new api.model();

// Define the events the model should bind to
model.bindTo('widget', 'read', 'start');

// Primary logic for the model
model.functions.start = function(req,res, parameters){
var resource = mongoose.model('widgets');

var data = {};
// Do stuff here. Namely, get the data from the widget model using the parameters specified.

// Add a payload to the response
api.response.addPayload(data);

model.end();
};

``

Conventions / Best Practices

// Coming soon

License

The MIT License (MIT)

Copyright (c) 2015 Malcolm Diggs

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.