Merge pull request #588 from neo4j/remove-label-operator

angrykoala · web-flow · commit 84953238fd71 · 2025-10-15T13:00:24.000+01:00
Remove labelOperator
diff --git a/.changeset/easy-horses-repeat.md b/.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_
+
+```js
+MATCH (this1:Movie:Film)
+```
+
+_After_
+
+```cypher
+MATCH (this1:Movie&Film)
+```
diff --git a/examples/patterns/label-expressions.ts b/examples/patterns/label-expressions.ts
@@ -30,9 +30,7 @@ const matchQuery = new Cypher.Match(
     })
 ).return(movieNode);
 
-const { cypher, params } = matchQuery.build({
-    labelOperator: "&",
-});
+const { cypher, params } = matchQuery.build();
 
 console.log("Cypher");
 console.log(cypher);
diff --git a/examples/patterns/length.ts b/examples/patterns/length.ts
@@ -29,9 +29,7 @@ const pattern = new Cypher.Pattern(movie).related(actedIn, { type: "ACTED_IN", l
 
 const matchQuery = new Cypher.Match(pattern).return(movie);
 
-const { cypher, params } = matchQuery.build({
-    labelOperator: "&",
-});
+const { cypher, params } = matchQuery.build();
 
 console.log("Cypher");
 console.log(cypher);
diff --git a/examples/patterns/quantified-path-patterns.ts b/examples/patterns/quantified-path-patterns.ts
@@ -41,9 +41,7 @@ const quantifiedPath = new Cypher.QuantifiedPath(
 
 const query = new Cypher.Match(quantifiedPath).return(m2);
 
-const { cypher, params } = query.build({
-    labelOperator: "&",
-});
+const { cypher, params } = query.build();
 
 console.log("Cypher");
 console.log(cypher);
diff --git a/src/Environment.ts b/src/Environment.ts
@@ -27,13 +27,11 @@ export type EnvPrefix = {
 };
 
 export type EnvConfig = {
-    labelOperator: NonNullable<BuildConfig["labelOperator"]>;
     unsafeEscapeOptions: NonNullable<BuildConfig["unsafeEscapeOptions"]>;
     cypherVersion: BuildConfig["cypherVersion"];
 };
 
 const defaultConfig: EnvConfig = {
-    labelOperator: ":",
     unsafeEscapeOptions: {},
     cypherVersion: undefined,
 };
diff --git a/src/clauses/Clause.ts b/src/clauses/Clause.ts
@@ -30,18 +30,6 @@ const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
  * @group Clauses
  */
 export type BuildConfig = Partial<{
-    /** Defines the default operator for adding multiple labels in a Pattern. Defaults to `":"`
-     *
-     * If the target Cypher is version 5 or above, `"&"` is recommended
-     *
-     * @example
-     * `MATCH (this:Movie:Film)`
-     * `MATCH (this:Movie&Film)`
-     *
-     * @deprecated This will be removed in the following major release and the value `"&"` will be used in the generated Cypher
-     *
-     */
-    labelOperator: ":" | "&";
     /** Will prefix generated queries with the Cypher version
      * @example `CYPHER 5`
      */
@@ -85,11 +73,10 @@ export abstract class Clause extends CypherASTNode {
 
     /** Compiles a clause into Cypher and params */
     public build(config?: BuildConfig): CypherResult {
-        const { prefix, extraParams = {}, labelOperator = ":", cypherVersion, unsafeEscapeOptions = {} } = config ?? {};
+        const { prefix, extraParams = {}, cypherVersion, unsafeEscapeOptions = {} } = config ?? {};
 
         if (this.isRoot) {
             const env = this.getEnv(prefix, {
-                labelOperator,
                 cypherVersion,
                 unsafeEscapeOptions,
             });
@@ -104,7 +91,7 @@ export abstract class Clause extends CypherASTNode {
         }
         const root = this.getRoot();
         if (root instanceof Clause) {
-            return root.build({ prefix, extraParams, labelOperator, cypherVersion, unsafeEscapeOptions });
+            return root.build({ prefix, extraParams, cypherVersion, unsafeEscapeOptions });
         }
         throw new Error(`Cannot build root: ${root.constructor.name}`);
     }
diff --git a/src/expressions/HasLabel.test.ts b/src/expressions/HasLabel.test.ts
@@ -55,9 +55,9 @@ describe("HasLabel", () => {
             const queryResult = new TestClause(query).build();
 
             expect(queryResult.cypher).toMatchInlineSnapshot(`
-            "MATCH (this0:Movie)
-            WHERE this0:Movie:Film"
-        `);
+"MATCH (this0:Movie)
+WHERE this0:Movie&Film"
+`);
 
             expect(queryResult.params).toMatchInlineSnapshot(`{}`);
         });
diff --git a/src/expressions/HasLabel.ts b/src/expressions/HasLabel.ts
@@ -58,9 +58,9 @@ export class HasLabel extends CypherASTNode {
     private generateLabelExpressionStr(env: CypherEnvironment): string {
         if (Array.isArray(this.expectedLabels)) {
             const escapedLabels = this.expectedLabels.map((label) => escapeLabel(label));
-            return addLabelToken(env.config.labelOperator, ...escapedLabels);
+            return addLabelToken(...escapedLabels);
         } else {
-            return addLabelToken(env.config.labelOperator, this.expectedLabels.getCypher(env));
+            return addLabelToken(this.expectedLabels.getCypher(env));
         }
     }
 
diff --git a/src/pattern/Pattern.test.ts b/src/pattern/Pattern.test.ts
@@ -191,9 +191,7 @@ describe("Patterns", () => {
                     .to(b)
             );
             const queryResult = query.build();
-            expect(queryResult.cypher).toMatchInlineSnapshot(
-                `"(this0:Person:Actor { name: $param0, surname: $param1 })-[this1:ACTED_IN { roles: $param2 }]->(this2)"`
-            );
+            expect(queryResult.cypher).toMatchInlineSnapshot(`"(this0:Person&Actor { name: $param0, surname: $param1 })-[this1:ACTED_IN { roles: $param2 }]->(this2)"`);
 
             expect(queryResult.params).toMatchInlineSnapshot(`
                 {
@@ -225,9 +223,7 @@ describe("Patterns", () => {
                     .to(b)
             );
             const queryResult = query.build();
-            expect(queryResult.cypher).toMatchInlineSnapshot(
-                `"(this0:Person:Actor)-[this1:ACTED_IN { roles: (\\"The \\" + \\"Matrix\\") }]->(this2)"`
-            );
+            expect(queryResult.cypher).toMatchInlineSnapshot(`"(this0:Person&Actor)-[this1:ACTED_IN { roles: (\\"The \\" + \\"Matrix\\") }]->(this2)"`);
 
             expect(queryResult.params).toMatchInlineSnapshot(`{}`);
         });
diff --git a/src/pattern/labels-to-string.ts b/src/pattern/labels-to-string.ts
@@ -44,7 +44,7 @@ function labelOrTypeToString(
     escapeFunc: (s: string) => string
 ): string {
     if (elements instanceof LabelExpr) {
-        return addLabelToken(env.config.labelOperator, elements.getCypher(env));
+        return addLabelToken(elements.getCypher(env));
     } else {
         const escapedLabels = asArray(elements).map((label: string | Expr) => {
             if (typeof label === "string") {
@@ -54,6 +54,6 @@ function labelOrTypeToString(
             }
         });
 
-        return addLabelToken(env.config.labelOperator, ...escapedLabels);
+        return addLabelToken(...escapedLabels);
     }
 }
diff --git a/src/references/Label.ts b/src/references/Label.ts
@@ -58,7 +58,7 @@ export class Label extends CypherASTNode {
     }
 
     private generateLabelExpressionStr(env: CypherEnvironment): string {
-        return addLabelToken(env.config.labelOperator, escapeLabel(this.label));
+        return addLabelToken(escapeLabel(this.label));
     }
 }
 
@@ -77,7 +77,7 @@ export class DynamicLabel extends Label {
     public getCypher(env: CypherEnvironment): string {
         const nodeId = this.node.getCypher(env);
         const exprStr = `$(${this.expr.getCypher(env)})`;
-        const labelStr = addLabelToken(env.config.labelOperator, exprStr);
+        const labelStr = addLabelToken(exprStr);
         return `${nodeId}${labelStr}`;
     }
 }
diff --git a/src/utils/add-label-token.test.ts b/src/utils/add-label-token.test.ts
@@ -19,24 +19,24 @@
 
 import { addLabelToken } from "./add-label-token";
 
-describe.each([":", "&"] as const)("addLabelToken", (operator) => {
-    test("addLabelToken without labels using operator %s", () => {
-        const result = addLabelToken(operator);
+describe("addLabelToken", () => {
+    test("addLabelToken without labels", () => {
+        const result = addLabelToken();
         expect(result).toBe("");
     });
 
-    test("addLabelToken with a single label using operator %s", () => {
-        const result = addLabelToken(operator, "Movie");
+    test("addLabelToken with a single label", () => {
+        const result = addLabelToken("Movie");
         expect(result).toBe(":Movie");
     });
 
-    test("addLabelToken with two labels using operator %s", () => {
-        const result = addLabelToken(operator, "Movie", "Film");
-        expect(result).toBe(`:Movie${operator}Film`);
+    test("addLabelToken with two labels", () => {
+        const result = addLabelToken("Movie", "Film");
+        expect(result).toBe(`:Movie&Film`);
     });
 
-    test("addLabelToken with multiple labels using operator %s", () => {
-        const result = addLabelToken(operator, "Movie", "Film", "Video");
-        expect(result).toBe(`:Movie${operator}Film${operator}Video`);
+    test("addLabelToken with multiple labels", () => {
+        const result = addLabelToken("Movie", "Film", "Video");
+        expect(result).toBe(`:Movie&Film&Video`);
     });
 });
diff --git a/src/utils/add-label-token.ts b/src/utils/add-label-token.ts
@@ -18,11 +18,11 @@
  */
 
 /** Generates a string with all the labels. For example `:Movie&Film` */
-export function addLabelToken(andToken: ":" | "&", ...labels: string[]): string {
+export function addLabelToken(...labels: string[]): string {
     const firstLabel = labels.shift();
     if (!firstLabel) return "";
 
-    const extraLabels = labels.map((label) => `${andToken}${label}`).join("");
+    const extraLabels = labels.map((label) => `&${label}`).join("");
 
     return `:${firstLabel}${extraLabels}`;
 }
diff --git a/tests/build-config/label-operator.test.ts b/tests/build-config/label-operator.test.ts
diff --git a/tests/issues/479.test.ts b/tests/issues/479.test.ts
@@ -116,7 +116,7 @@ RETURN count(this1)"
 
             expect(queryResult.cypher).toMatchInlineSnapshot(`
 "WITH $param0 AS var0
-MATCH (this1:$(var0):\`normal$Label\`:$($param1))
+MATCH (this1:$(var0)&\`normal$Label\`&$($param1))
 RETURN count(this1)"
 `);
 

Original file line number	Diff line number	Diff line change
`@@ -58,9 +58,9 @@ export class HasLabel extends CypherASTNode {`
`58`	`58`	`private generateLabelExpressionStr(env: CypherEnvironment): string {`
`59`	`59`	`if (Array.isArray(this.expectedLabels)) {`
`60`	`60`	`const escapedLabels = this.expectedLabels.map((label) => escapeLabel(label));`
`61`		`- return addLabelToken(env.config.labelOperator, ...escapedLabels);`
	`61`	`+ return addLabelToken(...escapedLabels);`
`62`	`62`	`} else {`
`63`		`- return addLabelToken(env.config.labelOperator, this.expectedLabels.getCypher(env));`
	`63`	`+ return addLabelToken(this.expectedLabels.getCypher(env));`
`64`	`64`	`}`
`65`	`65`	`}`
`66`	`66`
Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,7 @@ function labelOrTypeToString(`
`44`	`44`	`escapeFunc: (s: string) => string`
`45`	`45`	`): string {`
`46`	`46`	`if (elements instanceof LabelExpr) {`
`47`		`- return addLabelToken(env.config.labelOperator, elements.getCypher(env));`
	`47`	`+ return addLabelToken(elements.getCypher(env));`
`48`	`48`	`} else {`
`49`	`49`	`const escapedLabels = asArray(elements).map((label: string \| Expr) => {`
`50`	`50`	`if (typeof label === "string") {`
`@@ -54,6 +54,6 @@ function labelOrTypeToString(`
`54`	`54`	`}`
`55`	`55`	`});`
`56`	`56`
`57`		`- return addLabelToken(env.config.labelOperator, ...escapedLabels);`
	`57`	`+ return addLabelToken(...escapedLabels);`
`58`	`58`	`}`
`59`	`59`	`}`