Updates to the Readme File

README.md

@@ -2,7 +2,7 @@
 
 This is the official Neo4j driver for JavaScript.
 
-Starting with 5.0, the Neo4j Drivers will be moving to a monthly release cadence. A minor version will be released on the last Friday of each month so as to maintain versioning consistency with the core product (Neo4j DBMS) which has also moved to a monthly cadence.
+As of the 5.28.0 LTS release, the driver is no longer on a monthly release cadence. Minor version releases will happen when there are sufficient new features or improvements to warrant them. This is to reduce the required work of users updating their driver. 
 
 As a policy, patch versions will not be released except on rare occasions. Bug fixes and updates will go into the latest minor version and users should upgrade to that. Driver upgrades within a major version will never contain breaking API changes.
 
@@ -38,10 +38,13 @@ Please note that `@next` only points to pre-releases that are not suitable for p
 To get the latest stable release omit `@next` part altogether or use `@latest` instead.
 
 ```javascript
+// If you are using CommonJS
 var neo4j = require('neo4j-driver')
+// Alternatively, if you are using ES6
+import neo4j from 'neo4j-driver'
 ```
 
-Driver instance should be closed when Node.js application exits:
+Driver instance should be closed when the application exits:
 
 ```javascript
 driver.close() // returns a Promise
@@ -223,7 +226,7 @@ readTxResultPromise
   .catch(error => {
     console.log(error)
   })
-  .then(() => session.close())
+  .finally(() => session.close())
 ```
 
 #### Reading with Reactive Session
@@ -267,7 +270,7 @@ writeTxResultPromise
   .catch(error => {
     console.log(error)
   })
-  .then(() => session.close())
+  .finally(() => session.close())
 ```
 
 #### Writing with Reactive Session
@@ -276,7 +279,7 @@ writeTxResultPromise
 rxSession
   .executeWrite(txc =>
     txc
-      .run("MERGE (alice:Person {name: 'James'}) RETURN alice.name AS name")
+      .run("MERGE (alice:Person {name: 'Alice'}) RETURN alice.name AS name")
       .records()
       .pipe(map(record => record.get('name')))
   )
@@ -287,74 +290,62 @@ rxSession
   })
 ```
 
-### Consuming Records
-
-#### Consuming Records with Streaming API
+### ExecuteQuery Function
 
 ```javascript
-// Run a Cypher statement, reading the result in a streaming manner as records arrive:
-session
-  .run('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', {
-    nameParam: 'Alice'
-  })
-  .subscribe({
-    onKeys: keys => {
-      console.log(keys)
-    },
-    onNext: record => {
-      console.log(record.get('name'))
-    },
-    onCompleted: () => {
-      session.close() // returns a Promise
-    },
-    onError: error => {
-      console.log(error)
+// Since 5.8.0, the driver has offered a way to run a single query transaction with minimal boilerplate.
+// The driver.executeQuery() function features the same automatic retries as transaction functions.
+// 
+var executeQueryResultPromise = driver
+  .executeQuery(
+    "MATCH (alice:Person {name: $nameParam}) RETURN alice.DOB AS DateOfBirth", 
+    {
+      nameParam: 'Alice'
+    }, 
+    {
+      routing: 'READ', 
+      database: 'neo4j'
     }
-  })
-```
-
-Subscriber API allows following combinations of `onKeys`, `onNext`, `onCompleted` and `onError` callback invocations:
-
-- zero or one `onKeys`,
-- 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.
-
-#### Consuming Records with Promise API
+  )
 
-```javascript
-// the Promise way, where the complete result is collected before we act on it:
-session
-  .run('MERGE (james:Person {name : $nameParam}) RETURN james.name AS name', {
-    nameParam: 'James'
-  })
+// returned Promise can be later consumed like this:
+executeQueryResultPromise
   .then(result => {
-    result.records.forEach(record => {
-      console.log(record.get('name'))
-    })
+    console.log(result.records)
   })
   .catch(error => {
     console.log(error)
   })
-  .then(() => session.close())
 ```
 
