Remove assignToPath from clauses

.changeset/shaggy-kangaroos-wink.md

@@ -0,0 +1,5 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove `Path` and `NamedPath` in favor of `PathVariable` and `NamedPathVariable`

.changeset/witty-bottles-juggle.md

@@ -0,0 +1,28 @@
+---
+"@neo4j/cypher-builder": major
+---
+
+Remove `assignToPath` method from clauses, in favor of `assignTo` in Patterns for the following clauses:
+
+-   `Match`
+-   `Merge`
+-   `Create`
+
+Before:
+
+```js
+new Cypher.Match(pattern).assignToPath(pathVariable).return(pathVariable);
+```
+
+Now:
+
+```js
+new Cypher.Match(pattern.assignTo(pathVariable)).return(pathVariable);
+```
+
+Generates the Cypher:
+
+```cypher
+MATCH p = ()-[]-()
+RETURN p
+```

docs/modules/ROOT/pages/migration-guide-2.adoc

@@ -144,6 +144,37 @@ The generated Cypher:
 
 Note that labels and types are now defined in the Pattern, not in the `Node` and `Relationship` classes.
 
+=== Assign to path variable
+
+The method `assignToPath` has been removed in the following clauses:
+
+- `Match`
+- `Merge`
+- `Create`
+
+Instead, the method `assignTo` in `Patterns` must be used:
+
+Before:
+
+```js
+const pathVariable = new Cypher.Cypher.PathVariable()
+new Cypher.Match(pattern).assignToPath(pathVariable).return(pathVariable);
+```
+
+Now:
+
+```js
+const pathVariable = new Cypher.Cypher.PathVariable()
+new Cypher.Match(pattern.assignTo(pathVariable)).return(pathVariable);
+```
+
+Generates the Cypher:
+
+```cypher
+MATCH p = ()-[]-()
+RETURN p
+```
+
 
 == Node and Relationship variables
 
@@ -179,6 +210,10 @@ new Cypher.Pattern(a, { labels: ["Person", "Actor"] })
     .to(b)
 ----
 
+=== Path variables
+
+The variables used for paths `Cypher.Path` and `Cypher.NamedPath` have been removed in favor of the more accurate names: `Cypher.PathVariable` and `Cypher.NamedPathVariable`  
+
 == Renamed features
 
 The following features where deprecated in favor of a different name with the same functionality. The deprecated features have been removed in version 2.0:

docs/package.json

