Merge pull request #599 from neo4j/595-list-range-operator

595 list range operator

Author: angrykoala

.changeset/mighty-bags-behave.md

@@ -0,0 +1,11 @@
+---
+"@neo4j/cypher-builder": minor
+---
+
+Add support for range operator (`[ .. ]`) in `Cypher.List`, `PropertyRef.range` and using `Cypher.listRange`:
+
+```js
+new Cypher.Variable().property("prop").range(1, -1); // var0["prop"][1..-1]
+new Cypher.List([1, 2, 3, 4]).range(1, -1); // [1, 2, 3, 4][1..-1]
+Cypher.listRange(expr, 2, -1); // expr[2..-1]
+```

docs/modules/ROOT/pages/variables-and-params/lists.adoc

@@ -34,8 +34,6 @@ RETURN [labels(node)]
 You can use instead `new Cypher.Literal(["element 1", "element 2"])` to avoid verbose code.
 ====
 
-
-
 == Index
 Use the `.index` method of a variable or `List` to create an index access:
 
@@ -64,6 +62,34 @@ Cypher.listIndex(Cypher.collect(new Cypher.Variable()), 2);
 collect(var0)[2]
 ----
 
+== Range
+Use the `.range` method of a `List` to create a list range operator:
+
+
+[source, javascript]
+----
+new Cypher.List([1,2,3]).range(2, -1)
+----
+
+[source, cypher]
+----
+[1, 2, 3][2..-1]
+----
+
+=== Range operator on arbitrary expressions
+
+To create an index on an arbitrary expression, like a function, use `Cypher.listRange`:
+
+[source, javascript]
+----
+Cypher.listRange(Cypher.collect(new Cypher.Variable()), 1, -1);
+----
+
+[source, cypher]
+----
+collect(var0)[1..-1]
+----
+
 == List comprehension
 
 link:https://neo4j.com/docs/cypher-manual/current/values-and-types/lists/#cypher-list-comprehension[List comprehension] can be created with `new Cypher.ListComprehension` and passing a variable to be used in the comprehension. 

docs/modules/ROOT/pages/variables-and-params/variables.adoc

@@ -211,7 +211,7 @@ MATCH(this0:Movie)
 RETURN this0[($param0 + $param1)]
 ----
 
-=== Index
+== Index
 
 Like properties, an index can also be accessed through the method `.index`:
 

src/Cypher.ts

@@ -83,6 +83,7 @@ export * as vector from "./namespaces/vector/vector";
 export { ListComprehension } from "./expressions/list/ListComprehension";
 export { ListExpr as List } from "./expressions/list/ListExpr";
 export { listIndex, type ListIndex } from "./expressions/list/ListIndex";
+export { listRange, type ListRange } from "./expressions/list/ListRange";
 export { PatternComprehension } from "./expressions/list/PatternComprehension";
 
 // --Map

src/expressions/list/ListExpr.test.ts

@@ -38,4 +38,13 @@ describe("List", () => {
         expect(queryResult.cypher).toMatchInlineSnapshot(`"[\\"1\\", \\"2\\", \\"3\\"][0]"`);
         expect(queryResult.params).toMatchInlineSnapshot(`{}`);
     });
+
+    test("list range", () => {
+        const cypherList = new Cypher.List([new Cypher.Literal("1"), new Cypher.Literal("2"), new Cypher.Literal("3")]);
+        const listIndex = cypherList.range(1, -1);
+        const queryResult = new TestClause(listIndex).build();
+
+        expect(queryResult.cypher).toMatchInlineSnapshot(`"[\\"1\\", \\"2\\", \\"3\\"][1..-1]"`);
+        expect(queryResult.params).toMatchInlineSnapshot(`{}`);
+    });
 });

src/expressions/list/ListExpr.ts

@@ -21,6 +21,8 @@ import type { CypherEnvironment } from "../../Environment";
 import type { CypherCompilable, Expr } from "../../types";
 import type { ListIndex } from "./ListIndex";
 import { listIndex } from "./ListIndex";
+import type { ListRange } from "./ListRange";
+import { listRange } from "./ListRange";
 
 /** Represents a List
  * @see {@link https://neo4j.com/docs/cypher-manual/current/syntax/lists/ | Cypher Documentation}
@@ -59,4 +61,9 @@ export class ListExpr implements CypherCompilable {
     public index(index: number): ListIndex {
         return listIndex(this, index);
     }
+
+    /** Adds a list range operator (`[ .. ]`) */
+    public range(from: number, to: number): ListRange {
+        return listRange(this, from, to);
+    }
 }

