connect-composer

Connect and reuse connect/ express middlewares

Compose connect/ express compatible middlewares and reuse or extend them.

Features:

• Stack middlewares
• Use connect middlewares without or with connect, express
• Trap errors within middlewares using function (err, req, res, next) functions
• Safely catch errors within middlewares
• Modify and reuse existing middlewares

Table of Contents

• Description
  • Stack Middlewares
  • Stack composed middlewares
  • Trap and catch errors
  • Manipulate and reuse middlewares
• Example
• Methods
• compose() ⇒ function
  • compose.before ⇒ function
  • compose.after ⇒ function
  • compose.replace ⇒ function
  • compose.remove ⇒ function
  • compose.push ⇒ function
  • compose.unshift ⇒ function
  • compose.decompose(middlewares) ⇒ Array
  • compose.clone() ⇒ function
  • compose.noop()
• Contribution and License Agreement
• License
• References

Description

Stack Middlewares

This module allows to join middlewares together:

var compose = require('connect-composer')
var req = { test: [] }
var res = {}
var middlewares1 = [
  function (req, res, next) { req.test.push('one'); next() },
  function (req, res, next) { req.test.push('two'); next() }
]
var middlewares2 = [
  function (req, res, next) { req.test.push('three'); next() },
  function (req, res, next) { req.test.push('four'); next() }
]
// create a new middleware
var newMiddlewares = compose(middlewares1, middlewares2)
// run new composed middleware
newMiddlewares(req, res, function () {
  console.log(req.test) // < [ 'one', 'two', 'three', 'four' ]
})

Stack composed middlewares

You can also stack composed middlewares:

var compose = require('connect-composer')
var req = { test: [] }
var res = {}
// pass as Array
var middlewares1 = compose([
  function (req, res, next) { req.test.push('one'); next() },
  function (req, res, next) { req.test.push('two'); next() }
])
// or by Argument
var newMiddlewares = compose(
  middlewares1,
  function (req, res, next) { req.test.push('three'); next() },
  function (req, res, next) { req.test.push('four'); next() }
)
// run new composed middleware
newMiddlewares(req, res, function () {
  console.log(req.test) // < [ 'one', 'two', 'three', 'four' ]
})

Trap and catch errors

Traps errors and catches errors within middlewares (prevents server from crashing)

var compose = require('connect-composer')
var req = { test: [] }
var res = {}
var middlewares = compose(
  function (req, res, next) { req.test.push('one'); next() },
  function (req, res, next) {
    next('badly')           // middleware calls `next` with error parameter
  },
  function (req, res, next) {
    req.test.push('two')    // is never called
    next()
  },
  function (err, req, res, next) { // error is trapped here; function has arity 4
    console.log(err + ' trapped')  // < badly trapped
    next()                  // continue with the processing
  },
  function (req, res, next) { req.test.push('three'); next() },
  function (req, res, next) {
    if (1) throw new Error('another error') // middleware calls `next` with error parameter
    next()
  },
  function (req, res, next) {
    req.test.push('four')   // is never called
    next()
  }
)
// run new composed middleware
middlewares(req, res, function (err) {
  console.log(err)      // < [Error: another error] is catched
  console.log(req.test) // < [ 'one', 'three' ]
})

Manipulate and reuse middlewares

Use the following methods to change an existing composed middleware

• unshift(middlewares) prepend middlewares to the front of the stack
• push(middlewares) push middlewares to the end of the stack
• before(selector, middlewares) insert middlewares before selector
• after(selector, middlewares) insert middlewares after selector
• replace(selector, middlewares) replace middlewares with name selector with middlewares
• remove(selector) remove middlewares with name selector
• clone() clone composed middlewares

var compose = require('connect-composer')
var res = {}
var initial = {
  two: function (req, res, next) { req.test.push('two'); next() },
  four: function (req, res, next) { req.test.push('four'); next() }
}
var others = {
  one: function one (req, res, next) { req.test.push('one'); next() },
  three: function three (req, res, next) { req.test.push('three'); next() },
  five: function othersFive (req, res, next) { req.test.push('five'); next() },
  six: function six (req, res, next) { req.test.push('six'); next() },
  seven: { seven: function (req, res, next) { req.test.push('seven'); next() } },
  eight: function (req, res, next) { req.test.push('eight'); next() }
}
// create a composed middleware
var composed = compose(initial)
 
