docs(transactions): add example of aborting a transaction

Fix #7113

docs/transactions.jade

@@ -35,6 +35,21 @@ block content
     [require:transactions.*basic example]
     ```
 
+    ## Aborting a Transaction
+
+    The most important feature of transactions is the ability to roll back _all_
+    operations in the transaction using the [`abortTransaction()` function](https://docs.mongodb.com/manual/reference/method/Session.abortTransaction/).
+
+    Think about [modeling a bank account in Mongoose](https://thecodebarbarian.com/a-node-js-perspective-on-mongodb-4-transactions.html#transactions-with-mongoose).
+    To transfer money from account `A` to account `B`, you would decrement
+    `A`'s balance and increment `B`'s balance. However, if `A` only has a balance
+    of $5 and you try to transfer $10, you want to abort the transaction and undo
+    incrementing `B`'s balance.
+
+    ```javascript
+    [require:transactions.*abort]
+    ```
+
     ## With Mongoose Documents and `save()`
 
     If you get a [Mongoose document](/docs/documents.html) from [`findOne()`](/docs/api.html#findone_findOne)

test/docs/transactions.test.js

@@ -75,6 +75,24 @@ describe('transactions', function() {
       then(doc => assert.ok(doc));
   });
 
+  it('abort', function() {
+    // acquit:ignore:start
+    const Customer = db.model('Customer0', new Schema({ name: String }));
+    // acquit:ignore:end
+    let session = null;
+    return Customer.createCollection().
+      then(() => Customer.startSession()).
+      then(_session => {
+        session = _session;
+        session.startTransaction();
+        return Customer.create([{ name: 'Test' }], { session: session });
+      }).
+      then(() => Customer.create([{ name: 'Test2' }], { session: session })).
+      then(() => session.abortTransaction()).
+      then(() => Customer.countDocuments()).
+      then(count => assert.strictEqual(count, 0));
+  });
+
   it('save', function() {
     const User = db.model('User', new Schema({ name: String }));