feat: emit on route definition

[fed135]

What the feature is

This PR adds a route event on the app that emits whenever a new route is defined.

ex:

var app = express();

app.on('route', function (route) {
    // The route object
});

// Using the route method
app.route('/:foo')
    .get(function(req, res) {
      res.send(req.params.foo);
    }); // Will trigger
    
// Using direct methods
app.get('/:bar', function(req, res) {
      res.send(req.params.bar);
    }); // Will trigger

Why do we want this

I built a few express plugins and often find myself monkey-patching internal methods in order to get info about the routes an app has. There are already events that can be used by plugin developers such as mount.

In effect, this could offer a clean interface for plugin developers and reduce friction when trying to release new versions of Express.

Any potential drawbacks

Since this is a new event, it should not impact existing applications. It does not expose new information about the application so the attack surface should also remain unchanged.

There would of course need to be some updates to the published documentation to add this new event.

Status of this PR

I currently have a suggested implementation, albeit one I'm not super fond of. It is fairly straightforward to emit the event on direct method calls since the calls are already overloaded in express, but router objects are directly handled by the router dependency. The solution I found was to defer the emit in the router call, which is used in all cases.

I have created some tests to validate that the events are triggered.

[krzysdz]

I built a few express plugins and often find myself monkey-patching internal methods in order to get info about the routes an app has.

Wouldn't something like pillarjs/router#174 solve your particular problem. Getting the list of all routes is something that is frequently requested (I just found a feature request from 2011) and pillarjs/router#174 tries to address this.

[fed135]

@krzysdz This would be an interesting approach to my issues. Thank you for bringing it to my attention.

Edit: Actually, reading into the details of the proposed changes, it seems the getRoutes method would not return as much info as I'd expected. Exposing the entire Route object, like in my implementation, exposes the handler stack, which is often times useful for plugins.

I'll comment over there to see if there's interest in exposing the handler stack or if there's potential synergies between our efforts.