From 8424b5810ba97c98773524b9427d6d1c4ed80f49 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Mon, 17 Feb 2025 08:33:19 +0100 Subject: [PATCH 01/10] bring package readme into sync --- packages/neo4j-driver/README.md | 148 ++++++++++++++++---------------- 1 file changed, 74 insertions(+), 74 deletions(-) diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index a81d231a4..b176bd13c 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -188,76 +188,6 @@ var rxSession = driver.rxSession({ }) ``` -### Executing Queries - -#### Consuming Records with Streaming API - -```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) - } - }) -``` - -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' - }) - .then(result => { - result.records.forEach(record => { - console.log(record.get('name')) - }) - }) - .catch(error => { - console.log(error) - }) - .then(() => session.close()) -``` - -#### Consuming Records with Reactive API - -```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()) - ) - .subscribe({ - next: data => console.log(data), - complete: () => console.log('completed'), - error: err => console.log(err) - }) -``` - ### Transaction functions ```javascript @@ -276,7 +206,7 @@ neo4j.driver('neo4j://localhost', neo4j.auth.basic('neo4j', 'password'), { // It is possible to execute read transactions that will benefit from automatic // retries on both single instance ('bolt' URI scheme) and Causal Cluster // ('neo4j' URI scheme) and will get automatic load balancing in cluster deployments -var readTxResultPromise = session.readTransaction(txc => { +var readTxResultPromise = session.executeRead(txc => { // used transaction will be committed automatically, no need for explicit commit/rollback var result = txc.run('MATCH (person:Person) RETURN person.name AS name') @@ -300,7 +230,7 @@ readTxResultPromise ```javascript rxSession - .readTransaction(txc => + .executeRead(txc => txc .run('MATCH (person:Person) RETURN person.name AS name') .records() @@ -318,7 +248,7 @@ rxSession ```javascript // It is possible to execute write transactions that will benefit from automatic retries // on both single instance ('bolt' URI scheme) and Causal Cluster ('neo4j' URI scheme) -var writeTxResultPromise = session.writeTransaction(async txc => { +var writeTxResultPromise = session.executeWrite(async txc => { // used transaction will be committed automatically, no need for explicit commit/rollback var result = await txc.run( @@ -344,7 +274,7 @@ writeTxResultPromise ```javascript rxSession - .writeTransaction(txc => + .executeWrite(txc => txc .run("MERGE (alice:Person {name: 'James'}) RETURN alice.name AS name") .records() @@ -357,6 +287,76 @@ rxSession }) ``` +### Consuming Records + +#### Consuming Records with Streaming API + +```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) + } + }) +``` + +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' + }) + .then(result => { + result.records.forEach(record => { + console.log(record.get('name')) + }) + }) + .catch(error => { + console.log(error) + }) + .then(() => session.close()) +``` + +#### Consuming Records with Reactive API + +```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()) + ) + .subscribe({ + next: data => console.log(data), + complete: () => console.log('completed'), + error: err => console.log(err) + }) +``` + ### Explicit Transactions #### With Async Session From f6b1b2ffd1efd60843adb5632e4c39857023c00c Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Mon, 17 Feb 2025 16:00:31 +0100 Subject: [PATCH 02/10] replace session.run with other functions --- README.md | 23 +++++++++++++---------- packages/neo4j-driver/README.md | 23 +++++++++++++---------- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b176bd13c..418c6e612 100644 --- a/README.md +++ b/README.md @@ -293,8 +293,8 @@ rxSession ```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', { +driver + .executeQuery('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', { nameParam: 'Alice' }) .subscribe({ @@ -323,8 +323,8 @@ Subscriber API allows following combinations of `onKeys`, `onNext`, `onCompleted ```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', { +driver + .executeQuery('MERGE (james:Person {name : $nameParam}) RETURN james.name AS name', { nameParam: 'James' }) .then(result => { @@ -342,9 +342,12 @@ session ```javascript rxSession - .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { - nameParam: 'Bob' - }) + .executeRead(txc => + txc + .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { + nameParam: 'Bob' + }) + ) .records() .pipe( map(record => record.get('name')), @@ -447,20 +450,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``53``- 1)` and `Number.MAX_SAFE_INTEGER` `(2``53``- 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') }) ``` diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index b176bd13c..418c6e612 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -293,8 +293,8 @@ rxSession ```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', { +driver + .executeQuery('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', { nameParam: 'Alice' }) .subscribe({ @@ -323,8 +323,8 @@ Subscriber API allows following combinations of `onKeys`, `onNext`, `onCompleted ```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', { +driver + .executeQuery('MERGE (james:Person {name : $nameParam}) RETURN james.name AS name', { nameParam: 'James' }) .then(result => { @@ -342,9 +342,12 @@ session ```javascript rxSession - .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { - nameParam: 'Bob' - }) + .executeRead(txc => + txc + .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { + nameParam: 'Bob' + }) + ) .records() .pipe( map(record => record.get('name')), @@ -447,20 +450,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``53``- 1)` and `Number.MAX_SAFE_INTEGER` `(2``53``- 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') }) ``` From ae8396c7b90595e927e96a7d6c0025dac2ce58d0 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Tue, 18 Feb 2025 13:26:11 +0100 Subject: [PATCH 03/10] Descibe autocommit tx and executequery --- README.md | 165 ++++++++++++++++++++------------ packages/neo4j-driver/README.md | 165 ++++++++++++++++++++------------ 2 files changed, 204 insertions(+), 126 deletions(-) diff --git a/README.md b/README.md index 418c6e612..b8b41cd93 100644 --- a/README.md +++ b/README.md @@ -287,77 +287,43 @@ 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: -driver - .executeQuery('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: -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) - }) - .then(() => session.close()) + ) ``` -#### Consuming Records with Reactive API +### Auto-Commit/Implicit Transaction ```javascript -rxSession - .executeRead(txc => - txc - .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) - }) ``` ### Explicit Transactions @@ -437,6 +403,79 @@ rxSession }) ``` +### Consuming Records + +#### Consuming Records with Streaming API + +```javascript +// Run a Cypher statement, reading the result in a streaming manner as records arrive: +driver + .executeQuery('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) + }) + .then(() => session.close()) +``` + +#### Consuming Records with Reactive API + +```javascript +rxSession + .executeRead(txc => + txc + .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { + nameParam: 'Bob' + }) + ) + .records() + .pipe( + map(record => record.get('name')), + concatWith(rxSession.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``64``- 1)` and `(2``63``- 1)`. diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index 418c6e612..b8b41cd93 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -287,77 +287,43 @@ 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: -driver - .executeQuery('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: -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) - }) - .then(() => session.close()) + ) ``` -#### Consuming Records with Reactive API +### Auto-Commit/Implicit Transaction ```javascript -rxSession - .executeRead(txc => - txc - .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) - }) ``` ### Explicit Transactions @@ -437,6 +403,79 @@ rxSession }) ``` +### Consuming Records + +#### Consuming Records with Streaming API + +```javascript +// Run a Cypher statement, reading the result in a streaming manner as records arrive: +driver + .executeQuery('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) + }) + .then(() => session.close()) +``` + +#### Consuming Records with Reactive API + +```javascript +rxSession + .executeRead(txc => + txc + .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { + nameParam: 'Bob' + }) + ) + .records() + .pipe( + map(record => record.get('name')), + concatWith(rxSession.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``64``- 1)` and `(2``63``- 1)`. From 24ef51077936adc7a5b49c6944b9285c93ebb1b6 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Tue, 18 Feb 2025 15:26:31 +0100 Subject: [PATCH 04/10] Add ES6 import guide --- README.md | 3 +++ packages/neo4j-driver/README.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/README.md b/README.md index b8b41cd93..28f03370c 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,10 @@ 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: diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index b8b41cd93..28f03370c 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -38,7 +38,10 @@ 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: From feb0f77ae8953beb79abbee63cdf6706464accf4 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:34:23 +0100 Subject: [PATCH 05/10] add result consumption to run and executequery --- README.md | 19 +++++++++++++++++++ packages/neo4j-driver/README.md | 19 +++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/README.md b/README.md index 28f03370c..e763cd3ba 100644 --- a/README.md +++ b/README.md @@ -307,6 +307,15 @@ var executeQueryResultPromise = driver database: 'neo4j' } ) + +// returned Promise can be later consumed like this: +executeQueryResultPromise + .then(result => { + console.log(result.records) + }) + .catch(error => { + console.log(error) + }) ``` ### Auto-Commit/Implicit Transaction @@ -327,6 +336,16 @@ var implicitTxResultPromise = session database: 'neo4j' } ) + +// returned Promise can be later consumed like this: +implicitTxResultPromise + .then(result => { + console.log(result.records) + }) + .catch(error => { + console.log(error) + }) + .then(() => session.close()) ``` ### Explicit Transactions diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index 28f03370c..e763cd3ba 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -307,6 +307,15 @@ var executeQueryResultPromise = driver database: 'neo4j' } ) + +// returned Promise can be later consumed like this: +executeQueryResultPromise + .then(result => { + console.log(result.records) + }) + .catch(error => { + console.log(error) + }) ``` ### Auto-Commit/Implicit Transaction @@ -327,6 +336,16 @@ var implicitTxResultPromise = session database: 'neo4j' } ) + +// returned Promise can be later consumed like this: +implicitTxResultPromise + .then(result => { + console.log(result.records) + }) + .catch(error => { + console.log(error) + }) + .then(() => session.close()) ``` ### Explicit Transactions From 573b64573d8f653b9373ff6ae5deb8785e470d10 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Wed, 12 Mar 2025 12:40:11 +0100 Subject: [PATCH 06/10] Editorial changes --- README.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e763cd3ba..e66395cb1 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ import neo4j from 'https://cdn.jsdelivr.net/npm/neo4j-driver@X.Y.Z/lib/browser/n ``` 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 +WebSockets when the page is unloaded. However, driver instance should be explicitly closed when its lifetime is not the same as the lifetime of the web page: ```javascript @@ -116,13 +116,13 @@ driver.close() // returns a Promise ```javascript // Create a driver instance, for the user `neo4j` with password `password`. -// It should be enough to have a single driver per database per application. +// It should be enough to have a single driver per DBMS per application. var driver = neo4j.driver( 'neo4j://localhost', neo4j.auth.basic('neo4j', 'password') ) -// Close the driver when application exits. +// Close the driver when the application exits. // This closes all used network connections. await driver.close() ``` @@ -295,15 +295,14 @@ rxSession ```javascript // 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", + "MATCH (alice:Person {name: $nameParam}) RETURN alice.DOB AS DateOfBirth", { nameParam: 'Alice' - }, + }, { - routing: 'READ', + routing: 'READ', database: 'neo4j' } ) @@ -321,17 +320,17 @@ executeQueryResultPromise ### Auto-Commit/Implicit Transaction ```javascript -// This is the most basic and limited form with which to run a Cypher query. +// 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. +// Implicit transactions are the only ones that can be used for CALL { … } IN TRANSACTIONS queries. var implicitTxResultPromise = session .run( - "CALL { …​ } IN TRANSACTIONS", + "CALL { … } IN TRANSACTIONS", { param1: 'param' - }, + }, { database: 'neo4j' } From a70e28061e92b5469c6cab89fcf4db72be095cf4 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Tue, 18 Mar 2025 13:30:43 +0100 Subject: [PATCH 07/10] addressing some comments --- README.md | 38 +++++++++++++++++---------------- packages/neo4j-driver/README.md | 17 ++++++++------- 2 files changed, 29 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e66395cb1..f65a1fa8a 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ var neo4j = require('neo4j-driver') 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 @@ -103,7 +103,7 @@ import neo4j from 'https://cdn.jsdelivr.net/npm/neo4j-driver@X.Y.Z/lib/browser/n ``` 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 its lifetime +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 @@ -116,13 +116,13 @@ driver.close() // returns a Promise ```javascript // Create a driver instance, for the user `neo4j` with password `password`. -// It should be enough to have a single driver per DBMS per application. +// It should be enough to have a single driver per database per application. var driver = neo4j.driver( 'neo4j://localhost', neo4j.auth.basic('neo4j', 'password') ) -// Close the driver when the application exits. +// Close the driver when application exits. // This closes all used network connections. await driver.close() ``` @@ -226,7 +226,7 @@ readTxResultPromise .catch(error => { console.log(error) }) - .then(() => session.close()) + .finally(() => session.close()) ``` #### Reading with Reactive Session @@ -270,7 +270,7 @@ writeTxResultPromise .catch(error => { console.log(error) }) - .then(() => session.close()) + .finally(() => session.close()) ``` #### Writing with Reactive Session @@ -295,14 +295,15 @@ rxSession ```javascript // 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", + "MATCH (alice:Person {name: $nameParam}) RETURN alice.DOB AS DateOfBirth", { nameParam: 'Alice' - }, + }, { - routing: 'READ', + routing: 'READ', database: 'neo4j' } ) @@ -320,17 +321,17 @@ executeQueryResultPromise ### Auto-Commit/Implicit Transaction ```javascript -// This is the most basic and limited form with which to run a Cypher query. +// 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. +// Implicit transactions are the only ones that can be used for CALL { …​ } IN TRANSACTIONS queries. var implicitTxResultPromise = session .run( - "CALL { … } IN TRANSACTIONS", + "CALL { …​ } IN TRANSACTIONS", { param1: 'param' - }, + }, { database: 'neo4j' } @@ -344,7 +345,7 @@ implicitTxResultPromise .catch(error => { console.log(error) }) - .then(() => session.close()) + .finally(() => session.close()) ``` ### Explicit Transactions @@ -430,9 +431,11 @@ rxSession ```javascript // Run a Cypher statement, reading the result in a streaming manner as records arrive: -driver - .executeQuery('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', { - nameParam: 'Alice' +session + .executeWrite(tx => { + return tx.run('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', { + nameParam: 'Alice' + }) }) .subscribe({ onKeys: keys => { @@ -472,7 +475,6 @@ driver .catch(error => { console.log(error) }) - .then(() => session.close()) ``` #### Consuming Records with Reactive API diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index e763cd3ba..f65a1fa8a 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -44,7 +44,7 @@ var neo4j = require('neo4j-driver') 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 @@ -226,7 +226,7 @@ readTxResultPromise .catch(error => { console.log(error) }) - .then(() => session.close()) + .finally(() => session.close()) ``` #### Reading with Reactive Session @@ -270,7 +270,7 @@ writeTxResultPromise .catch(error => { console.log(error) }) - .then(() => session.close()) + .finally(() => session.close()) ``` #### Writing with Reactive Session @@ -345,7 +345,7 @@ implicitTxResultPromise .catch(error => { console.log(error) }) - .then(() => session.close()) + .finally(() => session.close()) ``` ### Explicit Transactions @@ -431,9 +431,11 @@ rxSession ```javascript // Run a Cypher statement, reading the result in a streaming manner as records arrive: -driver - .executeQuery('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', { - nameParam: 'Alice' +session + .executeWrite(tx => { + return tx.run('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', { + nameParam: 'Alice' + }) }) .subscribe({ onKeys: keys => { @@ -473,7 +475,6 @@ driver .catch(error => { console.log(error) }) - .then(() => session.close()) ``` #### Consuming Records with Reactive API From 69d3281163929b1f7e2ef986c255758d389c3993 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Tue, 18 Mar 2025 15:03:57 +0100 Subject: [PATCH 08/10] fixes to code snippets --- README.md | 38 ++++++++++++++++----------------- packages/neo4j-driver/README.md | 38 ++++++++++++++++----------------- 2 files changed, 38 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index f65a1fa8a..cabafc6ee 100644 --- a/README.md +++ b/README.md @@ -436,20 +436,20 @@ session 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) - } + .subscribe({ + onKeys: keys => { + console.log(keys) + }, + onNext: record => { + console.log(record.get('name')) + }, + onCompleted: () => { + session.close() // returns a Promise + }, + onError: error => { + console.log(error) + } + }) }) ``` @@ -481,16 +481,16 @@ driver ```javascript rxSession - .executeRead(txc => + .executeWrite(txc => txc .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { nameParam: 'Bob' - }) - ) - .records() + }) + .records() + ) .pipe( map(record => record.get('name')), - concatWith(rxSession.close()) + concatWith(session.close()) ) .subscribe({ next: data => console.log(data), diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index f65a1fa8a..cabafc6ee 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -436,20 +436,20 @@ session 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) - } + .subscribe({ + onKeys: keys => { + console.log(keys) + }, + onNext: record => { + console.log(record.get('name')) + }, + onCompleted: () => { + session.close() // returns a Promise + }, + onError: error => { + console.log(error) + } + }) }) ``` @@ -481,16 +481,16 @@ driver ```javascript rxSession - .executeRead(txc => + .executeWrite(txc => txc .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { nameParam: 'Bob' - }) - ) - .records() + }) + .records() + ) .pipe( map(record => record.get('name')), - concatWith(rxSession.close()) + concatWith(session.close()) ) .subscribe({ next: data => console.log(data), From 996fda2d0d672dbe612c26c947119ecf7c3501c5 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Tue, 18 Mar 2025 15:19:26 +0100 Subject: [PATCH 09/10] align names to reduce confusion --- README.md | 4 ++-- packages/neo4j-driver/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index cabafc6ee..c2cf8a4bc 100644 --- a/README.md +++ b/README.md @@ -279,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'))) ) @@ -484,7 +484,7 @@ rxSession .executeWrite(txc => txc .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { - nameParam: 'Bob' + nameParam: 'James' }) .records() ) diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index cabafc6ee..c2cf8a4bc 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -279,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'))) ) @@ -484,7 +484,7 @@ rxSession .executeWrite(txc => txc .run('MERGE (james:Person {name: $nameParam}) RETURN james.name AS name', { - nameParam: 'Bob' + nameParam: 'James' }) .records() ) From 1980a72b983db9d9fd57d85fb0ab52bc2f4c8870 Mon Sep 17 00:00:00 2001 From: MaxAake <61233757+MaxAake@users.noreply.github.com> Date: Wed, 19 Mar 2025 10:08:58 +0100 Subject: [PATCH 10/10] release cadence --- README.md | 2 +- packages/neo4j-driver/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c2cf8a4bc..5bf5dfc09 100644 --- a/README.md +++ b/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. diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index c2cf8a4bc..5bf5dfc09 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/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.