return object with cookies from transaction open and send with

transaction requests #164

Author: ehennum

lib/documents.js

@@ -155,7 +155,9 @@ function probeOutputTransform(/*headers, data*/) {
  * a uri string.
  * @method documents#probe
  * @param {string}  uri - the uri for the database document
- * @param {string}  [txid] - the transaction id for an open transaction
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction
  * @returns {ResultProvider} an object whose result() function takes
  * a {@link documents#probeResult} success callback.
  */
@@ -170,7 +172,8 @@ function probeDocumentsImpl(contentOnly, args) {
 
   var params = (!valcheck.isString(args[0])) ? args[0] : null; 
 
-  var uri;
+  var uri = null;
+  var txid = null;
 
   var path = '/v1/documents?format=json';
   if (params === null) {
@@ -183,16 +186,17 @@ function probeDocumentsImpl(contentOnly, args) {
     }
     path += '&uri='+encodeURIComponent(uri);
 
-    var txid = params.txid;
+    txid = params.txid;
     if (!valcheck.isNullOrUndefined(txid)) {
-      path += '&txid='+txid;
+      path += '&txid='+mlutil.getTxidParam(txid);
     }
   }
 
   var connectionParams = this.client.connectionParams;
   var requestOptions = mlutil.copyProperties(connectionParams);
   requestOptions.method = 'HEAD';
   requestOptions.path = mlutil.databaseParam(connectionParams, path, '&');
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'probe document', this.client, requestOptions, 'empty', 'empty'
@@ -281,7 +285,9 @@ function singleReadOutputTransform(headers, data) {
  * for the database documents
  * @param {documents.categories|documents.categories[]}  [categories] - the categories of information
  * to retrieve for the documents
- * @param {string}  [txid] - the transaction id for an open transaction
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction
  * @param {string}  [transform] - the name of a transform extension to apply
  * to each document; the transform must have been installed using
  * the {@link transforms#write} function.
@@ -334,7 +340,7 @@ function readDocumentsImpl(contentOnly, args) {
     uris.map(encodeURIComponent).join('&uri=');
   path += '&category=' + categories.join('&category=');
   if (!valcheck.isNullOrUndefined(txid)) {
-    path += '&txid='+txid;
+    path += '&txid='+mlutil.getTxidParam(txid);
   }
   if (!valcheck.isNullOrUndefined(transform)) {
     path += '&'+mlutil.endpointTransform(transform);
@@ -412,6 +418,7 @@ function readDocumentsImpl(contentOnly, args) {
       };
     }
   }
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'read documents', this.client, requestOptions, 'empty', 
@@ -444,7 +451,9 @@ function readDocumentsImpl(contentOnly, args) {
  * @param {number} [quality] - a weight to increase or decrease the rank of the document
  * @param {number} [versionId] - an identifier for the currently stored version of the
  * document (when enforcing optimistic locking)
- * @param {string}  [txid] - the transaction id for an open transaction
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction
  * @param {string}  [transform] - the name of a transform extension to apply
  * to the document; the transform must have been installed using
  * the {@link transforms#write} function.
@@ -480,7 +489,9 @@ function writeStreamImpl(document, categories) {
 
   var sep = '?';
 
-  var writeParams = addWriteParams(document, categories);
+  var txid = getTxid(document);
+
+  var writeParams = addWriteParams(document, categories, txid);
   if (writeParams.length > 0) {
     endpoint += writeParams;
     sep = '&';
@@ -496,6 +507,7 @@ function writeStreamImpl(document, categories) {
       'Accept': 'application/json'
   };
   requestOptions.path = mlutil.databaseParam(connectionParams, endpoint, sep);
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   // TODO: treat as chunked single document if no properties
   var requestPartList = [];
@@ -587,7 +599,9 @@ function writeListOutputTransform(headers, data) {
  * or an array of document descriptors to write
  * @param {documents.categories|documents.categories[]}  [categories] - the categories of information
  * to write for the documents
- * @param {string}  [txid] - the transaction id for an open transaction
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction
  * @param {string}  [transform] - the name of a transform extension to apply
  * to each document; the transform must have been installed using
  * the {@link transforms#write} function.
@@ -685,7 +699,7 @@ function writeMetadata(document, categories) {
 
   var txid = document.txid;
   if (!valcheck.isNullOrUndefined(txid)) {
-    endpoint += '&txid='+txid;
+    endpoint += '&txid='+mlutil.getTxidParam(txid);
   }
 
   var requestHeaders = {
@@ -698,6 +712,7 @@ function writeMetadata(document, categories) {
   requestOptions.method  = 'PUT';
   requestOptions.headers = requestHeaders;
   requestOptions.path    = mlutil.databaseParam(connectionParams, endpoint, '&');
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'write single metadata', this.client, requestOptions, 'single', 'empty'
@@ -721,7 +736,9 @@ function writeContent(contentOnly, document, requestParams, categories, requestT
 
   var sep = '?';
 
-  var writeParams = addWriteParams(requestParams, categories);
+  var txid = getTxid(requestParams);
+
+  var writeParams = addWriteParams(requestParams, categories, txid);
   if (writeParams.length > 0) {
     endpoint += writeParams;
     sep = '&';
@@ -807,6 +824,7 @@ function writeContent(contentOnly, document, requestParams, categories, requestT
   requestOptions.method  = hasUri ? 'PUT' : 'POST';
   requestOptions.headers = requestHeaders;
   requestOptions.path    = mlutil.databaseParam(connectionParams, endpoint, sep);
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'write single document', this.client, requestOptions, requestType, 'empty'
@@ -835,7 +853,9 @@ function writeDocumentList(contentOnly, documents, requestParams, categories) {
 
   var endpoint = '/v1/documents';
 
-  var writeParams = addWriteParams(requestParams, categories);
+  var txid = getTxid(requestParams);
+
+  var writeParams = addWriteParams(requestParams, categories, txid);
   var sep = '?';
   if (writeParams.length > 0) {
     endpoint += writeParams;
@@ -854,6 +874,7 @@ function writeDocumentList(contentOnly, documents, requestParams, categories) {
   requestOptions.method  = 'POST';
   requestOptions.headers = requestHeaders;
   requestOptions.path    = mlutil.databaseParam(connectionParams, endpoint, sep);
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'write document list', this.client, requestOptions, 'multipart', 'single'
@@ -874,8 +895,11 @@ function writeDocumentList(contentOnly, documents, requestParams, categories) {
 
   return requester.startRequest(operation);
 }
+function getTxid(requestParams) {
+  return valcheck.isNullOrUndefined(requestParams) ? null : requestParams.txid;
+}
 /** @ignore */
-function addWriteParams(requestParams, categories) {
+function addWriteParams(requestParams, categories, txid) {
   var writeParams = '';
 
   var sep = '?';
@@ -884,9 +908,8 @@ function addWriteParams(requestParams, categories) {
       writeParams += sep+'category='+categories.join('&category=');
       if (sep !== '&') { sep = '&'; }
     }
-    var txid = requestParams.txid;
     if (!valcheck.isNullOrUndefined(txid)) {
-      writeParams += sep+'txid='+txid;
+      writeParams += sep+'txid='+mlutil.getTxidParam(txid);
       if (sep !== '&') { sep = '&'; }
     }
     var transform = mlutil.endpointTransform(requestParams.transform);
@@ -1118,7 +1141,9 @@ function removeOutputTransform(headers/*, data*/) {
  * @method documents#remove
  * @param {string|string[]}  uris - the uri string or an array of uri strings
  * identifying the database documents
- * @param {string}  [txid] - the transaction id for an open transaction
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction
  * @param {string} [temporalCollection] - the name of the temporal collection;
  * use only when deleting a document created as a temporal document; sets the
  * system end time to record when the document was no longer active
@@ -1173,7 +1198,7 @@ function removeDocumentImpl(contentOnly, isLegacy, args) {
   var path = '/v1/documents?uri='+
     uris.map(encodeURIComponent).join('&uri=');
   if (!valcheck.isNullOrUndefined(txid)) {
-    path += '&txid='+txid;
+    path += '&txid='+mlutil.getTxidParam(txid);
   }
   if (!valcheck.isNullOrUndefined(temporalCollection)) {
     path += '&temporal-collection='+temporalCollection;
@@ -1193,6 +1218,7 @@ function removeDocumentImpl(contentOnly, isLegacy, args) {
   }
   requestOptions.method = 'DELETE';
   requestOptions.path = mlutil.databaseParam(connectionParams, path, '&');
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'remove document', this.client, requestOptions, 'empty', 'empty'
@@ -1293,7 +1319,7 @@ function removeAllDocumentsImpl(contentOnly, params) {
   }
 
   if (!valcheck.isNullOrUndefined(txid)) {
-    endpoint += sep+'txid='+txid;
+    endpoint += sep+'txid='+mlutil.getTxidParam(txid);
     if (sep === '?') {
       sep = '&';
     }
@@ -1303,6 +1329,7 @@ function removeAllDocumentsImpl(contentOnly, params) {
   var requestOptions = mlutil.copyProperties(connectionParams);
   requestOptions.method = 'DELETE';
   requestOptions.path = mlutil.databaseParam(connectionParams, endpoint, sep);
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'remove all documents', this.client, requestOptions, 'empty', 'empty'
@@ -1341,8 +1368,10 @@ function listOutputTransform(headers, data) {
  * page of result documents (also known as the result slice) 
  * @property {number} [pageLength] - the number of documents in the returned page
  * of result documents 
- * @property {string}  [txid] - the transaction id for an open transaction to include
- * modified documents in the results if the documents match the criteria
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction to include modified documents
+ * in the results if the documents match the criteria
  * @property {string} [view] - a value from the enumeration
  * all|facets|metadata|none|results|uris controlling whether to generate some or all
  * of a search response summarizing the search response in addition to the result
@@ -1408,7 +1437,7 @@ function queryDocumentsImpl(collectionParam, contentOnly, builtQuery) {
     endpoint += '&pageLength='+pageLength;
   }
   if (!valcheck.isNullOrUndefined(txid)) {
-    endpoint += '&txid='+txid;
+    endpoint += '&txid='+mlutil.getTxidParam(txid);
   }
   if (!valcheck.isNullOrUndefined(transform)) {
     endpoint += '&'+mlutil.endpointTransform(transform);
@@ -1431,6 +1460,7 @@ function queryDocumentsImpl(collectionParam, contentOnly, builtQuery) {
           'application/json')
   };
   requestOptions.path = mlutil.databaseParam(connectionParams, endpoint, '&');
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'query documents', this.client, requestOptions, 'single',
@@ -1729,8 +1759,10 @@ function patchOutputTransform(/*headers, data*/) {
  * to the document.
  * @param {documents.categories|documents.categories[]}  [categories] - the
  * categories of information modified by the patch (typically 'content')
- * @param {string}  [txid] - the transaction id to patch the document
- * as part of a larger multi-statement transaction
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction to patch the document as part
+ * of a larger multi-statement transaction
  * @param {number} [versionId] - an identifier for the currently stored version
  * of the document (when enforcing optimistic locking)
  * @returns {ResultProvider} an object whose result() function takes
@@ -1821,7 +1853,7 @@ Documents.prototype.patch = function patchDocuments() {
     }
   }
   if (!valcheck.isNullOrUndefined(txid)) {
-    endpoint += '&txid=' + txid;
+    endpoint += '&txid=' + mlutil.getTxidParam(txid);
   }
 
   var patchBody = isRawPatch ? documentOperations : {patch: documentOperations};
@@ -1842,6 +1874,7 @@ Documents.prototype.patch = function patchDocuments() {
     requestOptions.headers['If-Match'] = versionId;
   }
   requestOptions.path = mlutil.databaseParam(connectionParams, endpoint, '&');
+  mlutil.addTxidHeaders(requestOptions, txid);
 
   var operation = new Operation(
       'patch document', this.client, requestOptions, 'single', 'single'
@@ -1912,7 +1945,9 @@ Documents.prototype.suggest = function suggestDocuments() {
     throw new Error('no query with bindings for document suggestion');
   }
 
-  var searchBody = makeSearchBody(query).searchBody;
+  var wrapper = makeSearchBody(query);
+
+  var searchBody = wrapper.searchBody;
   var search = searchBody.search;
   if (valcheck.isNullOrUndefined(search)) {
     throw new Error('cannot get  document suggestions for empty search');
@@ -1962,6 +1997,7 @@ Documents.prototype.suggest = function suggestDocuments() {
       'Accept':       'application/json',
   };
   requestOptions.path = mlutil.databaseParam(connectionParams, endpoint, '&');
+  mlutil.addTxidHeaders(requestOptions, wrapper.txid);
 
   var operation = new Operation(
       'search suggest', this.client, requestOptions, 'single', 'single'

lib/mlutil.js

@@ -246,7 +246,62 @@ function unmarshal(format, data) {
   }
 }
 
+function Transaction(id, cookies) {
+  if (!(this instanceof Transaction)) {
+    return new Transaction(id, cookies);
+  }
+
+  this.txid = id;
+  if (valcheck.isArray(cookies) && cookies.length > 0) {
+    for (var i=0; i < cookies.length; i++) {
+      cookies[i] = cookies[i].replace(/;\s*expires\s*=[^;]+(;|$)/i, '$1');
+    }
+    this.cookies = cookies;
+  }
+}
+Transaction.prototype.toString = function transactionToString() {
+  return this.txid;
+};
+
+function getTxidParam(txid, action) {
+  if (valcheck.isNullOrUndefined(txid)) {
+    if (!valcheck.isNullOrUndefined(action)) {
+      throw new Error(
+          'cannot '+action+' transaction without string or Transaction object identifier'
+          );
+    }
+    return;
+  }
+
+  if (valcheck.isString(txid)) {
+    return txid;
+  } else if (txid instanceof Transaction) {
+    return txid.txid;
+  }
+
+  throw new Error(
+      'can only '+action+' transaction with string or Transaction object identifier: '+
+      (typeof txid)
+  );
+}
+function addTxidHeaders(requestOptions, txid) {
+  if (txid instanceof Transaction) {
+    var cookies = txid.cookies;
+    if (!valcheck.isNullOrUndefined(cookies)) {
+      var headers = requestOptions.headers;
+      if (!valcheck.isNullOrUndefined(headers)) {
+        headers.cookie = cookies;
+      } else {
+        requestOptions.headers = {
+            cookie: cookies
+        };
+      }
+    }
+  }
+}
+
 module.exports = {
+    addTxidHeaders:      addTxidHeaders,
     appendItem:          appendItem,
     asArray:             asArray,
     callbackOn:          callbackOn,
@@ -257,9 +312,11 @@ module.exports = {
     Error:               MarkLogicError,
     extension:           extension,
     first:               first,
+    getTxidParam:        getTxidParam,
     marshal:             marshal,
     multipartBoundary:   multipartBoundary,
     parseJSON:           parseJSON,
     rootname:            rootname,
+    Transaction:         Transaction,
     unmarshal:           unmarshal
 };

lib/query-builder.js

@@ -4766,7 +4766,9 @@ function snippet() {
  * @param {...string} [forestNames] - the names of forests providing documents
  * for the result set
  * @param {...string} [search] - options modifying the default behaviour of the query
- * @param {string}  [txid] - the transaction id for an open transaction
+ * @param {string|transactions.Transaction}  [txid] - a string
+ * transaction id or Transaction object identifying an open
+ * multi-statement transaction
  * @param {number} [weight] - a weighting factor between -16 and 64
  * @param {boolean} [debug] - whether to return query debugging
  * @param {boolean} [metrics] - whether to return metrics for the query performance