Merge branch 'main' into 3-dev

Author: angrykoala

docs/modules/ROOT/content-nav.adoc

@@ -2,9 +2,9 @@
 * Getting started
 ** xref:getting-started/installation.adoc[]
 ** xref:getting-started/querying.adoc[]
+** xref:getting-started/connecting-to-neo4j.adoc[]
 ** xref:getting-started/filters-and-projections.adoc[]
 ** xref:getting-started/relationships-and-advanced-filtering.adoc[]
-** xref:getting-started/connecting-to-neo4j.adoc[]
 * Building queries
 ** Clauses
 *** xref:clauses/match.adoc[]

docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc

@@ -27,10 +27,7 @@ CREATE(:Movie {title: "The Terminal"})
 ----
 
 == Initialize the driver
-Add the following lines to the JavaScript file created in the xref:/getting-started/installation.adoc[Installation] step to initialize the driver:```
-
-I think the link to the JS manual makes it a bit confusing here because the instructions are also featured below, so if that makes sense, removing that notion can be a bit more clarifying.
-
+Add the following lines to the JavaScript file created in the xref:/getting-started/installation.adoc[Installation] step to initialize the driver:
 
 [source, javascript]
 ----

docs/modules/ROOT/pages/getting-started/filters-and-projections.adoc

@@ -18,8 +18,7 @@ It should return only the movie "The Matrix", released in 1999.
 
 == Filtering
 
-Adding filters to a `MATCH` clause has a similar process to how you add the `RETURN` clause.
-Here is how you should proceed:
+Adding filters to a `MATCH` clause is similar to how you add the `RETURN` clause:
 
 . Use the method `.where`:
 +
@@ -31,38 +30,41 @@ const clause = new Cypher.Match(new Cypher.Pattern(movieNode, { labels: ["Movie"
     .return(movieNode);
 ----
 
-. Then, add a condition to the filter:
+. Then, to add a condition to the filter, for example:
 +
 [source, cypher]
 ----
 m.title = "The Matrix"
 ----
 
-. Use the function `Cypher.eq()` to add the property `title` of the `movieNode` variable and compare them with an equality operator (`=`):
+.. Use the function `Cypher.eq()` to add an **eq**uality operator (`=`) in where:
++
+[source, javascript]
+----
+    .where(Cypher.eq())
+----
+
+.. `Cypher.eq()` takes two arguments to compare. For the first one, add the property `title` of `movieNode`: 
 +
 [source, javascript]
 ----
 movieNode.property("title") 
 ----
 
-. Use the `Cypher.Param` class to add the string `"The Matrix"` as a parameter.
-It will replace the value with a suitable placeholder:
+.. The second argument is the value to compare (`"The Matrix"`). Pass it as a link:https://neo4j.com/docs/cypher-manual/current/syntax/parameters/[Parameter] with `new Cypher.Param`
 +
 [source, javascript]
 ----
 new Cypher.Param("The Matrix")
 ----
 +
-[NOTE]
-====
-Though it is possible to inject the string value into the query, it is good practice to use link:https://neo4j.com/docs/cypher-manual/current/syntax/parameters/[Parameters]. 
-====
+`Cypher.Param` will replace the string with a suitable `$param`, to avoid injecting values directly into the generated Cypher.
 
-. Finally, your `MATCH` clause should now look like this:
+. Your `MATCH` clause should now look like this:
 +
 [source, javascript]
 ----
-const clause = new Cypher.Match(new Cypher.Pattern(movieNode, { labels: ["Movie"] }))
+const clause = new Cypher.Match(new (movieNode, { labels: ["Movie"] }))
     .where(Cypher.eq(movieNode.property("title"), new Cypher.Param("The Matrix")))
     .return(movieNode);
 ----

docs/modules/ROOT/pages/getting-started/installation.adoc

@@ -19,7 +19,7 @@ This guide shows how to start using Cypher Builder by setting up a Node.js proje
 npm init es6 -y
 ----
 +
-Note that these examples use ES6 modules, but CommonJS modules can be used as well.
+Note that these examples use ES modules, but CommonJS modules can be used as well.
 
 
 . Install link:https://www.npmjs.com/package/@neo4j/cypher-builder[`@neo4j/cypher-builder`] and add it to the dependencies list with the following command: 

docs/modules/ROOT/pages/getting-started/querying.adoc

@@ -69,7 +69,6 @@ import Cypher from "@neo4j/cypher-builder";
 const movieNode = new Cypher.Node();
 
 const matchPattern = new Cypher.Pattern(movieNode, { labels: ["Movie"] });
-
 const clause = new Cypher.Match(matchPattern).return(movieNode);
 
 const { cypher } = clause.build();
@@ -89,5 +88,3 @@ RETURN this0
 ====
 Note that `this0` is an autogenerated name for the Node variable created by the Cypher Builder. 
 ====
-
-To create more complex queries, refer to the tutorial on xref:/getting-started/filters-and-projections.adoc[Filtering and projection].

docs/modules/ROOT/pages/getting-started/relationships-and-advanced-filtering.adoc

@@ -29,21 +29,19 @@ Querying it on the Movies Dataset should prompt this result:
 | "The Replacements" | "Pain heals, Chicks dig scars... Glory lasts forever" | 2000 | ["Shane Falco"]
 |===
 
-Though the `Cypher.Match` statement accepts a `Cypher.Node` variable, this is a shorthand for very simple queries involving a single node. 
-For more complex `MATCH` statements, like the one in this tutorial, you should define a *Pattern* when establishing relationships.
-
 == Pattern creation
 
-These are the steps you should follow to define a more complex pattern:
+To define a more complex pattern:
 
-. Define the elements of the pattern. 
+. Define the variables of the pattern. 
 Relationships, just like nodes, are variables that can be created and reused across your query:
 +
 [source, javascript]
 ----
-const actedIn = new Cypher.Relationship();
-
+const movieNode = new Cypher.Node();
 const personNode = new Cypher.Node();
+
+const actedIn = new Cypher.Relationship();
 ----
 +
 So far, the relationship is not connected to the nodes. 
@@ -60,7 +58,7 @@ const pattern = new Cypher.Pattern(movieNode, { labels: ["Movie"] })
 +
 Note that, in Cypher Builder, patterns work similarly to Cypher, with each element of the chain being either a relationship or a node.
 
-. Switch the `movieNode` variable for the `pattern` in the `MATCH` clause:
+. Use the `pattern` variable in the `MATCH` clause:
 +
 [source, javascript]
 ----
@@ -185,7 +183,7 @@ Make sure to double-check whether all variables refer to the correct param and n
 
 == Projection aliases
 
-Lastly, here is how you can add projection aliases:
+Lastly, you can add projection aliases:
 
 . To return `r.roles` aliased as `actingRoles`, add `roles` to the list of properties:
 +