@@ -18,19 +18,19 @@
     "author": "Neo4j",
     "license": "ISC",
     "dependencies": {
-        "@antora/cli": "^3.1.4",
-        "@antora/site-generator-default": "^3.1.4",
-        "@neo4j-antora/antora-add-notes": "^0.3.0",
+        "@antora/cli": "^3.1.9",
+        "@antora/site-generator-default": "^3.1.9",
+        "@neo4j-antora/antora-add-notes": "^0.3.1",
         "@neo4j-antora/antora-modify-sitemaps": "^0.4.4",
         "@neo4j-antora/antora-page-roles": "^0.3.2",
         "@neo4j-antora/antora-table-footnotes": "^0.3.2",
         "@neo4j-antora/mark-terms": "1.1.0",
-        "@neo4j-documentation/macros": "^1.0.2",
+        "@neo4j-documentation/macros": "^1.0.4",
         "@neo4j-documentation/remote-include": "^1.0.0"
     },
     "devDependencies": {
-        "express": "^4.18.2",
-        "nodemon": "^3.0.0"
+        "express": "^4.21.1",
+        "nodemon": "^3.1.7"
     },
     "overrides": {
         "@antora/site-generator-default": {

src/clauses/Create.ts

@@ -22,7 +22,6 @@ import { PathAssign } from "../pattern/PathAssign";
 import { Pattern } from "../pattern/Pattern";
 import { compileCypherIfExists } from "../utils/compile-cypher-if-exists";
 import { Clause } from "./Clause";
-import { WithPathAssign } from "./mixins/WithPathAssign";
 import { WithFinish } from "./mixins/clauses/WithFinish";
 import { WithMerge } from "./mixins/clauses/WithMerge";
 import { WithReturn } from "./mixins/clauses/WithReturn";
@@ -37,7 +36,6 @@ import { mixin } from "./utils/mixin";
 export interface Create
     extends WithReturn,
         WithSet,
-        WithPathAssign,
         WithWith,
         WithDelete,
         WithRemove,
@@ -49,7 +47,7 @@ export interface Create
  * @see [Cypher Documentation](https://neo4j.com/docs/cypher-manual/current/clauses/create/)
  * @category Clauses
  */
-@mixin(WithReturn, WithSet, WithPathAssign, WithWith, WithDelete, WithRemove, WithMerge, WithFinish, WithOrder)
+@mixin(WithReturn, WithSet, WithWith, WithDelete, WithRemove, WithMerge, WithFinish, WithOrder)
 export class Create extends Clause {
     private readonly pattern: Pattern | PathAssign<Pattern>;
 
@@ -81,13 +79,6 @@ export class Create extends Clause {
 
     /** @internal */
     public getCypher(env: CypherEnvironment): string {
-        const pathCypher = this.compilePath(env);
-        if (pathCypher && this.pattern instanceof PathAssign) {
-            throw new Error(
-                "Cannot generate CREATE, using assignTo and assignToPath at the same time is not supported"
-            );
-        }
-
         const patternCypher = this.pattern.getCypher(env);
 
         const setCypher = compileCypherIfExists(this.setSubClause, env, { prefix: "\n" });
@@ -96,6 +87,6 @@ export class Create extends Clause {
         const orderByCypher = compileCypherIfExists(this.orderByStatement, env, { prefix: "\n" });
 
         const nextClause = this.compileNextClause(env);
-        return `CREATE ${pathCypher}${patternCypher}${setCypher}${removeCypher}${deleteStr}${orderByCypher}${nextClause}`;
+        return `CREATE ${patternCypher}${setCypher}${removeCypher}${deleteStr}${orderByCypher}${nextClause}`;
     }
 }

src/clauses/Match.ts

@@ -18,12 +18,11 @@
  */
 
 import type { CypherEnvironment } from "../Environment";
-import { PathAssign } from "../pattern/PathAssign";
+import type { PathAssign } from "../pattern/PathAssign";
 import type { Pattern } from "../pattern/Pattern";
 import type { QuantifiedPath } from "../pattern/quantified-patterns/QuantifiedPath";
 import { compileCypherIfExists } from "../utils/compile-cypher-if-exists";
 import { Clause } from "./Clause";
-import { WithPathAssign } from "./mixins/WithPathAssign";
 import { WithCall } from "./mixins/clauses/WithCall";
 import { WithCallProcedure } from "./mixins/clauses/WithCallProcedure";
 import { WithCreate } from "./mixins/clauses/WithCreate";
@@ -44,7 +43,6 @@ export interface Match
         WithWhere,
         WithSet,
         WithWith,
-        WithPathAssign,
         WithDelete,
         WithRemove,
         WithUnwind,
@@ -69,7 +67,6 @@ type ShortestStatement = {
     WithWhere,
     WithSet,
     WithWith,
-    WithPathAssign,
     WithDelete,
     WithRemove,
     WithUnwind,
@@ -160,11 +157,6 @@ export class Match extends Clause {
 
     /** @internal */
     public getCypher(env: CypherEnvironment): string {
-        const pathAssignStr = this.compilePath(env);
-        if (pathAssignStr && this.pattern instanceof PathAssign) {
-            throw new Error("Cannot generate MATCH, using assignTo and assignToPath at the same time is not supported");
-        }
-
         const patternCypher = this.pattern.getCypher(env);
 
         const whereCypher = compileCypherIfExists(this.whereSubClause, env, { prefix: "\n" });
@@ -177,7 +169,7 @@ export class Match extends Clause {
         const optionalMatch = this._optional ? "OPTIONAL " : "";
         const shortestStatement = this.getShortestStatement();
 
-        return `${optionalMatch}MATCH ${shortestStatement}${pathAssignStr}${patternCypher}${whereCypher}${setCypher}${removeCypher}${deleteCypher}${orderByCypher}${nextClause}`;
+        return `${optionalMatch}MATCH ${shortestStatement}${patternCypher}${whereCypher}${setCypher}${removeCypher}${deleteCypher}${orderByCypher}${nextClause}`;
     }
 
     private getShortestStatement(): string {

src/clauses/Merge.ts

@@ -19,10 +19,9 @@
 
 import type { Pattern } from "..";
 import type { CypherEnvironment } from "../Environment";
-import { PathAssign } from "../pattern/PathAssign";
+import type { PathAssign } from "../pattern/PathAssign";
 import { compileCypherIfExists } from "../utils/compile-cypher-if-exists";
 import { Clause } from "./Clause";
-import { WithPathAssign } from "./mixins/WithPathAssign";
 import { WithCreate } from "./mixins/clauses/WithCreate";
 import { WithFinish } from "./mixins/clauses/WithFinish";
 import { WithReturn } from "./mixins/clauses/WithReturn";
@@ -39,7 +38,6 @@ import { mixin } from "./utils/mixin";
 export interface Merge
     extends WithReturn,
         WithSet,
-        WithPathAssign,
         WithDelete,
         WithRemove,
         WithWith,
@@ -51,7 +49,7 @@ export interface Merge
  * @see [Cypher Documentation](https://neo4j.com/docs/cypher-manual/current/clauses/merge/)
  * @category Clauses
  */
-@mixin(WithReturn, WithSet, WithPathAssign, WithDelete, WithRemove, WithWith, WithCreate, WithFinish, WithOrder)
+@mixin(WithReturn, WithSet, WithDelete, WithRemove, WithWith, WithCreate, WithFinish, WithOrder)
 export class Merge extends Clause {
     private readonly pattern: Pattern | PathAssign<Pattern>;
     private readonly onCreateClause: OnCreate;
@@ -92,11 +90,7 @@ export class Merge extends Clause {
 
     /** @internal */
     public getCypher(env: CypherEnvironment): string {
-        const pathAssignStr = this.compilePath(env);
-        if (pathAssignStr && this.pattern instanceof PathAssign) {
-            throw new Error("Cannot generate MERGE, using assignTo and assignToPath at the same time is not supported");
-        }
-        const mergeStr = `MERGE ${pathAssignStr}${this.pattern.getCypher(env)}`;
+        const mergeStr = `MERGE ${this.pattern.getCypher(env)}`;
         const setCypher = compileCypherIfExists(this.setSubClause, env, { prefix: "\n" });
         const onCreateCypher = compileCypherIfExists(this.onCreateClause, env, { prefix: "\n" });
         const onMatchCypher = compileCypherIfExists(this.onMatchClause, env, { prefix: "\n" });

tests/clause-chaining.test.ts

@@ -37,7 +37,6 @@ describe("Clause chaining", () => {
             "optionalMatch",
             "merge",
             "create",
-            "assignToPath",
             "orderBy",
             "limit",
             "skip",
@@ -59,7 +58,6 @@ describe("Clause chaining", () => {
             "with",
             "merge",
             "create",
-            "assignToPath",
             "orderBy",
             "limit",
             "skip",
@@ -122,7 +120,6 @@ describe("Clause chaining", () => {
             "with",
             "merge",
             "create",
-            "assignToPath",
             "orderBy",
             "limit",
             "skip",