Add batch op events

This change adds two events:

 - `before op batch` - fired once before any set of ops is applied.
 - `op batch` - fired once after any set of ops is applied. This may
   follow multiple `op` events if the op had multiple `json0` components

This is a non-breaking change that should allow clients to process ops
in their entirety.

There has already been some discussion around this:

 - #129
 - #396

This is a much simpler approach than the existing pull request. Here we
try not to change existing behaviour, and only add new, non-breaking
events.

Motivation for such an event would include clients applying some form of
validation logic, which doesn't make sense if an op is shattered.

For example, consider a client that wants to ensure a field
`mustBePresent` is always populated:

```js
doc.on('op', () => {
  if (!doc.data.mustBePresent) throw new Error('invalid');
});

remoteDoc.submitOp([
  {p: ['mustBePresent', 0], sd: 'existing value'},
  {p: ['mustBePresent', 0], si: 'new value'},
]);
```

In the above example, the submitted op is clearly attempting to perform
a replacement. However, the receiving `doc` only receives this
replacement in parts, so it looks like the document reaches an invalid
state, when actually the submitted op is perfectly valid.

In this case we `throw`, but we could have also attempted to populate
with a default value, which could interfere with the desired value.

This change fixes the above issue, because now we can just listen for
the `op batch` event, and consider the document once all the components
of a given op have been applied.

Author: Alec Gibson

README.md

@@ -364,6 +364,12 @@ An operation is about to be applied to the data. `source` will be `false` for op
 `doc.on('op', function(op, source) {...})`
 An operation was applied to the data. `source` will be `false` for ops received from the server and defaults to `true` for ops generated locally.
 
+`doc.on('before op batch'), function(op, source) {...})`
+A potentially multi-part operation is about to be applied to the data. `source` will be `false` for ops received from the server and defaults to `true` for ops generated locally.
+
+`doc.on('op batch'), function(op, source) {...})`
+A potentially multi-part operation was applied to the data. `source` will be `false` for ops received from the server and defaults to `true` for ops generated locally.
+
 `doc.on('del', function(data, source) {...})`
 The document was deleted. Document contents before deletion are passed in as an argument. `source` will be `false` for ops received from the server and defaults to `true` for ops generated locally.
 

lib/client/doc.js

@@ -581,6 +581,10 @@ Doc.prototype._otApply = function(op, source) {
       );
     }
 
+    // NB: If we need to add another argument to this event, we should consider
+    // the fact that the 'op' event has op.src as its 3rd argument
+    this.emit('before op batch', op.op, source);
+
     // Iteratively apply multi-component remote operations and rollback ops
     // (source === false) for the default JSON0 OT type. It could use
     // type.shatter(), but since this code is so specific to use cases for the
@@ -614,6 +618,7 @@ Doc.prototype._otApply = function(op, source) {
         this.data = this.type.apply(this.data, componentOp.op);
         this.emit('op', componentOp.op, source, op.src);
       }
+      this.emit('op batch', op.op, source);
       // Pop whatever was submitted since we started applying this op
       this._popApplyStack(stackLength);
       return;
@@ -630,6 +635,7 @@ Doc.prototype._otApply = function(op, source) {
     // For ops from other clients, this will be after the op has been
     // committed to the database and published
     this.emit('op', op.op, source, op.src);
+    this.emit('op batch', op.op, source);
     return;
   }
 

test/client/doc.js

@@ -1,6 +1,7 @@
 var Backend = require('../../lib/backend');
 var expect = require('chai').expect;
 var async = require('async');
+var errorHandler = require('../util').errorHandler;
 
 describe('Doc', function() {
   beforeEach(function() {
@@ -266,6 +267,62 @@ describe('Doc', function() {
         verifyConsistency(doc, doc2, doc3, handlers, done);
       });
     });
+
+    it('emits batch op events for a multi-component local op', function(done) {
+      var doc = this.doc;
+      var beforeOpBatchCount = 0;
+
+      var submittedOp = [
+        {p: ['tricks'], oi: ['fetching']},
+        {p: ['tricks', 0], li: 'stand'}
+      ];
+
+      doc.on('before op batch', function(op, source) {
+        expect(op).to.eql(submittedOp);
+        expect(source).to.be.true;
+        beforeOpBatchCount++;
+      });
+
+      doc.on('op batch', function(op, source) {
+        expect(op).to.eql(submittedOp);
+        expect(source).to.be.true;
+        expect(beforeOpBatchCount).to.equal(1);
+        expect(doc.data).to.eql({tricks: ['stand', 'fetching']});
+        done();
+      });
+
+      doc.submitOp(submittedOp, errorHandler(done));
+    });
+
+    it('emits batch op events for a multi-component remote op', function(done) {
+      var doc = this.doc;
+      var doc2 = this.doc2;
+      var beforeOpBatchCount = 0;
+
+      var submittedOp = [
+        {p: ['tricks'], oi: ['fetching']},
+        {p: ['tricks', 0], li: 'stand'}
+      ];
+
+      doc.on('before op batch', function(op, source) {
+        expect(op).to.eql(submittedOp);
+        expect(source).to.be.false;
+        beforeOpBatchCount++;
+      });
+
+      doc.on('op batch', function(op, source) {
+        expect(op).to.eql(submittedOp);
+        expect(source).to.be.false;
+        expect(beforeOpBatchCount).to.equal(1);
+        expect(doc.data).to.eql({tricks: ['stand', 'fetching']});
+        done();
+      });
+
+      async.series([
+        doc.subscribe.bind(doc),
+        doc2.submitOp.bind(doc2, submittedOp)
+      ], errorHandler(done));
+    });
   });
 
   describe('submitting ops in callbacks', function() {