Merge pull request #96 from stephenplusplus/transactions

datastore: refactor transaction & datastore.

README.md

@@ -242,18 +242,18 @@ ds.allocateIds(['ns-test', 'Company', null], 100, function(err, keys) {
 Datastore has support for transactions. Transactions allow you to perform
 multiple operations and commiting your changes atomically.
 
-`runInTransaction` is a utility method to work with transactions.
+`transaction` is a utility method to work with transactions.
 
 ~~~~ js
-ds.runInTransaction(function(t, done) {
- // perform actions via t.
- t.get(key, function(err, obj) {
+ds.transaction(function(transaction, done) {
+ // call datastore methods as usual
+ // when you're done, call done
+ transaction.get(key, function(err, entity) {
  if (err) {
- t.rollback(done);
+ transaction.rollback(done);
  return;
  }
- // do any other operation with obj.
- // when you're done, call done.
+ // do any other operations with entity.
  done();
  });
 }, function(err) {
@@ -262,18 +262,11 @@ ds.runInTransaction(function(t, done) {
 });
 ~~~~
 
-The transaction will be auto committed if it's not rollbacked or
-commited when done is called. Transactions support the following
-CRUD and transaction related operations.
-
-* t.get(key, callback)
-* t.getAll(keys, callback)
-* t.save(key, obj, callback)
-* t.saveAll(keys, objs, callback)
-* t.del(key, callback)
-* t.delAll(keys, callback)
-* t.rollback(callback)
-* t.commit(callback)
+* transaction.get([key], callback);
+* transaction.save([{ key: '', data: {} }], callback);
+* transaction.delete([key], callback);
+* transaction.rollback(callback);
+* transaction.commit(callback);
 
 ### Google Cloud Storage
 

lib/datastore/dataset.js

@@ -0,0 +1,135 @@
+/**
+ * Copyright 2014 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+var conn = require('../common/connection.js');
+var entity = require('./entity.js');
+var Transaction = require('./transaction.js');
+var Query = require('./query.js');
+var util = require('../common/util.js');
+
+var SCOPES = [
+ 'https://www.googleapis.com/auth/datastore',
+ 'https://www.googleapis.com/auth/userinfo.email'
+];
+
+/**
+ * Creates a new dataset with the provided options.
+ * @param {object} opts Dataset identifier options.
+ * @param {string} opts.id Dataset ID, this is your project ID
+ * from Google Developers Console.
+ * @param {string} opts.keyFilename Path to the JSON key file downloaded from
+ * Google Developers Console.
+ */
+function Dataset(opts) {
+ opts = opts || {};
+ var id = opts.projectId || '';
+
+ if (id.indexOf('s~') === -1 && id.indexOf('e~') === -1) {
+ id = 's~' + id;
+ }
+
+ this.connection = new conn.Connection({
+ keyFilename: opts.keyFilename,
+ scopes: SCOPES
+ });
+ this.id = id;
+ this.transaction = this.createTransaction();
+}
+
+/**
+ * Creates a query from the current dataset to query the specified
+ * kinds.
+ *
+ * Example usage:
+ * ds.createQuery(['Lion', 'Chimp'])
+ * ds.createQuery('zoo', ['Lion', 'Chimp'])
+ *
+ * @param {string=} ns Optional namespace to query entities from.
+ * @param {Array<String>} kinds A list of kinds to query.
+ * @return {Query}
+ */
+Dataset.prototype.createQuery = function(ns, kinds) {
+ if (!kinds) {
+ kinds = ns;
+ ns = '';
+ }
+ kinds = util.arrayize(kinds);
+ return new Query(ns, kinds);
+};
+
+/**
+ * Gets the object identified with the provided key.
+ * @param {Key} key A non-incomplete key.
+ * @param {Function} callback The callback function.
+ */
+Dataset.prototype.get = function(key, callback) {
+ this.transaction.get(key, callback);
+};
+
+Dataset.prototype.save = function(key, obj, callback) {
+ this.transaction.save(key, obj, callback);
+};
+
+Dataset.prototype.delete = function(key, callback) {
+ this.transaction.delete(key, callback);
+};
+
+Dataset.prototype.runQuery = function(q, callback) {
+ this.transaction.runQuery(q, callback);
+};
+
+Dataset.prototype.runInTransaction = function(fn, callback) {
+ var newTransaction = this.createTransaction();
+ newTransaction.begin(function(err) {
+ if (err) {
+ return callback(err);
+ }
+ fn(newTransaction, newTransaction.finalize.bind(newTransaction, callback));
+ });
+};
+
+Dataset.prototype.allocateIds = function(incompleteKey, n, callback) {
+ if (entity.isKeyComplete(incompleteKey)) {
+ throw new Error('An incomplete key should be provided.');
+ }
+ var incompleteKeys = [];
+ for (var i = 0; i < n; i++) {
+ incompleteKeys.push(entity.keyToKeyProto(this.id, incompleteKey));
+ }
+ this.transaction.makeReq(
+ 'allocateIds', { keys: incompleteKeys }, function(err, resp) {
+ if (err) {
+ return callback(err);
+ }
+ var keys = [];
+ resp.keys.forEach(function(k) {
+ keys.push(entity.keyFromKeyProto(k));
+ });
+ callback(null ,keys);
+ });
+};
+
+Dataset.prototype.createTransaction = function() {
+ return new Transaction(this.connection, this.id);
+};
+
+/**
+ * Exports Dataset.
+ * @type {Dataset}
+ */
+module.exports = Dataset;