node package manager
Love JavaScript? Your insights can make it even better. Take the 2017 JavaScript Ecosystem Survey »



Onion is a simple and flexible middleware stack that enables you to add a middleware layer to just about anything.




npm install onion

Stacking and Peeling


Stacking some skins is simple just get you a new onion

Onion = require 'onion'
onion = new Onion
onion.stack (name, next) ->
    console.log 'Hello'
onion.stack (name, next) ->
    console.log name+'!'
onion.peel 'World'

Now you could peel that onion

onion.peel 'World'

and get


More Complex


It is also possible to stack and peel just for specific events. Just give stack a name and use peelFor like

Onion = require 'onion'
onion = new Onion
onion.stack 'foo'(next) ->
    console.log 'foo'
onion.stack 'bar'(next) ->
    console.log 'bar'
onion.peelFor 'foo'
onion.peelFor 'bar'

and get



The innermost function is called if there are no skins left on the onion and the last middleware calls next(). This could be used to catch unwanted behaviour or reply with an 404 status code when handling HTTP requests.

By default the innermost function does nothing.

Onion = require 'onion'
onion = new Onion
onion.stack (next) ->
    console.log 'just calling next'
just calling next

If we replace the innermost function with something useful, we could get

onion.innermost = ->
    console.log 'gives fancy text'
just calling next
gives fancy text

Error Handling

The error skin is a special middleware that is executed if a middleware throws an error. The error middleware can then decide how to handle the error. The error is given to the middleware after the given arguments, that means that the error middleware has the same signature as any other middleware, but with an error object appended. For example

@error = (args..., next, error) ->
    console.log error.message

will print the error message to the console and call the next middleware. By calling next the error can be ignored, thus the next middleware will be called.

The flexible way

Onion = require 'onion'
onion = new Onion
onion.construct ->
    skin1 = (next) ->
        console.log 'skin 1'
    skin2 = (next) ->
        console.log 'skin 2'
    return [skin1skin2]

Skin Constructor

The construct method takes a function that returns the middleware (the so called skin constructor). The given function is executed in the scope of the onion, to provide a flexible way for e.g. adding specific methods to the onion before a middleware gets stacked. For example

skinconstructor = ->
    @foobar = 'foobar'
    skin = (val, next) ->
        if val is 'foobar'
            return 'it is foobar!'

will add the attribute foobar to the onion and stack the middleware skin that returns 'it is foobar!' if the given value was foobar.

onion.construct skinconstructor
    onion.foobar        # ~> 'foobar' 
    onion.peel 'barfoo' # ~> undefined 
    onion.peel 'foobar' # ~> 'it is foobar!' 

To summarize all possibilities to add a middleware:

{ event: 'foo'skin: func }
{ event: ['foo','bar']skin: func }
{ event: 'foo'skin: [func1func2}
{ event: ['foo','bar'][func1func2}

and any multiples from above in an array, e.g.:

[func1{ event: ['foo''bar']skin: func2 }]

where func, func1 and func2 are middlewares.

Similar projects

  • Connect - Middleware stack for nodejs httpServer requests.
  • Zen - General module stack engine for javascript.
  • Rack - Http middleware stack for ruby.


Onion is distributed under the MIT license. See LICENCE file.