datastore: use transaction object

lib/datastore/index.js

@@ -211,7 +211,7 @@ var util = require('../common/util.js');
  *
  *   datastore.runQuery(query, function(err, entities, info) {
  *     if (err) {
- *       // Error handling omitted...
+ *       // Error handling omitted.
  *       return;
  *     }
  *
@@ -301,26 +301,36 @@ var util = require('../common/util.js');
  * // <h3>Transactions</h3>
  * //
  * // Complex logic can be wrapped in a transaction with
- * // {module:datastore#runInTransaction}. All queries and updates run within
+ * // {module:datastore#transaction}. All queries and updates run within
  * // the transaction will be applied when the `done` function is called.
  * //-
- * datastore.runInTransaction(function(transaction, done) {
+ * var transaction = datastore.transaction();
+ *
+ * transaction.run(function(err) {
+ *   if (err) {
+ *     // Error handling omitted.
+ *   }
+ *
  *   var key = datastore.key(['Company', 'Google']);
  *
  *   transaction.get(key, function(err, data) {
+ *     if (err) {
+ *       // Error handling omitted.
+ *     }
+ *
  *     data.symbol = 'GOOG';
  *
  *     transaction.save({
  *       key: key,
  *       data: data
  *     });
  *
- *     done();
+ *     transaction.commit(function(err) {
+ *       if (!err) {
+ *         // Transaction committed successfully.
+ *       }
+ *     });
  *   });
- * }, function(err) {
- *   if (!err) {
- *     // Transaction run successfully.
- *   }
  * });
  */
 function Datastore(options) {
@@ -500,53 +510,13 @@ Datastore.prototype.key = function(options) {
   return new entity.Key(options);
 };
 
-/**
- * Run a function in the context of a new transaction. Transactions allow you to
- * perform multiple operations, committing your changes atomically. When you are
- * finished making your changes within the transaction, run the done() function
- * provided in the callback function to commit your changes. See an example
- * below for more information.
- *
- * @param {function} fn - The function to run in the context of a transaction.
- * @param {module:datastore/transaction} fn.transaction - The Transaction.
- * @param {function} fn.done - Function used to commit changes.
- * @param {function} callback - The callback function.
- * @param {?error} callback.err - An error returned while making this request
- *
- * @example
- * datastore.runInTransaction(function(transaction, done) {
- *   // From the `transaction` object, execute datastore methods as usual.
- *   transaction.get(datastore.key(['Company', 123]), function(err, entity) {
- *     if (err) {
- *       transaction.rollback(done);
- *       return;
- *     }
- *
- *     // Call `done` when you're ready to commit your changes.
- *     done();
- *   });
- * }, function(err, apiResponse) {});
- */
-Datastore.prototype.runInTransaction = function(fn, callback) {
-  var newTransaction = this.createTransaction_();
-
-  newTransaction.begin_(function(err, resp) {
-    if (err) {
-      callback(err, resp);
-      return;
-    }
-
-    fn(newTransaction, newTransaction.commit_.bind(newTransaction, callback));
-  });
-};
-
 /**
  * Create a new Transaction object.
  *
  * @return {module:datastore/transaction}
  * @private
  */
-Datastore.prototype.createTransaction_ = function() {
+Datastore.prototype.transaction = function() {
   return new Transaction(this);
 };
 

lib/datastore/request.js

@@ -103,9 +103,23 @@ function DatastoreRequest() {}
  * //-
  * // Or, if you're using a transaction object.
  * //-
- * datastore.runInTransaction(function(transaction, done) {
+ * var transaction = datastore.transaction();
+ *
+ * transaction.run(function(err) {
+ *   if (err) {
+ *     // Error handling omitted.
+ *   }
+ *
  *   transaction.allocateIds(incompleteKey, 100, function(err, keys) {
- *     done();
+ *     if (err) {
+ *       // Error handling omitted.
+ *     }
+ *
+ *     transaction.commit(function(err) {
+ *       if (!err) {
+ *         // Transaction committed successfully.
+ *       }
+ *     });
  *   });
  * });
  *
@@ -170,9 +184,19 @@ DatastoreRequest.prototype.allocateIds = function(incompleteKey, n, callback) {
  * //-
  * // Or, if you're using a transaction object.
  * //-
- * datastore.runInTransaction(function(transaction, done) {
- *   transaction.delete(key, function(err, apiResp) {
- *     done();
+ * var transaction = datastore.transaction();
+ *
+ * transaction.run(function(err) {
+ *   if (err) {
+ *     // Error handling omitted.
+ *   }
+ *
+ *   transaction.delete(key);
+ *
+ *   transaction.commit(function(err) {
+ *     if (!err) {
+ *       // Transaction committed successfully.
+ *     }
  *   });
  * });
  *
@@ -238,9 +262,23 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  * //-
  * // Or, if you're using a transaction object.
  * //-
- * datastore.runInTransaction(function(transaction, done) {
+ * var transaction = datastore.transaction();
+ *
+ * transaction.run(function(err) {
+ *   if (err) {
+ *     // Error handling omitted.
+ *   }
+ *
  *   transaction.get(key, function(err, entity) {
- *     done();
+ *     if (err) {
+ *       // Error handling omitted.
+ *     }
+ *
+ *     transaction.commit(function(err) {
+ *       if (!err) {
+ *         // Transaction committed successfully.
+ *       }
+ *     });
  *   });
  * });
  *
@@ -415,9 +453,23 @@ DatastoreRequest.prototype.insert = function(entities, callback) {
  * //-
  * // Or, if you're using a transaction object.
  * //-
- * datastore.runInTransaction(function(transaction, done) {
+ * var transaction = datastore.transaction();
+ *
+ * transaction.run(function(err) {
+ *   if (err) {
+ *     // Error handling omitted.
+ *   }
+ *
  *   transaction.runQuery(query, function(err, entities) {
- *     done();
+ *     if (err) {
+ *       // Error handling omitted.
+ *     }
+ *
+ *     transaction.commit(function(err) {
+ *       if (!err) {
+ *         // Transaction committed successfully.
+ *       }
+ *     });
  *   });
  * });
  *