express-jefferson

Declarative Express Application Wiring

express-jefferson is a library for declaratively describing RESTful services and configuring express apps.

// main.js
var express = require('express'),
    jefferson = require('express-jefferson'),
    app = express(),    
    conf = {
        proxies: [logInvocations, resolvePromises],
        pre: {
            safe: [markReadOnly],
            unsafe: [authenticate]
        },
        post: {
            all: [addHaetoasLinks, transmitResponse]
        },
        params: {
            beerId: getBeerById,
            userId: getUserById
        },
        routes: {
            '/beers': {
                get: [getBeerList, send.json]
                post: [createBeer, send.json]
            },
            '/beers/:beerId': 
                get: [send.json]
                put: [editBeer, send.json]
            }
        }
    };
    
jefferson(app, conf);

Configuration

• routes - (required) - A map of routes by route path. Each object in the map contains a map of method to middleware function array.

routes: {
    {
        '/my-path': {
            get: [getThings, send]
            past: [makeThing, send]
        },
        '/my-path/:id': {
            get: [getThing, send]
        }
    }
}

• aliases: (optional) - A map of alias-name to handler chain. Routes may use these aliases in lieu of repeated function groups.

aliases: {
    'processAndTransmit': [deletePassword, addHateoasLinks, transmitEntity]
},
routes: {
    '/users/:id': {
        get: [getUser, 'processAndTransmit']
    }
}

• pre: (optional) - (object) Boilerplate section of pre-middleware functions (see below)
• post: (optional) - (object) Boilerplate section of post-middleware functions (see below)
• proxies: (optional) - An array of proxy objects invoked around all middleware functions in order. (see below)
• params: (optional) - A map of path-parameter name to resolver functions.

params: {
    userId: (req, res, next) => {
        req.user = userStore.findUser(req.params.userId);
        next();
    }
}
routes: {
    '/users/:userId': {
        get: [(req, res, next) => res.send(req.user)]
    }
}

• enable: (optional) - An array of settings strings to enable (http://expressjs.com/api.html#app.enable)

enable: ['trust proxy', 'etag']

• disable: (optional) - An array of settings strings to disable (http://expressjs.com/api.html#app.disable)

disable: ['trust proxy', 'etag']

• engines: (optional) - An map of template rendering engines. { <extension>: <engineFunction> }

engines: {
    'jade': require('jade').__express
}

• locals: (optional) - (object) An object that will populate app.locals (http://expressjs.com/api.html#app.locals) { <localName>: <localValue> }

locals: {
    'a': true
}

• settings: (optional) - (object) An object that will be iterated to populate application settings using app.set (http://expressjs.com/api.html#app.set) { <settingName>: <settingValue> }

settings: {
    'a': true
}

Boilerplate Config Sections (pre/post):

• all: (optional) - An array of middleware to be applied to all endpoints.
• safe: (optional) - An array of middleware to be applied to all safe endpoints (GET, HEAD, OPTIONS).
• unsafe: (optional) - An array of middleware to be applied to all unsafe endpoints (not GET, HEAD, OPTIONS).
• method: (optional, object) - On object of method-name to handler list.

pre: {
    all: [trackInvocation],
    unsafe: [authenticate],
    method: {
        get: [markRequestReadOnly]
    }
}

Proxy Definition:

• name: - The name of the proxy.
• init: - A function that accepts a middleware function, augments it, and returns the augmented proxy.
• conf: (optional) - A configuration object that is passed to the proxy init function.

{
    name: 'Logger',
    init (delegate) {
        return (req, res, next) => {
            console.log("invoking middleware function");
            delegate(req, res, next);
        }
    }
}

Proxies provided in Jefferson

Promise-Based Middleware Proxy

require('express-jefferson/proxies/promise-handler')

This proxy accepts promise-based middleware (middleware that accepts two arguments) and wraps them in a promise chain before invoking next().

Config Options:

• haltCondition (optional) - a predicate function that accepts the request and response. If it returns a truthy value, then the middleware chain will be halted.

Trace Logger Middleware Proxy

require('express-jefferson/proxies/trace-logger')

This proxy logs invocations of middleware using the debug library.

Config Options:

• logger (optional) - the name of the debug logger to use. Default is "jefferson:trace-logger"