src/expressions/list/ListRange.test.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Cypher from "../..";
+import { TestClause } from "../../utils/TestClause";
+
+describe("ListRange", () => {
+    test("get 0 .. 2 from list", () => {
+        const list = new Cypher.List([new Cypher.Literal("1"), new Cypher.Literal("2"), new Cypher.Literal("3")]);
+        const listIndex = Cypher.listRange(list, 0, 2);
+        const queryResult = new TestClause(listIndex).build();
+
+        expect(queryResult.cypher).toMatchInlineSnapshot(`"[\\"1\\", \\"2\\", \\"3\\"][0..2]"`);
+        expect(queryResult.params).toMatchInlineSnapshot(`{}`);
+    });
+
+    test("get 2 .. -1 from list", () => {
+        const list = new Cypher.List([new Cypher.Literal("1"), new Cypher.Literal("2"), new Cypher.Literal("3")]);
+        const listIndex = Cypher.listRange(list, 2, -1);
+        const queryResult = new TestClause(listIndex).build();
+
+        expect(queryResult.cypher).toMatchInlineSnapshot(`"[\\"1\\", \\"2\\", \\"3\\"][2..-1]"`);
+        expect(queryResult.params).toMatchInlineSnapshot(`{}`);
+    });
+
+    test("get range from arbitrary expression", () => {
+        const collect = Cypher.collect(new Cypher.Variable());
+        const listIndex = Cypher.listRange(collect, 2, 3);
+        const queryResult = new TestClause(listIndex).build();
+
+        expect(queryResult.cypher).toMatchInlineSnapshot(`"collect(var0)[2..3]"`);
+        expect(queryResult.params).toMatchInlineSnapshot(`{}`);
+    });
+});

src/expressions/list/ListRange.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { CypherEnvironment } from "../../Environment";
+import type { CypherCompilable, Expr } from "../../types";
+
+/**
+ * @group Lists
+ */
+export class ListRange implements CypherCompilable {
+    private readonly value: Expr;
+    private readonly from: number;
+    private readonly to: number;
+
+    /**
+     * @internal
+     */
+    constructor(variable: Expr, from: number, to: number) {
+        this.value = variable;
+        this.from = from;
+        this.to = to;
+    }
+
+    /** @internal */
+    public getCypher(env: CypherEnvironment): string {
+        return `${this.value.getCypher(env)}[${this.from}..${this.to}]`;
+    }
+}
+
+/** Adds a list range operator (`[ .. ]`) to an expression
+ * @example
+ * ```cypher
+ * collect(var)[1..2]
+ * ```
+ */
+export function listRange(expr: Expr, from: number, to: number): ListRange {
+    return new ListRange(expr, from, to);
+}

src/references/PropertyRef.test.ts

@@ -96,6 +96,16 @@ describe("Property", () => {
         expect(queryResult.cypher).toMatchInlineSnapshot(`"var0.myProperty[5]"`);
     });
 
+    test("List range access on property", () => {
+        const variable = new Cypher.Variable();
+        const property = variable.property("myProperty").range(1, -1);
+
+        const testClause = new TestClause(property);
+
+        const queryResult = testClause.build();
+        expect(queryResult.cypher).toMatchInlineSnapshot(`"var0.myProperty[1..-1]"`);
+    });
+
     describe("Expression", () => {
         test("Serialize expression with []", () => {
             const variable = new Cypher.Variable();

src/references/PropertyRef.ts

@@ -18,7 +18,9 @@
  */
 
 import type { CypherEnvironment } from "../Environment";
-import { ListIndex } from "../expressions/list/ListIndex";
+import { listIndex, type ListIndex } from "../expressions/list/ListIndex";
+import type { ListRange } from "../expressions/list/ListRange";
+import { listRange } from "../expressions/list/ListRange";
 import type { CypherCompilable, Expr } from "../types";
 import { escapeProperty } from "../utils/escape";
 import type { Variable } from "./Variable";
@@ -48,9 +50,14 @@ export class PropertyRef implements CypherCompilable {
         return new PropertyRef(this._variable, ...this.propertyPath, prop);
     }
 
-    /* Access individual elements via the ListIndex class, using the square bracket notation */
+    /** Access individual elements in the list */
     public index(index: number): ListIndex {
-        return new ListIndex(this, index);
+        return listIndex(this, index);
+    }
+
+    /** Adds a list range operator (`[ .. ]`) */
+    public range(from: number, to: number): ListRange {
+        return listRange(this, from, to);
     }
 
     /** @internal */