# Command Stack

Command Stack is a simple router intended for internal routing of application state (and not for http requests or browser pushState). 

The idea is to enforce a familiar route driven, synchronous control flow to your application to ensure consistent handling of state.   

Asynchronous functions are accommodated with standard callback pattern and modularity encouraged via middleware. 

## Install
```
npm install --save command-stack
```

## Usage
```
var cs = require('command-stack')

cs.listen('/', function(state, next) {
   //functionality here
   next(null, state)
})
```

The route definition above itself is middleware, we simply listen for the desired route and call next() 

And when you are ready to invoke the route: 

```
cs.fire('/', state, function(err, newState) {
  //any function listening for the given route will do it's thing...
  //each listener function is fired in the order it was defined.
  //the callback from fire receives the final result after all listener functions have completed
  //so if the fire command was called from within
  //another fire event already underway, you can now pass state up to the original stack again.  
})
```

Because of the guaranteed synchronous execution of the middleware stack you can nest commands that 'go horizontal' from within this stack; without breaking or complicating the overall control flow of the application. Ex: 

```
cs.listen('/action', function(state, next) {
    //Branch off and fire another stack: 
    cs.fire('/another-action', state, function(err, newState) { 
        next(null, newState) //< Return the modified state to original stack.
    })
})
```

Each fire the state object is modified to include a req property with the corresponding route and parameters.  Ex: state.req


###  Modularity

The current hypothesis is that now you have a super simple control flow to your application you can focus on building actual functionality via modules that stack together as middleware.  Modules for your app can simply drop in as a function that runs an cstack.listener or set of cstack.listeners. 


### TODOs
- Document more clearly the state.req object
- Write tests
- Get catch-all wildcard listeners ie: cstack.listen('*') working as expected