From 73ffc36225166e439c1d6ec6498c526eae219597 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Tue, 21 Feb 2017 13:56:56 -0500 Subject: [PATCH] spanner: transaction docs (#2009) --- packages/spanner/src/database.js | 6 +- packages/spanner/src/table.js | 6 +- packages/spanner/src/transaction-request.js | 116 ++++++++++++++++++-- packages/spanner/src/transaction.js | 2 +- test/docs.js | 6 +- 5 files changed, 116 insertions(+), 20 deletions(-) diff --git a/packages/spanner/src/database.js b/packages/spanner/src/database.js index 8939312832a..b6357f970b7 100644 --- a/packages/spanner/src/database.js +++ b/packages/spanner/src/database.js @@ -571,7 +571,7 @@ Database.prototype.run = function(query, options, callback) { * database.runStream(query) * .on('error', function(err) {}) * .on('data', function(row) {}) - * .on('end', function() {}) + * .on('end', function() {}); * * //- * // If you anticipate many results, you can end a stream early to prevent @@ -804,7 +804,7 @@ Database.prototype.table = function(name) { * ') PRIMARY KEY(SingerId)' * ]; * - * database.setSchema(statements, function(err, operation, apiResponse) { + * database.updateSchema(statements, function(err, operation, apiResponse) { * if (err) { * // Error handling omitted. * } @@ -819,7 +819,7 @@ Database.prototype.table = function(name) { * //- * // If the callback is omitted, we'll return a Promise. * //- - * database.setSchema(statements) + * database.updateSchema(statements) * .then(function(data) { * var operation = data[0]; * return operation.promise(); diff --git a/packages/spanner/src/table.js b/packages/spanner/src/table.js index 863dc784dda..96fdb1c5f82 100644 --- a/packages/spanner/src/table.js +++ b/packages/spanner/src/table.js @@ -97,7 +97,6 @@ util.inherits(Table, TransactionRequest); * .then(function() { * // Table created successfully. * }); - * }); */ Table.prototype.create = function(schema, callback) { this.database.createTable(schema, callback); @@ -154,7 +153,10 @@ Table.prototype.create = function(schema, callback) { * // If you anticipate many results, you can end a stream early to prevent * // unnecessary processing and API requests. * //- - * table.createReadStream() + * table.createReadStream({ + * keys: ['1'], + * columns: ['SingerId', 'name'] + * }) * .on('data', function(row) { * this.end(); * }); diff --git a/packages/spanner/src/transaction-request.js b/packages/spanner/src/transaction-request.js index 5fa103f9323..3dc217bf500 100644 --- a/packages/spanner/src/transaction-request.js +++ b/packages/spanner/src/transaction-request.js @@ -119,7 +119,7 @@ TransactionRequest.formatTimestampOptions_ = function(options) { * @return {Stream} * * @example - * database.runTransaction(function(err) { + * database.runTransaction(function(err, transaction) { * if (err) { * // Error handling omitted. * } @@ -150,7 +150,7 @@ TransactionRequest.formatTimestampOptions_ = function(options) { * // Rows are returned as an array of object arrays. Each object has a `name` * // and `value` property. To get a serialized object, call `toJSON()`. * //- - * database.runTransaction(function(err) { + * database.runTransaction(function(err, transaction) { * if (err) { * // Error handling omitted. * } @@ -236,25 +236,41 @@ TransactionRequest.prototype.createReadStream = function(table, query) { * @example * var keys = ['Id1', 'Id2', 'Id3']; * - * database.runTransaction(function(err) { + * database.runTransaction(function(err, transaction) { * if (err) { * // Error handling omitted. * } * - * transaction.deleteRows('Singers', keys, function(err, apiResponse) {}); + * // Queue this mutation until later calling `commit`. + * // Note that a callback is not passed to `deleteRows`. + * transaction.deleteRows('Singers', keys); + * + * // Commit the transaction. + * transaction.commit(function(err) { + * if (!err) { + * // The rows were deleted successfully. + * } + * }); * }); * * //- - * // If the callback is omitted, we'll return a Promise. + * // If you are using a Promise to retrieve the transaction. * //- * database.runTransaction() * .then(function(data) { * var transaction = data[0]; * - * transaction.deleteRows('Singers', keys) - * .then(function(data) { - * var apiResponse = data[0]; - * }); + * // Queue this mutation until later calling `commit`. + * // Note that a callback is not passed to `deleteRows`. + * transaction.deleteRows('Singers', keys); + * + * // Commit the transaction. + * return transaction.commit(); + * }) + * .then(function(data) { + * var apiResponse = data[0]; + * + * // The rows were deleted successfully. * }); */ TransactionRequest.prototype.deleteRows = function(table, keys, callback) { @@ -312,6 +328,13 @@ TransactionRequest.prototype.deleteRows = function(table, keys, callback) { * // Queue this mutation until later calling `commit`. * // Note that a callback is not passed to `insert`. * transaction.insert(row); + * + * // Commit the transaction. + * transaction.commit(function(err) { + * if (!err) { + * // The row was inserted successfully. + * } + * }); * }); * * //- @@ -333,7 +356,34 @@ TransactionRequest.prototype.deleteRows = function(table, keys, callback) { * row, * row2 * ]); + * + * // Commit the transaction. + * transaction.commit(function(err) { + * if (!err) { + * // The rows were inserted successfully. + * } + * }); * }); + * + * //- + * // If you are using a Promise to retrieve the transaction. + * //- + * database.runTransaction() + * .then(function(data) { + * var transaction = data[0]; + * + * // Queue this mutation until later calling `commit`. + * // Note that a callback is not passed to `insert`. + * transaction.insert(row); + * + * // Commit the transaction. + * return transaction.commit(); + * }) + * .then(function(data) { + * var apiResponse = data[0]; + * + * // The row was inserted successfully. + * }); */ TransactionRequest.prototype.insert = function(table, keyVals, callback) { return this.mutate_('insert', table, keyVals, callback); @@ -473,8 +523,14 @@ TransactionRequest.prototype.read = function(table, keyVals, callback) { * // Queue this mutation until later calling `commit`. * // Note that a callback is not passed to `replace`. * transaction.replace('Singers', row); - * }); * + * // Commit the transaction. + * transaction.commit(function(err) { + * if (!err) { + * // The row was replaced successfully. + * } + * }); + * }); * * //- * // If you are using a Promise to retrieve the transaction. @@ -486,6 +542,14 @@ TransactionRequest.prototype.read = function(table, keyVals, callback) { * // Queue this mutation until later calling `commit`. * // Note that a callback is not passed to `replace`. * transaction.replace('Singers', row); + * + * // Commit the transaction. + * return transaction.commit(); + * }) + * .then(function(data) { + * var apiResponse = data[0]; + * + * // The row was replaced successfully. * }); */ TransactionRequest.prototype.replace = function(table, keyVals, callback) { @@ -537,8 +601,14 @@ TransactionRequest.prototype.requestStream = function() {}; * // Queue this mutation until later calling `commit`. * // Note that a callback is not passed to `update`. * transaction.update('Singers', row); - * }); * + * // Commit the transaction. + * transaction.commit(function(err) { + * if (!err) { + * // The row was updated successfully. + * } + * }); + * }); * * //- * // If you are using a Promise to retrieve the transaction. @@ -550,6 +620,14 @@ TransactionRequest.prototype.requestStream = function() {}; * // Queue this mutation until later calling `commit`. * // Note that a callback is not passed to `update`. * transaction.update('Singers', row); + * + * // Commit the transaction. + * return transaction.commit(); + * }) + * .then(function(data) { + * var apiResponse = data[0]; + * + * // The row was updated successfully. * }); */ TransactionRequest.prototype.update = function(table, keyVals, callback) { @@ -583,8 +661,14 @@ TransactionRequest.prototype.update = function(table, keyVals, callback) { * // Queue this mutation until later calling `commit`. * // Note that a callback is not passed to `upsert`. * transaction.upsert('Singers', row); - * }); * + * // Commit the transaction. + * transaction.commit(function(err) { + * if (!err) { + * // The row was updated or inserted successfully. + * } + * }); + * }); * * //- * // If you are using a Promise to retrieve the transaction. @@ -596,6 +680,14 @@ TransactionRequest.prototype.update = function(table, keyVals, callback) { * // Queue this mutation until later calling `commit`. * // Note that a callback is not passed to `upsert`. * transaction.upsert('Singers', row); + * + * // Commit the transaction. + * return transaction.commit(); + * }) + * .then(function(data) { + * var apiResponse = data[0]; + * + * // The row was updated or inserted successfully. * }); */ TransactionRequest.prototype.upsert = function(table, keyVals, callback) { diff --git a/packages/spanner/src/transaction.js b/packages/spanner/src/transaction.js index 0c2ec7e783e..f533b3f4226 100644 --- a/packages/spanner/src/transaction.js +++ b/packages/spanner/src/transaction.js @@ -519,7 +519,7 @@ Transaction.prototype.run = function(query, callback) { * transaction.runStream(query) * .on('error', function(err) {}) * .on('data', function(row) {}) - * .on('end', function() {}) + * .on('end', function() {}); * }); * * //- diff --git a/test/docs.js b/test/docs.js index 07645148e73..73667b0f1ff 100644 --- a/test/docs.js +++ b/test/docs.js @@ -50,7 +50,7 @@ var DocsError = createErrorClass('DocsError', function(err, code) { var JSHintError = createErrorClass('JSHintError', function(err) { this.message = format('"{evidence}" - {reason}', { - evidence: err.evidence.trim(), + evidence: err.evidence && err.evidence.trim(), reason: err.reason }); @@ -218,7 +218,9 @@ function createInstantiationCode(mod) { if (api) { Object.keys(api).forEach(function(apiName) { Object.keys(api[apiName]).forEach(function(method) { - api[apiName][method] = function() {}; + api[apiName][method] = function() { + return Promise.resolve(); + }; }); }); }