Address comments in the PR

bigmontz · bigmontz · commit 76618b8eed60 · 2023-01-25T11:07:33.000+01:00
diff --git a/packages/core/src/driver.ts b/packages/core/src/driver.ts
@@ -260,7 +260,7 @@ Object.freeze(routing)
 /**
  * The query configuration
  * @interface
- * @experimental
+ * @experimental This can be changed or removed anytime.
  * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 class QueryConfig<T = EagerResult> {
@@ -385,7 +385,7 @@ class Driver {
   /**
    * The bookmark managed used by {@link Driver.executeQuery}
    *
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @type {BookmarkManager}
    * @returns {BookmarkManager}
    */
@@ -396,7 +396,9 @@ class Driver {
   /**
    * Executes a query in a retriable context and returns a {@link EagerResult}.
    *
-   * This method is a shortcut for a transaction function.
+   * This method is a shortcut for a {@link Session#executeRead} and {@link Session#executeWrite}.
+   *
+   * NOTE: `CALL {} IN TRANSACTIONS` and `USING PERIODIC COMMIT` are not supported by this method.
    *
    * @example
    * // Run a simple write query
@@ -410,22 +412,25 @@ class Driver {
    *    { routing: neo4j.routing.READERS})
    *
    * @example
-   * // Run a read query returning a Person Node
-   * const person1 = await driver.executeQuery(
+   * // Run a read query returning a Person Nodes per elementId
+   * const peopleMappedById = await driver.executeQuery(
    *    'MATCH (p:Person{ name: $name }) RETURN p',
    *    { name: 'Person1'},
    *    {
    *      resultTransformer: neo4j.resultTransformers.mappedResultTransformer({
    *        map(record) {
-   *          return record.get('p')
+   *          const p = record.get('p')
+   *          return [p.elementId, p]
    *        },
-   *        collect(personArray) {
-   *          return personArray[0]
+   *        collect(elementIdPersonPairArray) {
+   *          return new Map(elementIdPersonPairArray)
    *        }
    *      })
    *    }
    * )
    *
+   * const person = peopleMappedById.get("<ELEMENT_ID>")
+   *
    * @example
    * // these lines
    * const transformedResult = await driver.executeQuery(
@@ -455,7 +460,7 @@ class Driver {
    * }
    *
    * @public
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @param {string | {text: string, parameters?: object}} query - Cypher query to execute
    * @param {Object} parameters - Map with parameters to use in the query
    * @param {QueryConfig<T>} config - The query configuration
diff --git a/packages/core/src/result-transformers.ts b/packages/core/src/result-transformers.ts
@@ -35,7 +35,7 @@ type ResultTransformer<T> = (result: Result) => Promise<T>
  *
  * @typedef {function<T>(result:Result):Promise<T>} ResultTransformer
  * @interface
- * @experimental
+ * @experimental This can be changed or removed anytime.
  *
  * @see {@link resultTransformers} for provided implementations.
  * @see {@link Driver#executeQuery} for usage.
@@ -44,7 +44,7 @@ type ResultTransformer<T> = (result: Result) => Promise<T>
 /**
  * Defines the object which holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
  *
- * @experimental
+ * @experimental This can be changed or removed anytime.
  * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 class ResultTransformers {
@@ -63,7 +63,7 @@ class ResultTransformers {
    * const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'})
    *
    *
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @returns {ResultTransformer<EagerResult<Entries>>} The result transformer
    * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
    */
@@ -126,7 +126,7 @@ class ResultTransformers {
    * const objects = await session.executeRead(tx => getRecordsAsObjects(tx.run('MATCH (p:Person{ age: $age }) RETURN p.name as name')))
    * objects.forEach(object => console.log(`${object.name} has 25`))
    *
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @param {object} config The result transformer configuration
    * @param {function(record:Record):R} [config.map=function(record) {  return record }] Method called for mapping each record
    * @param {function(records:R[], summary:ResultSummary, keys:string[]):T} [config.collect=function(records, summary, keys) { return { records, summary, keys }}] Method called for mapping
@@ -176,7 +176,7 @@ class ResultTransformers {
 /**
  * Holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
  *
- * @experimental
+ * @experimental This can be changed or removed anytime.
  * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 const resultTransformers = new ResultTransformers()
diff --git a/packages/neo4j-driver-deno/lib/core/driver.ts b/packages/neo4j-driver-deno/lib/core/driver.ts
@@ -260,7 +260,7 @@ Object.freeze(routing)
 /**
  * The query configuration
  * @interface
- * @experimental
+ * @experimental This can be changed or removed anytime.
  * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 class QueryConfig<T = EagerResult> {
@@ -385,7 +385,7 @@ class Driver {
   /**
    * The bookmark managed used by {@link Driver.executeQuery}
    *
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @type {BookmarkManager}
    * @returns {BookmarkManager}
    */
@@ -396,7 +396,9 @@ class Driver {
   /**
    * Executes a query in a retriable context and returns a {@link EagerResult}.
    *
-   * This method is a shortcut for a transaction function.
+   * This method is a shortcut for a {@link Session#executeRead} and {@link Session#executeWrite}.
+   *
+   * NOTE: `CALL {} IN TRANSACTIONS` and `USING PERIODIC COMMIT` are not supported by this method.
    *
    * @example
    * // Run a simple write query
@@ -410,22 +412,25 @@ class Driver {
    *    { routing: neo4j.routing.READERS})
    *
    * @example
-   * // Run a read query return a Person Node
-   * const person1 = await driver.executeQuery(
+   * // Run a read query returning a Person Nodes per elementId
+   * const peopleMappedById = await driver.executeQuery(
    *    'MATCH (p:Person{ name: $name }) RETURN p',
    *    { name: 'Person1'},
    *    {
    *      resultTransformer: neo4j.resultTransformers.mappedResultTransformer({
    *        map(record) {
-   *          return record.get('p')
+   *          const p = record.get('p')
+   *          return [p.elementId, p]
    *        },
-   *        collect(personArray) {
-   *          return personArray[0]
+   *        collect(elementIdPersonPairArray) {
+   *          return new Map(elementIdPersonPairArray)
    *        }
    *      })
    *    }
    * )
    *
+   * const person = peopleMappedById.get("<ELEMENT_ID>")
+   *
    * @example
    * // these lines
    * const transformedResult = await driver.executeQuery(
@@ -455,7 +460,7 @@ class Driver {
    * }
    *
    * @public
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @param {string | {text: string, parameters?: object}} query - Cypher query to execute
    * @param {Object} parameters - Map with parameters to use in the query
    * @param {QueryConfig<T>} config - The query configuration
diff --git a/packages/neo4j-driver-deno/lib/core/result-transformers.ts b/packages/neo4j-driver-deno/lib/core/result-transformers.ts
@@ -35,7 +35,7 @@ type ResultTransformer<T> = (result: Result) => Promise<T>
  *
  * @typedef {function<T>(result:Result):Promise<T>} ResultTransformer
  * @interface
- * @experimental
+ * @experimental This can be changed or removed anytime.
  *
  * @see {@link resultTransformers} for provided implementations.
  * @see {@link Driver#executeQuery} for usage.
@@ -44,7 +44,7 @@ type ResultTransformer<T> = (result: Result) => Promise<T>
 /**
  * Defines the object which holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
  *
- * @experimental
+ * @experimental This can be changed or removed anytime.
  * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 class ResultTransformers {
@@ -59,11 +59,11 @@ class ResultTransformers {
    * const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'}, {
    *   resultTransformer: neo4j.resultTransformers.eagerResultTransformer()
    * })
-   * // equivalent to:
+   * // is equivalent to:
    * const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'})
    *
    *
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @returns {ResultTransformer<EagerResult<Entries>>} The result transformer
    * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
    */
@@ -126,7 +126,7 @@ class ResultTransformers {
    * const objects = await session.executeRead(tx => getRecordsAsObjects(tx.run('MATCH (p:Person{ age: $age }) RETURN p.name as name')))
    * objects.forEach(object => console.log(`${object.name} has 25`))
    *
-   * @experimental
+   * @experimental This can be changed or removed anytime.
    * @param {object} config The result transformer configuration
    * @param {function(record:Record):R} [config.map=function(record) {  return record }] Method called for mapping each record
    * @param {function(records:R[], summary:ResultSummary, keys:string[]):T} [config.collect=function(records, summary, keys) { return { records, summary, keys }}] Method called for mapping
@@ -176,7 +176,7 @@ class ResultTransformers {
 /**
  * Holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
  *
- * @experimental
+ * @experimental This can be changed or removed anytime.
  * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 const resultTransformers = new ResultTransformers()