// do some manipulation
composed.unshift(others.one)              // prepend
composed.push(others.five)                // append
composed.before('four', others.three)     // insert before
composed.after('othersFive', others.six)  // insert after
composed.after('six', others.seven)
 
// named functions become named middleware functions
console.log(composed.stack) // [ { one: [Function: one] },
                            //   { two: [Function] },
                            //   { three: [Function: three] },
                            //   { four: [Function] },
                            //   { othersFive: [Function: othersFive] },
                            //   { six: [Function: six] },
                            //   { seven: [Function] } ]
 
// lets clone the middlewares
var composed2 = composed.clone() // clone the middlewares; same as `compose(composed)`
composed2.remove('six').remove('two').remove('four') // remove middlewares
 
// do some more manipulation
composed.replace('seven', others.eight)   // replace middleware seven with eight
 
// run new composed middleware
var req = { test: [] }
composed(req, res, function () {
  console.log(4, req.test) // < [ 'one', 'two', 'three', 'four', 'five', 'six', 'eight' ]
})
 
// run the other composed middleware (with a different request)
var req2 = { test: [] }
composed2(req2, res, function () {
  console.log(5, req2.test) // < [ 'one', 'three', 'five', 'seven' ]
})

Example

Run the examples above with node test/sample.js.

Methods

## compose() ⇒ function compose a new middleware function from multiple middlewares

Returns: function - middleware function

Param	Type
	function | Array | Object

• compose() ⇒ function
  • .before ⇒ function
  • .after ⇒ function
  • .replace ⇒ function
  • .remove ⇒ function
  • .push ⇒ function
  • .unshift ⇒ function
  • .decompose(middlewares) ⇒ Array
  • .clone() ⇒ function
  • .noop()

### compose.before ⇒ function Inserts `middlewares` before each of the named middleware `selector` If `selector` does not match a named middleware the middleware stack stays the same

Kind: static property of compose Returns: function - middleware

Param	Type	Description
selector	String	selector for named middleware
middlewares	Array | Object

### compose.after ⇒ function Inserts `middlewares` after each of the named middleware `selector` If `selector` does not match a named middleware the middleware stack stays the same

Kind: static property of compose Returns: function - middleware

Param	Type	Description
selector	String	selector for named middleware
middlewares	Array | Object

### compose.replace ⇒ function Replaces the named middleware `selector` with `middlewares` If `selector` does not match a named middleware the middleware stack stays the same

Kind: static property of compose Returns: function - middleware

Param	Type	Description
selector	String	selector for named middleware
middlewares	Array | Object

### compose.remove ⇒ function Removes the named middleware `selector` from the stack If `selector` does not match a named middleware the middleware stack stays the same

Kind: static property of compose Returns: function - middleware

Param	Type	Description
selector	String	selector for named middleware

### compose.push ⇒ function Appends `middlewares` to the stack

Kind: static property of compose Returns: function - middleware

Param	Type
middlewares	Array | Object

### compose.unshift ⇒ function Prepends `middlewares` to the stack

Kind: static property of compose Returns: function - middleware

Param	Type
middlewares	Array | Object

### compose.decompose(middlewares) ⇒ Array decompose `obj` into middleware Array Named functions names are used as middleware identifiers

Kind: static method of compose Returns: Array - - array of middlewares {Object|Array}

Param	Type
middlewares	Object | Array | function

### compose.clone() ⇒ function clone the middleware for further manipulation

Kind: static method of compose Returns: function - cloned middleware function

compose.noop()

No operation middleware - just calls next

Kind: static method of compose

Contribution and License Agreement

If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work or correctly attributed with the source of its origin and licence.

License

Copyright (c) 2015 commenthol (MIT License)

See LICENSE for more info.

References

• connect
• express
• LICENSE