Cypher Builder version 3

.changeset/all-signs-live.md

@@ -0,0 +1,5 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove type `Cypher.Operation` in favor of `Cypher.Expr`

.changeset/blue-ends-relate.md

@@ -0,0 +1,11 @@
+---
+"@neo4j/cypher-builder": patch
+---
+
+Add support for `Cypher 25` version prefix:
+
+```js
+const { cypher } = matchQuery.build({
+    cypherVersion: "25",
+});
+```

.changeset/bright-meals-arrive.md

@@ -0,0 +1,5 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+ListComprehension `.in` method no longer throws if called twice. It will instead override the expression

.changeset/clean-items-greet.md

@@ -0,0 +1,23 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove second parameter of `ListComprehension` in favor of `.in`
+
+_Before_
+
+```js
+new Cypher.ListComprehension(variable, new Cypher.Literal([1, 2]));
+```
+
+_After_
+
+```js
+new Cypher.ListComprehension(variable).in(new Cypher.Literal([1, 2]));
+```
+
+In both cases, the same comprehension will be generated:
+
+```cypher
+[var0 IN [1, 2]]
+```

.changeset/common-cycles-obey.md

@@ -0,0 +1,13 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove support for patterns in size.
+
+_No longer supported_
+
+```js
+Cypher.size(new Cypher.Pattern(node));
+```
+
+Use `new Cypher.Count(pattern)` instead.

.changeset/cool-signs-start.md

@@ -0,0 +1,5 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Updates minimum node engine to 20.0.0

.changeset/easy-horses-repeat.md

@@ -0,0 +1,25 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove labelOperator, all labels will now use operator `&`
+
+No longer supported:
+
+```js
+const { cypher, params } = matchQuery.build({
+    labelOperator: "&",
+});
+```
+
+_Before_
+
+```cypher
+MATCH (this1:Movie:Film)
+```
+
+_After_
+
+```cypher
+MATCH (this1:Movie&Film)
+```

.changeset/fine-roses-film.md

@@ -0,0 +1,30 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove all apoc functions and procedures:
+
+- `apoc.util.validate`
+- `apoc.util.validatePredicate`
+- `apoc.date.convertFormat`
+- `apoc.cypher.runFirstColumnMany`
+- `apoc.cypher.runFirstColumnSingle`
+
+In order to use apoc methods, create a custom function or procedure. For example:
+
+```js
+function validate(
+    predicate: Predicate,
+    message: string,
+    params: List | Literal | Map
+): VoidCypherProcedure {
+    return new VoidCypherProcedure("apoc.util.validate", [predicate,  new Literal(message), params]);
+}
+```
+
+```js
+function validatePredicate(predicate: Predicate, message: string): CypherFunction {
+    return new CypherFunction("apoc.util.validatePredicate", [predicate, new Literal(message), new Literal([0])]);
+}
+
+```

.changeset/floppy-llamas-teach.md

@@ -0,0 +1,10 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove method `.children` from concat clauses:
+
+```js
+const query = Cypher.utils.concat(clause1, clause2);
+query.children; // No longer supported
+```

.changeset/sharp-women-kick.md

@@ -0,0 +1,30 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove `.importWith` from `Call` clauses in favor of constructor options
+
+_Before_
+
+```js
+const clause = new Cypher.Call(nestedClause).importWith(movieNode, actorNode);
+```
+
+```cypher
+CALL {
+    WITH var0, var1
+    // Nested clause
+}
+```
+
+_After_
+
+```js
+const clause = new Cypher.Call(nestedClause, [movieNode, actorNode]);
+```
+
+```cypher
+CALL (var0, var1){
+    // Nested clause
+}
+```

.changeset/thin-radios-poke.md

@@ -0,0 +1,8 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove functions deprecated in Cypher 5:
+
+- `distance` in favor of `point.distance`
+- `id` in favor of `elementId`

.changeset/violet-sloths-hug.md

@@ -0,0 +1,45 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove extra parameters in `Cypher.Foreach` in favor of methods `in` and `do`.
+
+For example, to create the following Cypher:
+
+```cypher
+FOREACH (var0 IN [1, 2, 3] |
+        CREATE (this1:Movie)
+        SET
+            this1.id = var0
+    )
+```
+
+_before_
+
+```js
+const list = new Cypher.Literal([1, 2, 3]);
+const variable = new Cypher.Variable();
+
+const movieNode = new Cypher.Node();
+const createMovie = new Cypher.Create(new Cypher.Pattern(movieNode, { labels: ["Movie"] })).set([
+    movieNode.property("id"),
+    variable,
+]);
+
+const foreachClause = new Cypher.Foreach(variable, list, createMovie);
+```
+
+_after_
+
+```js
+const list = new Cypher.Literal([1, 2, 3]);
+const variable = new Cypher.Variable();
+
+const movieNode = new Cypher.Node();
+const createMovie = new Cypher.Create(new Cypher.Pattern(movieNode, { labels: ["Movie"] })).set([
+    movieNode.property("id"),
+    variable,
+]);
+
+const foreachClause = new Cypher.Foreach(variable).in(list).do(createMovie);
+```

