Discussion: introduce new events API #524

Problem

Right now there are two event APIs:

1. The dataCallback and shouldSendCallback events, which can be specified using Raven.config or using their own dedicated set methods:
   • Raven.setDataCallback
   • Raven.setShouldSendCallback
2. An undocumented API using document-level DOM events:
   • document.addEventListener('ravenHandle', function () { ... });
   • document.addEventListener('ravenSuccess', function () { ... });
   • document.addEventListener('ravenFailure', function () { ... });

Difficulties with this system:

• The two APIs cover almost completely different events, e.g. ravenHandle fires only on handled exceptions (read: not messages), whereas dataCallback fires for every sent event
• Can only specify a single callback for dataCallback and shouldSendCallback [Add support for multiple callback listeners #428, dataCallback overwritten by angular plugin #477]
• DOM-level events don't work in certain environments, e.g. React Native which doesn't have a DOM/document
• there is very little different between dataCallback and shouldSendCallback – they can both mutate the data object; the only difference is that only shouldSendCallback can "cancel" the sending of an event – can these be combined?
• introducing new events like dataCallback and shouldSendCallback means adding more set API methods

Proposed solution

A new events API that looks something like this (aka very similar to Backbone.Events):

var handler = function () { /* do something */ };

Raven.on('send', handler); // set a handler
Raven.on('send', function () { /* do something else */ }); // set a different handler

Raven.off('send', handler); // remove a handler
Raven.off('send'); // remove all handlers

This API will also support chaining (like most other Raven methods), so you can do:

Raven
  .config('<your dsn>')
  .on('send', function () { /* do something */ })
  .install();

Proposed list of supported events:

• send – fires when Raven is about to send data
  • first argument to handler is Raven's data object, which supports mutation
  • returning false cancels send (like shouldSendCallback)
• success – fires when Raven transport is successful
• failure – fires when Raven transport fails

Proposed rollout

We introduce this API in Raven.js 3.0, but continue supporting the old API methods – albeit with a deprecation notice that outputs using console.warn (similar to how React deprecates methods between minor revs).

In 4.0 (whenever that comes out), we remove it entirely.

Possible discussion points

• should events be "read only", or should they have the ability to alter the control flow of Raven.js (see the proposed send event)
• should we just stay the course with what we have, and deprecate the DOM events in favor of events similar to dataCallback, e.g. setSuccessCallback, setFailureCallback, setHandleCallback?

Anyways, this is what I'm thinking. Thoughts? Feedback?

Note there's already a partial PR up that implements most of this (#521).