-#### Consuming Records with Reactive API
+### Auto-Commit/Implicit Transaction
 
 ```javascript
-rxSession
-  .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', {
-    nameParam: 'Bob'
-  })
-  .records()
-  .pipe(
-    map(record => record.get('name')),
-    concatWith(rxSession.close())
+// This is the most basic and limited form with which to run a Cypher query. 
+// The driver will not automatically retry implicit transactions.
+// This function should only be used when the other driver query interfaces do not fit the purpose.
+// Implicit transactions are the only ones that can be used for CALL { …​ } IN TRANSACTIONS queries. 
+
+var implicitTxResultPromise = session
+  .run(
+    "CALL { …​ } IN TRANSACTIONS", 
+    {
+      param1: 'param'
+    }, 
+    {
+      database: 'neo4j'
+    }
   )
-  .subscribe({
-    next: data => console.log(data),
-    complete: () => console.log('completed'),
-    error: err => console.log(err)
+
+// returned Promise can be later consumed like this:
+implicitTxResultPromise
+  .then(result => {
+    console.log(result.records)
+  })
+  .catch(error => {
+    console.log(error)
   })
+  .finally(() => session.close())
 ```
 
 ### Explicit Transactions
@@ -434,6 +425,80 @@ rxSession
   })
 ```
 
+### Consuming Records
+
+#### Consuming Records with Streaming API
+
+```javascript
+// Run a Cypher statement, reading the result in a streaming manner as records arrive:
+session
+  .executeWrite(tx => {
+    return tx.run('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', {
+      nameParam: 'Alice'
+    })
+    .subscribe({
+      onKeys: keys => {
+        console.log(keys)
+      },
+      onNext: record => {
+        console.log(record.get('name'))
+      },
+      onCompleted: () => {
+        session.close() // returns a Promise
+      },
+      onError: error => {
+        console.log(error)
+      }
+    })
+  })
+```
+
+Subscriber API allows following combinations of `onKeys`, `onNext`, `onCompleted` and `onError` callback invocations:
+
+- zero or one `onKeys`,
+- 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.
+
+#### Consuming Records with Promise API
+
+```javascript
+// the Promise way, where the complete result is collected before we act on it:
+driver
+  .executeQuery('MERGE (james:Person {name : $nameParam}) RETURN james.name AS name', {
+    nameParam: 'James'
+  })
+  .then(result => {
+    result.records.forEach(record => {
+      console.log(record.get('name'))
+    })
+  })
+  .catch(error => {
+    console.log(error)
+  })
+```
+
+#### Consuming Records with Reactive API
+
+```javascript
+rxSession
+  .executeWrite(txc =>
+    txc
+      .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', {
+        nameParam: 'James'
+      })
+      .records()
+    )
+  .pipe(
+    map(record => record.get('name')),
+    concatWith(session.close())
+  )
+  .subscribe({
+    next: data => console.log(data),
+    complete: () => console.log('completed'),
+    error: err => console.log(err)
+  })
+```
+
 ### Numbers and the Integer type
 
 The Neo4j type system uses 64-bit signed integer values. The range of values is between `-(2`<sup>`64`</sup>`- 1)` and `(2`<sup>`63`</sup>`- 1)`.
@@ -447,20 +512,20 @@ _**Any javascript number value passed as a parameter will be recognized as `Floa
 
 #### Writing integers
 
-Numbers written directly e.g. `session.run("CREATE (n:Node {age: $age})", {age: 22})` will be of type `Float` in Neo4j.
+Numbers written directly e.g. `driver.executeQuery("CREATE (n:Node {age: $age})", {age: 22})` will be of type `Float` in Neo4j.
 
 To write the `age` as an integer the `neo4j.int` method should be used:
 
 ```javascript
 var neo4j = require('neo4j-driver')
 
-session.run('CREATE (n {age: $myIntParam})', { myIntParam: neo4j.int(22) })
+driver.executeQuery('CREATE (n {age: $myIntParam})', { myIntParam: neo4j.int(22) })
 ```
 
 To write an integer value that are not within the range of `Number.MIN_SAFE_INTEGER` `-(2`<sup>`53`</sup>`- 1)` and `Number.MAX_SAFE_INTEGER` `(2`<sup>`53`</sup>`- 1)`, use a string argument to `neo4j.int`:
 
 ```javascript
-session.run('CREATE (n {age: $myIntParam})', {
+driver.executeQuery('CREATE (n {age: $myIntParam})', {
   myIntParam: neo4j.int('9223372036854775807')
 })
 ```