.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [16.x, latest]
+        node-version: [20.x, latest]
 
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5

docs/modules/ROOT/content-nav.adoc

@@ -44,6 +44,6 @@
 ** xref:how-to/update-labels.adoc[]
 ** xref:how-to/define-cypher-version.adoc[]
 * xref:compatibility.adoc[]
-* xref:migration-guide-2.adoc[]
+* xref:migration-guide-3.adoc[]
 * link:https://github.com/neo4j/cypher-builder/tree/main/examples[Examples]
 * link:https://neo4j.github.io/cypher-builder/reference/[Reference]

docs/modules/ROOT/pages/build-configuration.adoc

@@ -14,8 +14,7 @@ The method `build` accepts an object with options to configure the build process
 [cols="2,1,1,3",options="header"]
 |===
 | Setting | Type | Default | Description 
-| `labelOperator` | String | `":"` | Define the default operator to use when using multiple labels in a Pattern. It can be either `:` or `&`
-| `cypherVersion` | String | `undefined` | If set, will prepend all queries with a `CYPHER [Version]` statement. The only valid value is `"5"`
+| `cypherVersion` | String | `undefined` | If set, will prepend all queries with a `CYPHER [Version]` statement. The possible values are `"5"` and `"25"`
 | `prefix` | String | `undefined` | If set, will add a prefix to all variable names. See xref:how-to/customize-cypher.adoc#_build_prefix[Customize Cypher]
 | `extraParams` | Object | `{}` | Add the provided parameters to the resulting params object. See xref:variables-and-params/parameters.adoc#_adding_extra_parameters[Parameters]
 | `unsafeEscapeOptions` | Object | `{}` | Set of options to disable escaping from generated Cypher. See xref:_unsafe_escape_options[Unsafe escape options]

docs/modules/ROOT/pages/clauses/with.adoc

@@ -2,7 +2,7 @@
 :description: This page describes how to create `WITH` clauses.
 = With
 
-This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/with/[`WITH`] clause using the `Cypher.With` class. Note that this is different to the xref:../subqueries/call.adoc#_importwith[ImportWith] statement inside `CALL`.
+This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/with/[`WITH`] clause using the `Cypher.With` class.
 
 A `With` clause will take multiple parameters. Variables can be passed directly without aliasing:
 

docs/modules/ROOT/pages/compatibility.adoc

@@ -1,13 +1,13 @@
 [[compatibility]]
-:description: This page outlines the compatibility requirements for `@neo4j/cypher-builder` version 2 with Cypher and Node.js.
+:description: This page outlines the compatibility requirements for `@neo4j/cypher-builder` version 3 with Cypher and Node.js.
 = Compatibility
 
-This page outlines the compatibility requirements for `@neo4j/cypher-builder` version 2 with Cypher and Node.js.
+This page outlines the compatibility requirements for `@neo4j/cypher-builder` version 3 with Cypher and Node.js.
 
-* Targets link:https://neo4j.com/docs/cypher-manual/5/introduction/[Cypher 5], with support for link:https://neo4j.com/docs/cypher-manual/4.4/introduction/[Cypher 4.4].
-* Compatible with Node.js version 16.0.0 and later.
+* Targets link:https://neo4j.com/docs/cypher-manual/25/introduction/[Cypher 25], with support for link:https://neo4j.com/docs/cypher-manual/5/introduction/[Cypher 5].
+* Compatible with Node.js version 20.0.0 and later.
 
 [NOTE]
 ====
-`@neo4j/cypher-builder` version 1 is no longer supported. Version 2 is a full replacement and maintains the same compatibility with Cypher and Node.js.
+If you need to support Neo4j 4, stay with Cypher Builder 2.x, otherwise, xref:migration-guide-3.adoc#migration[migrate to version 3].
 ====

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

@@ -6,7 +6,7 @@ This guide shows how to start using Cypher Builder by setting up a Node.js proje
 
 == Requirements
 
-* link:https://nodejs.org/[Node.js] 16.0.0 or greater
+* link:https://nodejs.org/[Node.js] 20.0.0 or greater
 * link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[npm]
 * **[Optional]** A link:https://neo4j.com/cloud/platform/aura-graph-database/?ref=nav-get-started-cta[Neo4j] database to try Cypher queries.
 

docs/modules/ROOT/pages/how-to/define-cypher-version.adoc

@@ -2,7 +2,7 @@
 :description: This page describes how to define the Cypher version to be used in the query.
 = Define Cypher version
 
-It is possible to define the version of Cypher to use in a query by prepending that query with `CYPHER [version]`. For example:
+It is possible to explicitly define the version of Cypher to use in a query by prepending that query with `CYPHER [version]`. For example:
 
 
 [source, cypher]
@@ -13,7 +13,7 @@ RETURN this0
 ----
 
 
-To add the Cypher version at the beggining of the query, pass the parameter `cypherVersion` to `.build`:
+To add the Cypher version at the beggining of the query, pass the parameter `cypherVersion` to `.build`. The possible values are `"5"` and `"25"`:
 
 [source, javascript]
 ----