Merge remote-tracking branch 'origin/main' into call-docs

Author: angrykoala

.changeset/crazy-signs-kick.md

@@ -0,0 +1,5 @@
+---
+"@neo4j/cypher-builder": patch
+---
+
+Deprecates `Call.importWith` in favor of scope variables in `Call` constructor

.changeset/lazy-buckets-peel.md

@@ -0,0 +1,21 @@
+---
+"@neo4j/cypher-builder": patch
+---
+
+Deprecate apoc functions and procedures. These will no longer be supported in version 3 of Cypher Builder:
+
+- `apoc.date.convertFormat`
+- `apoc.util.validate`
+- `apoc.util.validatePredicate`
+- `apoc.cypher.runFirstColumnMany`
+- `apoc.cypher.runFirstColumnSingle`
+
+These can still be used by using the `Function` class directly:
+
+```js
+const convertFormat = new Cypher.Function("apoc.date.convertFormat", [
+    new Cypher.Variable(),
+    new Cypher.Literal("iso_zoned_date_time"),
+    new Cypher.Literal("iso_offset_date_time"),
+]);
+```

docs/modules/ROOT/pages/functions.adoc

@@ -26,18 +26,18 @@ This differentiates functions from clauses and other elements of the Cypher Buil
 ====
 
 Exposed functions have the closest possible name to their Cypher counterpart, and reside in the same namespace.
-For example, this query:
+For example:
 
 [source, javascript]
 ----
-Cypher.apoc.cypher.runFirstColumnSingle()
+Cypher.db.nameFromElementId("1234")
 ----
 
-Is equivalent to the Cypher function:
+Generates the Cypher function:
 
 [source, cypher]
 ----
-apoc.cypher.runFirstColumnSingle()
+db.nameFromElementId("1234")
 ----
 
 == Custom functions
@@ -46,7 +46,7 @@ In some cases, you may need to use functions that are not available in Cypher Bu
 For instance, if you are using plugins or some of the newest features of Neo4j.
 
 For these cases, you can use the class `Function` to create custom functions. 
-This example calls link:https://neo4j.com/docs/cypher-manual/current/functions/mathematical-numeric/#functions-isnan[`isNan`] as a custom function:
+This example calls an arbitrary function `myFunction`:
 
 [source, javascript]
 ----

docs/modules/ROOT/pages/subqueries/call.adoc

@@ -87,6 +87,7 @@ CALL (*) {
 }
 ----
 
+[role=label--deprecated]
 == `.importWith`
 
 [WARNING]
@@ -96,7 +97,7 @@ This method is deprecated in favor of <<_variable_scope>>.
 
 [WARNING]
 ====
-ImportWith cannot be used if scope variables are defined and will throw an error.
+`ImportWith` cannot be used if scope variables are defined and will throw an error.
 ====
 
 

src/clauses/Call.ts

@@ -60,7 +60,9 @@ export type CallInTransactionOptions = {
     retry?: number | boolean;
 };
 
-/**
+/** Adds a `CALL` subquery
+ * @param subquery - A clause to be wrapped in a `CALL` clause
+ * @param variableScope - A list of variables to pass to the scope of the clause: `CALL (var0) {`
  * @see {@link https://neo4j.com/docs/cypher-manual/current/clauses/call-subquery/ | Cypher Documentation}
  * @group Subqueries
  */
@@ -81,7 +83,8 @@ export class Call extends Clause {
     }
 
     /** Adds a `WITH` statement inside `CALL {`, this `WITH` can is used to import variables outside of the subquery
-     *  @see {@link https://neo4j.com/docs/cypher-manual/current/subqueries/call-subquery/#call-importing-variables | Cypher Documentation}
+     * @see {@link https://neo4j.com/docs/cypher-manual/current/subqueries/call-subquery/#call-importing-variables | Cypher Documentation}
+     * @deprecated Use constructor parameter `variableScope` instead
      */
     public importWith(...params: Array<Variable | "*">): this {
         if (this._importWith) {

src/namespaces/apoc/cypher/run-first-column.ts

@@ -26,6 +26,7 @@ import type { Expr } from "../../../types";
 
 /**
  * @group Functions
+ * @deprecated apoc methods will no longer be supported in Cypher Builder version 3
  * @see [Apoc Documentation](https://neo4j.com/docs/apoc/current/overview/apoc.cypher/apoc.cypher.runFirstColumnMany/)
  */
 export function runFirstColumnMany(
@@ -37,6 +38,7 @@ export function runFirstColumnMany(
 
 /**
  * @group Functions
+ * @deprecated apoc methods will no longer be supported in Cypher Builder version 3
  * @see [Apoc Documentation](https://neo4j.com/docs/apoc/current/overview/apoc.cypher/apoc.cypher.runFirstColumnSingle/)
  */
 export function runFirstColumnSingle(

src/namespaces/apoc/date.ts

@@ -25,6 +25,7 @@ import type { Expr } from "../../types";
 /**
  * @group Functions
  * @see [Apoc Documentation](https://neo4j.com/docs/apoc/current/overview/apoc.date/apoc.date.convertFormat/)
+ * @deprecated apoc methods will no longer be supported in Cypher Builder version 3
  * @example
  * ```ts
  * Cypher.apoc.date.convertFormat(

src/namespaces/apoc/util.ts

@@ -27,6 +27,7 @@ import { normalizeVariable } from "../../utils/normalize-variable";
 
 /**
  * @group Procedures
+ * @deprecated apoc methods will no longer be supported in Cypher Builder version 3
  * @see [Apoc Documentation](https://neo4j.com/docs/apoc/current/overview/apoc.util/apoc.util.validate/)
  */
 export function validate(
@@ -40,6 +41,7 @@ export function validate(
 
 /**
  * @group Functions
+ * @deprecated apoc methods will no longer be supported in Cypher Builder version 3
  * @see [Apoc Documentation](https://neo4j.com/docs/apoc/current/overview/apoc.util/apoc.util.validatePredicate/)
  */
 export function validatePredicate(predicate: Predicate, message: string): CypherFunction {