onion

Simple and flexible middleware stack that enables you to add a middleware layer to just about anything

npm install onion
32 downloads in the last month

Onion

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

Logo

Usage

Installation

npm install onion

Stacking and Peeling

Simple

Stacking some skins is simple just get you a new onion

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

onion.stack (name, next) ->
    console.log name+'!'

onion.peel 'World'

Now you could peel that onion

onion.peel 'World'

and get

Hello
World!

More Complex

Events

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

foo
bar

Innermost

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'
    next()
onion.peel()
just calling next

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

onion.innermost = ->
    console.log 'gives fancy text'
onion.peel()
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
    next()

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'
        next()

    skin2 = (next) ->
        console.log 'skin 2'
        next()

    return [skin1, skin2]

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!'
        else
            next()
        skin

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:

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

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.

Licence

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

npm loves you