Move summary to callback result/onCompleted, add examples

- #summarize() lived on the ResultStream from run - which was unhelpful,
  since the summary is not available until the result is consumed. This
  instead makes a summary available as an argument to `onCompleted` and
  as a field on the result object we get when we ask for a full result

- Add examples file for the manual.

Author: jakewins

src/v1/internal/connector.js

@@ -219,7 +219,6 @@ class Connection {
   }
 
   _handleMessage( msg ) {
-
     switch( msg.signature ) {
       case RECORD:
         this._currentObserver.onNext( msg.fields[0] );

src/v1/result.js

@@ -38,7 +38,6 @@ class Result {
     this._p = null;
     this._statement = statement;
     this._parameters = parameters;
-    this.summary = {};
   }
 
   /**
@@ -54,7 +53,10 @@ class Result {
       let records = [];
       let observer = {
         onNext: (record) => { records.push(record); },
-        onCompleted: () => { resolve(records); },
+        onCompleted: (summary) => {
+          records.summary = summary;
+          resolve(records);
+        },
         onError: (error) => { reject(error); }
       };
       self.subscribe(observer);
@@ -68,9 +70,9 @@ class Result {
    * @param {function(results: Object)} cb - Function to be called when all results are collected.
    * @return {Promise} promise.
    */
-  then(cb) {
+  then(onFulfilled, onRejected) {
     this._createPromise();
-    this._p.then(cb);
+    this._p.then(onFulfilled, onRejected);
     return this._p;
   }
 
@@ -80,9 +82,9 @@ class Result {
    * @param {function(error: Object)} cb - Function to be called upon errors.
    * @return {Promise} promise.
    */
-  catch(cb) {
+  catch(onRejected) {
     this._createPromise();
-    this._p.catch(cb);
+    this._p.catch(onRejected);
     return this._p;
   }
 
@@ -97,20 +99,12 @@ class Result {
   subscribe(observer) {
     let onCompletedOriginal = observer.onCompleted;
     let onCompletedWrapper = (metadata) => {
-      this.summary = new ResultSummary(this._statement, this._parameters, metadata);
-      onCompletedOriginal.call(observer);
+      let sum = new ResultSummary(this._statement, this._parameters, metadata);
+      onCompletedOriginal.call(observer, sum);
     };
     observer.onCompleted = onCompletedWrapper;
     this._streamObserver.subscribe(observer);
   }
-
-  /**
-   * Get a metadata summary for the statement.
-   * @return {ResultSummary} - A ResultSummary class.
-   */
-  summarize() {
-    return this.summary;
-  }
 }
 
 export default Result

test/v1/examples.test.js

@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) 2002-2015 "Neo Technology,"
+ * Network Engine for Objects in Lund AB [http://neotechnology.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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.
+ */
+
+var neo4j = require("../../lib/v1");
+
+var _console = console;
+
+describe('transaction', function() {
+
+  var driver, session, out, console;
+
+  beforeEach(function(done) {
+    driver = neo4j.driver("bolt://localhost");
+    session = driver.session();
+
+    // Override console.log, to assert on stdout output
+    out = [];
+    console = { log: function(msg) { out.push(msg); }  };
+
+    session.run("MATCH (n) DETACH DELETE n").then(done);
+  });
+
+  it('should document a minimum viable snippet', function(done) {
+    // tag::minimum-snippet[]
+    var driver = neo4j.driver("bolt://localhost");
+    var session = driver.session();
+
+    session.run( "CREATE (neo:Person {name:'Neo', age:23})" );
+
+    session
+      .run( "MATCH (p:Person) WHERE p.name = 'Neo' RETURN p.age" )
+      .then( function( result ) {
+        console.log( "Neo is " + result[0]["p.age"].toInt() + " years old." );
+
+        session.close();
+        driver.close();
+        done();
+      });
+    // end::minimum-snippet[]
+  });
+
+  it('should document a statement', function(done) {
+    var resultPromise =
+    // tag::statement[]
+    session
+      .run( "CREATE (p:Person { name: {name} })", {"name": "The One"} )
+      .then( function(result) {
+        var theOnesCreated = result.summary.updateStatistics.nodesCreated();
+        console.log("There were " + theOnesCreated + " the ones created.")
+      });
+    // end::statement[]
+
+    // Then
+    resultPromise.then(function() {
+      expect(out[0]).toBe("There were 1 the ones created.");
+      done();
+    });
+  });
+
+  it('should document a statement without parameters', function(done) {
+    var resultPromise =
+    // tag::statement-without-parameters[]
+    session
+      .run( "CREATE (p:Person { name: 'The One' })" )
+      
+      .then( function(result) {
+        var theOnesCreated = result.summary.updateStatistics.nodesCreated();
+        console.log("There were " + theOnesCreated + " the ones created.");
+      });
+    // end::statement-without-parameters[]
+
+    // Then
+    resultPromise.then(function() {
+      expect(out[0]).toBe("There were 1 the ones created.");
+      done();
+    })
+  });
+
+  it('should document committing a transaction', function() {
+    // tag::transaction-commit[]
+    var tx = session.beginTransaction();
+    tx.run( "CREATE (p:Person { name: 'The One' })" );
+    tx.commit();
+    // end::transaction-commit[]
+  });
+
+  it('should document rolling back a transaction', function() {
+    // tag::transaction-rollback[]
+    var tx = session.beginTransaction();
+    tx.run( "CREATE (p:Person { name: 'The One' })" );
+    tx.rollback();
+    // end::transaction-rollback[]
+  });
+
+  it('should document how to require encryption', function() {
+    // tag::tls-require-encryption[]
+    // Unfortunately, this feature is not yet implemented for JavaScript
+    // end::tls-require-encryption[]
+  });
+
+  it('should document how to configure trust-on-first-use', function() {  
+    // tag::tls-trust-on-first-use[]
+    // Unfortunately, this feature is not yet implemented for JavaScript
+    // end::tls-trust-on-first-use[]
+  }); 
+
+  it('should document how to configure a trusted signing certificate', function() {  
+    // tag::tls-signed[]
+    // Unfortunately, this feature is not yet implemented for JavaScript
+    // end::tls-signed[]
+  });
+
+});

test/v1/session.test.js

@@ -134,9 +134,9 @@ describe('session', function() {
     var statement = "CREATE (n:Label {prop:{prop}}) RETURN n";
     var params = {prop: "string"}
     // When & Then
-    var result = driver.session().run( statement, params );
-    result.then(function() {
-      var sum = result.summarize();
+    driver.session().run( statement, params )
+          .then(function(result) {
+      var sum = result.summary;
       expect(sum.statement.text).toBe( statement );
       expect(sum.statement.parameters).toBe( params );
       expect(sum.updateStatistics.containsUpdates()).toBe(true);
@@ -153,9 +153,10 @@ describe('session', function() {
     var statement = "EXPLAIN CREATE (n:Label {prop:{prop}}) RETURN n";
     var params = {prop: "string"}
     // When & Then
-    var result = driver.session().run( statement, params );
-    result.then(function() {
-      var sum = result.summarize();
+    driver.session()
+          .run( statement, params )
+          .then(function(result) {
+      var sum = result.summary;
       expect(sum.hasPlan()).toBe(true);
       expect(sum.hasProfile()).toBe(false);
       expect(sum.plan.operatorType).toBe('ProduceResults');
@@ -173,9 +174,10 @@ describe('session', function() {
     var statement = "PROFILE MATCH (n:Label {prop:{prop}}) RETURN n";
     var params = {prop: "string"}
     // When & Then
-    var result = driver.session().run( statement, params );
-    result.then(function() {
-      var sum = result.summarize();
+    driver.session()
+          .run( statement, params )
+          .then(function(result) {
+      var sum = result.summary;
       expect(sum.hasPlan()).toBe(true); //When there's a profile, there's a plan
       expect(sum.hasProfile()).toBe(true);
       expect(sum.profile.operatorType).toBe('ProduceResults');
@@ -194,9 +196,10 @@ describe('session', function() {
     var driver = neo4j.driver("bolt://localhost");
     var statement = "EXPLAIN MATCH (n), (m) RETURN n, m";
     // When & Then
-    var result = driver.session().run( statement );
-    result.then(function() {
-      var sum = result.summarize();
+    driver.session()
+          .run( statement )
+          .then(function(result) {
+      var sum = result.summary;
       expect(sum.notifications.length).toBeGreaterThan(0);
       expect(sum.notifications[0].code).toBe("Neo.ClientNotification.Statement.CartesianProduct");
       expect(sum.notifications[0].title).toBe("This query builds a cartesian product between disconnected patterns.");