Merge branch 'develop'

Author: ehennum

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# How to contribute
+
+We welcome contributions from the community. If you have a patch that you'd
+like us to consider, please do the following: 
+
+* Provide a signed 
+[Contributor License Agreement](http://developer.marklogic.com/products/cla).
+
+* Create an issue for the fix or enhancement. 
+
+  For a bug, clearly describe the steps to reproduce the problem and the
+  earliest version that exhibits the problem. For an enhancement, make sure
+  you have basic agreement about the fix or enhancement.
+
+* [Fork the API repository](https://github.com/marklogic/node-client-api/fork) in your repository on GitHub.
+
+* Create a branch based on the `master` branch or (if you are in the Early
+Access program) on the `develop` branch.
+
+* Implement the fix or enhancement.
+
+  As with other projects, you should include unit tests using the same test
+  harness (at present, [Mocha](http://visionmedia.github.io/mocha/) and [should](https://github.com/visionmedia/should.js/)). Follow the same style conventions
+  as existing code. Run jshint on the changes. Create jsdoc for any new
+  interfaces.  (See the gulp tasks for a convenient way to run jshint.)
+  Run all of the tests to make sure the change doesn't have side effects.
+
+* Commit in one or more logical units with clear messages.
+
+* Push to the branch in your fork.
+
+* Create a pull request from your fork and add a comment to the issue.
+
+  The team will then review the changes and possibly suggest improvements
+  or alternatives.

README.md

@@ -1,13 +1,13 @@
-# MarkLogic Client API for node.js
+# MarkLogic Client API for Node.js
 
-The MarkLogic Client API for node.js provides access to the MarkLogic database
-from node.js.
+The MarkLogic Client API for Node.js provides access to the MarkLogic database
+from Node.js.
 
 ## Status
 
-The MarkLogic node.js API is currently in Early Access Release 2.
+This branch provides the work in progress for the Early Access Release 3 of the MarkLogic Node.js API.
 
-### Getting started
+## Getting started
 
 Please register at the MarkLogic Early Access website and then follow the tutorial instructions:
 
@@ -19,13 +19,13 @@ The instructions describe:
 * cloning this repository to set up the API
 * working through some initial examples to get familiar with the API
 
-For more detail about the API, use the documentation login from the Early Access
-to view the reference documentation:
+For more detail about the API, use the documentation login from the Early Access to view
+the reference documentation:
 
 http://docs-ea.marklogic.com/jsdoc/index.html
 
-After installing the dependencies including gulp, you can also build the documentation
-locally from the root directory of the marklogic package:
+After installing the dependencies including gulp, you can also build the documentation locally
+from the root directory of the marklogic package:
 
     gulp doc
 
@@ -56,7 +56,21 @@ To tear down the test database and REST server, execute
 
     node etc/test-teardown.js
 
-### Capabilities of the node.js Client API in Early Access 2
+### Capabilities added to the Node.js Client API in Early Access 3
+
+* quick path for simple CRUD and query on the database client
+* values and tuples requests
+* server-side transforms on query response summary and result documents in slice() clause
+* snippets including custom snippets in slice() clause
+* extract from result documents (projection)
+* resource service CRUD and invocation
+* graph CRUD and SPARQL query
+* bitemporal document CRUD and query
+* specifying the database when creating a database client
+* server-side eval and invoke
+* search suggest
+
+### Capabilities of the Node.js Client API in Early Access 2
 
 * createDatabaseClient() including HTTPS
 * documents.query()
@@ -93,18 +107,21 @@ To tear down the test database and REST server, execute
 * config.extlibs.write()
 * optimistic locking
 
-### Limitations in Early Access 2
+### Limitations in Early Access 3
 
-The MarkLogic node.js Client API has not yet undergone performance or
-stress testing.  The API should not be used in production in EA2.
+The MarkLogic Node.js Client API has not yet undergone performance or
+stress testing.  The API should not be used in production in EA3.  The
+interface may change before the initial release.
 
-### Candidate Features for Early Access 3
+## Support
 
-* projection from result documents
-* values and tuples lists
-* resource service CRUD and invocation
-* server-side eval
-* graph CRUD
-* aggregates on facets
-* specifying the database when creating a database client
-* pluggable XML conversion
+The MarkLogic Node.js Client API is maintained by MarkLogic Engineering.
+It is designed for use in production applications with MarkLogic Server.
+Everyone is encouraged to file bug reports, feature requests, and pull
+requests through GitHub. This input is critical and will be carefully
+considered, but we can’t promise a specific resolution or timeframe for
+any request. In addition, MarkLogic provides technical support
+for [release tags](https://github.com/marklogic/node-client-api/releases)
+of the Node Client API to licensed customers under the terms outlined
+in the [Support Handbook](http://www.marklogic.com/files/Mark_Logic_Support_Handbook.pdf).
+For more information or to sign up for support, visit [help.marklogic.com](help.marklogic.com).

etc/test-config.js

@@ -30,6 +30,9 @@ var restReaderPassword = 'x';
 var restWriterUser     = 'rest-writer';
 var restWriterPassword = 'x';
 
+var restEvaluatorUser     = 'rest-evaluator';
+var restEvaluatorPassword = 'x';
+
 var testServerName = 'unittest-nodeapi';
 
 // For SSL without client cert, use rejectUnauthorized: false
@@ -58,11 +61,27 @@ module.exports = {
         password: restWriterPassword,
         authType: restAuthType
     },
+    restEvaluatorConnection: {
+      host:     testHost,
+      port:     restPort,
+      user:     restEvaluatorUser,
+      password: restEvaluatorPassword,
+      authType: restAuthType
+    },
     manageAdminConnection: {
         host:     testHost,
         port:     managePort,
         user:     restAdminUser,
         password: restAdminPassword,
         authType: manageAuthType
+    },
+    restSslConnection: {
+        host:     testHost,
+        port:     restPort,
+        user:     restAdminUser,
+        password: restAdminPassword,
+        authType: 'BASIC',
+        rejectUnauthorized: false,
+        ssl:      true
     }
 };

etc/test-lib.js

@@ -21,12 +21,12 @@ var mlutil    = require('../lib/mlutil.js');
 //CAUTION: the functions in this module are not part of the supported API and
 //may change or may be removed at any time.
 
-function responseOutputTransform(data) {
+function responseOutputTransform(headers, data) {
   var operation = this;
 
   var response = {
       statusCode: operation.responseStatusCode,
-      headers:    operation.responseHeaders
+      headers:    headers
   };
   if (!valcheck.isNullOrUndefined(data)) {
     response.data = data;

etc/test-setup-users.js

@@ -21,33 +21,92 @@ var testconfig = require('./test-config.js');
 function setupUsers(manager, done) {
   console.log('checking for REST users');
   manager.get({
-    endpoint: '/manage/v2/users'
-    }).
-  result(function(response) {
+    endpoint: '/manage/v2/roles/'+encodeURIComponent('rest-evaluator')
+    }).result().
+  then(function(response) {
+    if (response.statusCode < 400) {
+      return this;
+    }
+    return manager.post({
+      endpoint: '/manage/v2/roles',
+      body: {
+        'role-name': 'rest-evaluator',
+        description: 'REST writer who can eval, invoke, or set a dynamic databases',
+        role: [
+          'rest-writer'
+        ],
+        privilege: [
+          {
+            'privilege-name': 'xdmp-eval',
+            action: 'http://marklogic.com/xdmp/privileges/xdmp-eval',
+            kind: 'execute'
+          },
+          {
+            'privilege-name': 'xdmp-eval-in',
+            action: 'http://marklogic.com/xdmp/privileges/xdmp-eval-in',
+            kind: 'execute'
+          },
+          {
+            'privilege-name': 'xdmp-invoke',
+            action: 'http://marklogic.com/xdmp/privileges/xdmp-invoke',
+            kind: 'execute'
+          },
+          {
+            'privilege-name': 'xdbc-eval',
+            action: 'http://marklogic.com/xdmp/privileges/xdbc-eval',
+            kind: 'execute'
+          },
+          {
+            'privilege-name': 'xdbc-eval-in',
+            action: 'http://marklogic.com/xdmp/privileges/xdbc-eval-in',
+            kind: 'execute'
+          },
+          {
+            'privilege-name': 'xdbc-invoke',
+            action: 'http://marklogic.com/xdmp/privileges/xdbc-invoke',
+            kind: 'execute'
+          }
+        ]
+      }
+      }).result();      
+  }).
+  then(function(response) {
+    return manager.get({
+      endpoint: '/manage/v2/users'
+      }).result();
+  }).
+  then(function(response) {
     var userName = null;
 
     var requiredUsers = {};
     userName = testconfig.restAdminConnection.user;
     requiredUsers[userName]  = {
       role:        'rest-admin',
-      name:        userName,
+      'user-name': userName,
       description: 'rest-admin user',
       password:    testconfig.restAdminConnection.password
       };
     userName = testconfig.restReaderConnection.user;
     requiredUsers[userName]  = {
       role:        'rest-reader',
-      name:        userName,
+      'user-name': userName,
       description: 'rest-reader user',
       password:    testconfig.restReaderConnection.password
       };
     userName = testconfig.restWriterConnection.user;
     requiredUsers[userName]  = {
       role:        'rest-writer',
-      name:        userName,
+      'user-name': userName,
       description: 'rest-writer user',
       password:    testconfig.restWriterConnection.password
       };
+    userName = testconfig.restEvaluatorConnection.user;
+    requiredUsers[userName]  = {
+      role:        'rest-evaluator',
+      'user-name': userName,
+      description: 'rest-writer user with evaluate privileges',
+      password:    testconfig.restEvaluatorConnection.password
+      };
 
     response.data['user-default-list']['list-items']['list-item'].
     forEach(function(user) {
@@ -92,7 +151,7 @@ function addUser(manager, users, next, done) {
   manager.post({
     endpoint: '/manage/v2/users',
     body: {
-      name:        userdef.name,
+      'user-name': userdef['user-name'],
       password:    userdef.password,
       description: userdef.description,
       role:        [