Merge pull request #186 from lutovich/1.1-doc-improvements

README improvements

Author: Zhen Li

README.md

@@ -31,6 +31,13 @@ To get the latest stable release omit `@next` part altogether or use `@latest` i
 ```javascript
 var neo4j = require('neo4j-driver').v1;
 ```
+Driver instance should be closed when Node.js application exits:
+
+```javascript
+driver.close();
+```
+
+otherwise application shutdown might hang or it might exit with a non-zero exit code.
 
 ## Include in web browser
 
@@ -46,13 +53,33 @@ This will make a global `neo4j` object available, where you can access the `v1`
 var driver = neo4j.driver("bolt://localhost", neo4j.auth.basic("neo4j", "neo4j"));
 ```
 
+It is not required to explicitly close the driver on a web page. Web browser should gracefully close all open 
+WebSockets when the page is unloaded. However, driver instance should be explicitly closed when it's lifetime
+is not the same as the lifetime of the web page:
+ 
+```javascript
+driver.close();
+```
+
 ## Usage examples
 
 ```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() {
+  // 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) {
+  console.log('Driver instantiation failed', error);
+};
+
 // 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();
@@ -122,8 +149,18 @@ if (success) {
   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:
+ * zero or more `onNext` followed by `onCompleted` when operation was successful. `onError` will not be invoked 
+ in this case
+ * zero or more `onNext` followed by `onError` when operation failed. Callback `onError` might be invoked after 
+ couple `onNext` invocations because records are streamed lazily by the database. `onCompleted` will not be invoked 
+ in this case
+
 ## Building
 
     npm install