neo4j-driver 1.1.1 → 1.3.0

package/README.md

@@ -63,39 +63,45 @@ driver.close();
 
 ## Usage examples
 
+Driver creation:
 ```javascript
-
 // Create a driver instance, for the user neo4j with password neo4j.
 // It should be enough to have a single driver per database per application.
 var driver = neo4j.driver("bolt://localhost", neo4j.auth.basic("neo4j", "neo4j"));
 
 // Register a callback to know if driver creation was successful:
-driver.onCompleted = function() {
+driver.onCompleted = function () {
   // proceed with using the driver, it was successfully instantiated
 };
 
 // Register a callback to know if driver creation failed.
 // This could happen due to wrong credentials or database unavailability:
-driver.onError = function(error) {
+driver.onError = function (error) {
   console.log('Driver instantiation failed', error);
 };
 
+// Close the driver when application exits.
+// This closes all used network connections.
+driver.close();
+```
+
+Session API:
+```javascript
 // Create a session to run Cypher statements in.
 // Note: Always make sure to close sessions when you are done using them!
 var session = driver.session();
 
 // Run a Cypher statement, reading the result in a streaming manner as records arrive:
 session
-  .run("MERGE (alice:Person {name : {nameParam} }) RETURN alice.name", { nameParam:'Alice' })
+  .run('MERGE (alice:Person {name : {nameParam} }) RETURN alice.name AS name', {nameParam: 'Alice'})
   .subscribe({
-    onNext: function(record) {
-     console.log(record._fields);
+    onNext: function (record) {
+      console.log(record.get('name'));
     },
-    onCompleted: function() {
-      // Completed!
+    onCompleted: function () {
       session.close();
     },
-    onError: function(error) {
+    onError: function (error) {
       console.log(error);
     }
   });
@@ -103,55 +109,102 @@ session
 // or
 // the Promise way, where the complete result is collected before we act on it:
 session
-  .run("MERGE (james:Person {name : {nameParam} }) RETURN james.name", { nameParam:'James' })
-  .then(function(result){
-    result.records.forEach(function(record) {
-      console.log(record._fields);
+  .run('MERGE (james:Person {name : {nameParam} }) RETURN james.name AS name', {nameParam: 'James'})
+  .then(function (result) {
+    result.records.forEach(function (record) {
+      console.log(record.get('name'));
     });
-    // Completed!
     session.close();
   })
-  .catch(function(error) {
+  .catch(function (error) {
     console.log(error);
   });
+```
+
+Transaction functions API:
+```javascript
+// Transaction functions provide a convenient API with minimal boilerplate and
+// retries on network fluctuations and transient errors. Maximum retry time is
+// configured on the driver level and is 30 seconds by default:
+neo4j.driver("bolt://localhost", neo4j.auth.basic("neo4j", "neo4j"), {maxTransactionRetryTime: 30000});
+
+// It is possible to execute read transactions that will benefit from automatic
+// retries on both single instance ('bolt' URI scheme) and Causal Cluster
+// ('bolt+routing' URI scheme) and will get automatic load balancing in cluster deployments
+var readTxResultPromise = session.readTransaction(function (transaction) {
+  // used transaction will be committed automatically, no need for explicit commit/rollback
+
+  var result = transaction.run('MATCH (person:Person) RETURN person.name AS name');
+  // at this point it is possible to either return the result or process it and return the
+  // result of processing it is also possible to run more statements in the same transaction
+  return result;
+});
+
+// returned Promise can be later consumed like this:
+readTxResultPromise.then(function (result) {
+  session.close();
+  console.log(result.records);
+}).catch(function (error) {
+  console.log(error);
+});
+
+// It is possible to execute write transactions that will benefit from automatic retries
+// on both single instance ('bolt' URI scheme) and Causal Cluster ('bolt+routing' URI scheme)
+var writeTxResultPromise = session.writeTransaction(function (transaction) {
+  // used transaction will be committed automatically, no need for explicit commit/rollback
+
+  var result = transaction.run('MERGE (alice:Person {name : \'Alice\' }) RETURN alice.name AS name');
+  // at this point it is possible to either return the result or process it and return the
+  // result of processing it is also possible to run more statements in the same transaction
+  return result.records.map(function (record) {
+    return record.get('name');
+  });
+});
+
+// returned Promise can be later consumed like this:
+writeTxResultPromise.then(function (namesArray) {
+  session.close();
+  console.log(namesArray);
+}).catch(function (error) {
+  console.log(error);
+});
+```
 
-//run statement in a transaction
+Explicit transactions API:
+```javascript
+// run statement in a transaction
 var tx = session.beginTransaction();
-tx.run("MERGE (bob:Person {name : {nameParam} }) RETURN bob.name", { nameParam:'Bob' })
+tx.run("MERGE (bob:Person {name : {nameParam} }) RETURN bob.name AS name", {nameParam: 'Bob'})
   .subscribe({
-    onNext: function(record) {
-      console.log(record._fields);
-      },
-    onCompleted: function() {
-      // Completed!
+    onNext: function (record) {
+      console.log(record.get('name'));
+    },
+    onCompleted: function () {
       session.close();
     },
-    onError: function(error) {
+    onError: function (error) {
       console.log(error);
     }
   });
-  
+
 //decide if the transaction should be committed or rolled back
 var success = false;
 
 if (success) {
   tx.commit()
     .subscribe({
-      onCompleted: function() {
-        // Completed!
+      onCompleted: function () {
+        // this transaction is now committed 
       },
-      onError: function(error) {
+      onError: function (error) {
         console.log(error);
-        }
-      });
-  } else {
+      }
+    });
+} else {
   //transaction is rolled black and nothing is created in the database
   console.log('rolled back');
   tx.rollback();
 }
-
-// Close the driver when application exits
-driver.close();
 ```
 
 Subscriber API allows following combinations of `onNext`, `onCompleted` and `onError` callback invocations:
@@ -171,10 +224,19 @@ See files under `examples/` on how to use.
 
 ## Testing
 
+Tests **require** latest [Boltkit](https://github.com/neo4j-contrib/boltkit) to be installed in the system. It is needed to start, stop and configure local test database. Boltkit can be installed with the following command:
+
+    pip install --upgrade boltkit
+
+To run tests against "default" Neo4j version:
+
     ./runTests.sh
+    
+To run tests against specified Neo4j version:
+    
+    ./runTests.sh '-e 3.1.3'
 
-This runs the test suite against a fresh download of Neo4j.
-Or `npm test` if you already have a running version of a compatible Neo4j server.
+Simple `npm test` can also be used if you already have a running version of a compatible Neo4j server.
 
 For development, you can have the build tool rerun the tests each time you change
 the source code:

package/gulpfile.babel.js

@@ -22,7 +22,6 @@ var source = require('vinyl-source-stream');
 var buffer = require('vinyl-buffer');
 var gulp = require('gulp');
 var through = require('through2');
-var gulpif = require('gulp-if');
 var uglify = require('gulp-uglify');
 var concat = require('gulp-concat');
 var gutil = require('gulp-util');
@@ -40,7 +39,6 @@ var decompress = require('gulp-decompress');
 var fs = require("fs-extra");
 var runSequence = require('run-sequence');
 var path = require('path');
-var childProcess = require("child_process");
 var minimist = require('minimist');
 var cucumber = require('gulp-cucumber');
 var merge = require('merge-stream');
@@ -48,6 +46,7 @@ var install = require("gulp-install");
 var os = require('os');
 var file = require('gulp-file');
 var semver = require('semver');
+var sharedNeo4j = require('./test/internal/shared-neo4j').default;
 
 gulp.task('default', ["test"]);
 
@@ -56,8 +55,7 @@ gulp.task('browser', function(cb){
 });
 
 /** Build all-in-one files for use in the browser */
-gulp.task('bu' +
-  'ild-browser', function () {
+gulp.task('build-browser', function () {
   var browserOutput = 'lib/browser';
   // Our app bundler
   var appBundler = browserify({
@@ -164,23 +162,17 @@ gulp.task('test', function(cb){
 
 gulp.task('test-nodejs', ['install-driver-into-sandbox'], function () {
   return gulp.src('test/**/*.test.js')
-        .pipe(jasmine({
-            // reporter: new reporters.JUnitXmlReporter({
-            //   savePath: "build/nodejs-test-reports",
-            //   consolidateAll: false
-            // }),
-            includeStackTrace: true
-        }));
+    .pipe(jasmine({
+      includeStackTrace: true,
+      verbose: true
+    }));
 });
 
 gulp.task('test-boltkit', ['nodejs'], function () {
   return gulp.src('test/**/*.boltkit.it.js')
     .pipe(jasmine({
-      // reporter: new reporters.JUnitXmlReporter({
-      //   savePath: "build/nodejs-test-reports",
-      //   consolidateAll: false
-      // }),
-      includeStackTrace: true
+      includeStackTrace: true,
+      verbose: true
     }));
 });
 
@@ -239,43 +231,14 @@ gulp.task('set', function() {
 });
 
 
-var neo4jHome  = path.resolve('./build/neo4j');
-var neorunPath = path.resolve('./neokit/neorun.py');
-var neorunStartArgsName = "--neorun.start.args"; // use this args to provide additional args for running neorun.start
-
-gulp.task('start-neo4j', function() {
-
-    var neorunStartArgs = '-p neo4j'; // default args to neorun.start: change the default password to neo4j
-    process.argv.slice(2).forEach(function (val) {
-        if(val.startsWith(neorunStartArgsName))
-        {
-            neorunStartArgs = val.split("=")[1];
-        }
-    });
+var neo4jHome = path.resolve('./build/neo4j');
 
-    neorunStartArgs = neorunStartArgs.match(/\S+/g) || '';
-
-    return runScript([
-        neorunPath, '--start=' + neo4jHome
-    ].concat( neorunStartArgs ) );
+gulp.task('start-neo4j', function (done) {
+  sharedNeo4j.start(neo4jHome, process.env.NEOCTRL_ARGS);
+  done();
 });
 
-gulp.task('stop-neo4j', function() {
-    return runScript([
-        neorunPath, '--stop=' + neo4jHome
-    ]);
+gulp.task('stop-neo4j', function (done) {
+  sharedNeo4j.stop(neo4jHome);
+  done();
 });
-
-var runScript = function(cmd) {
-    var spawnSync = childProcess.spawnSync, child, code;
-    child = spawnSync('python', cmd);
-    console.log("Script Outputs:\n" + child.stdout.toString());
-    var error = child.stderr.toString();
-    if (error.trim() !== "")
-        console.log("Script Errors:\n"+ error);
-    code = child.status;
-    if( code !==0 )
-    {
-        throw "Script finished with code " + code
-    }
-};