Introduce Driver.executeQuery

This method gives the user a simple interface and obvious place to start with the driver. Behind this method the full retry mechanism will be present. The results are eagerly returned and in memory. With this, we have removed the need for the user to have knowledge of transactions, routing control, streaming of results and cursor lifetimes, and any of the more complex concepts that are exposed when using the session object.

Author: bigmontz

packages/core/src/connection-provider.ts

@@ -43,6 +43,7 @@ class ConnectionProvider {
    * @property {Bookmarks} param.bookmarks - the bookmarks to send to routing discovery
    * @property {string} param.impersonatedUser - the impersonated user
    * @property {function (databaseName:string?)} param.onDatabaseNameResolved - Callback called when the database name get resolved
+   * @returns {Promise<Connection>}
    */
   acquireConnection (param?: {
     accessMode?: string

packages/core/src/driver.ts

@@ -40,7 +40,11 @@ import {
   SessionMode
 } from './types'
 import { ServerAddress } from './internal/server-address'
-import BookmarkManager from './bookmark-manager'
+import BookmarkManager, { bookmarkManager } from './bookmark-manager'
+import EagerResult, { createEagerResultFromResult } from './result-eager'
+import ManagedTransaction from './transaction-managed'
+import Result from './result'
+import { Dict } from './record'
 
 const DEFAULT_MAX_CONNECTION_LIFETIME: number = 60 * 60 * 1000 // 1 hour
 
@@ -159,7 +163,7 @@ class SessionConfig {
      * Enabling it is done by supplying an BookmarkManager implementation instance to this param.
      * A default implementation could be acquired by calling the factory function {@link bookmarkManager}.
      *
-     * **Warning**: Share the same BookmarkManager instance accross all session can have a negative impact
+     * **Warning**: Share the same BookmarkManager instance across all session can have a negative impact
      * on performance since all the queries will wait for the latest changes being propagated across the cluster.
      * For keeping consistency between a group of queries, use {@link Session} for grouping them.
      * For keeping consistency between a group of sessions, use {@link BookmarkManager} instance for groupping them.
@@ -179,7 +183,7 @@ class SessionConfig {
      *
      * // Reading Driver User will wait of the changes being propagated to the server before RUN the query
      * // So the 'Driver User' person should exist in the Result, unless deleted.
-     * const linkedSesssion2 = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})
+     * const linkedSession2 = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})
      *
      * await linkedSession1.close()
      * await linkedSession2.close()
@@ -193,6 +197,85 @@ class SessionConfig {
   }
 }
 
+type RoutingControl = 'WRITERS' | 'READERS'
+const WRITERS: RoutingControl = 'WRITERS'
+const READERS: RoutingControl = 'READERS'
+/**
+ * @typedef {'WRITERS'|'READERS'} RoutingControl
+ */
+/**
+ * Constant that represents writers routing control.
+ *
+ * @example
+ * driver.query("<QUERY>", <PARAMETERS>, { routing: neo4j.routing.WRITERS })
+ */
+const routing = {
+  WRITERS,
+  READERS
+}
+
+Object.freeze(routing)
+
+/**
+ * The query configuration
+ * @interface
+ */
+class QueryConfig<Entries extends Dict = Dict, T = EagerResult<Entries>> {
+  routing?: RoutingControl
+  database?: string
+  impersonatedUser?: string
+  bookmarkManager?: BookmarkManager
+  resultTransformer?: (result: Result) => Promise<T>
+
+  /**
+   * @constructor
+   * @private
+   */
+  private constructor () {
+    /**
+     * Define the type of cluster member the query will be routed to.
+     *
+     * @type {RoutingControl}
+     */
+    this.routing = routing.WRITERS
+
+    /**
+     * Define the transformation will be applied to the Result before return from the
+     * query method.
+     *
+     * @type {function<T>(result:Result): Promise<T>}
+     */
+    this.resultTransformer = undefined
+
+    /**
+     * The database this session will operate on.
+     *
+     * @type {string|undefined}
+     */
+    this.database = ''
+
+    /**
+     * The username which the user wants to impersonate for the duration of the query.
+     *
+     * @type {string|undefined}
+     */
+    this.impersonatedUser = undefined
+
+    /**
+     * Configure a BookmarkManager for the session to use
+     *
+     * A BookmarkManager is a piece of software responsible for keeping casual consistency between different sessions by sharing bookmarks
+     * between the them.
+     *
+     * By default, it uses the drivers non mutable driver level bookmark manager.
+     *
+     * Can be set to null to disable causal chaining.
+     * @type {BookmarkManager}
+     */
+    this.bookmarkManager = undefined
+  }
+}
+
 /**
  * A driver maintains one or more {@link Session}s with a remote
  * Neo4j instance. Through the {@link Session}s you can send queries
@@ -211,20 +294,21 @@ class Driver {
   private readonly _createConnectionProvider: CreateConnectionProvider
   private _connectionProvider: ConnectionProvider | null
   private readonly _createSession: CreateSession
+  private readonly _queryBookmarkManager: BookmarkManager
 
   /**
    * You should not be calling this directly, instead use {@link driver}.
    * @constructor
    * @protected
    * @param {Object} meta Metainformation about the driver
    * @param {Object} config
-   * @param {function(id: number, config:Object, log:Logger, hostNameResolver: ConfiguredCustomResolver): ConnectionProvider } createConnectonProvider Creates the connection provider
+   * @param {function(id: number, config:Object, log:Logger, hostNameResolver: ConfiguredCustomResolver): ConnectionProvider } createConnectionProvider Creates the connection provider
    * @param {function(args): Session } createSession Creates the a session
   */
   constructor (
     meta: MetaInfo,
     config: DriverConfig = {},
-    createConnectonProvider: CreateConnectionProvider,
+    createConnectionProvider: CreateConnectionProvider,
     createSession: CreateSession = args => new Session(args)
   ) {
     sanitizeConfig(config)
@@ -237,8 +321,9 @@ class Driver {
     this._meta = meta
     this._config = config
     this._log = log
-    this._createConnectionProvider = createConnectonProvider
+    this._createConnectionProvider = createConnectionProvider
     this._createSession = createSession
+    this._queryBookmarkManager = bookmarkManager()
 
     /**
      * Reference to the connection provider. Initialized lazily by {@link _getOrCreateConnectionProvider}.
@@ -250,6 +335,85 @@ class Driver {
     this._afterConstruction()
   }
 
+  /**
+   * The bookmark managed used by {@link Driver.executeQuery}
+   *
+   * @type {BookmarkManager}
+   * @returns {BookmarkManager}
+   */
+  get queryBookmarkManager (): BookmarkManager {
+    return this._queryBookmarkManager
+  }
+
+  /**
+   * Executes a query in a retriable context and returns a {@link EagerResult}.
+   *
+   * This method is a shortcut for a transaction function
+   *
+   * @example
+   * // Run a simple write query
+   * const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'})
+   *
+   * @example
+   * // Run a read query
+   * const { keys, records, summary } = await driver.executeQuery(
+   *                  'MATCH (p:Person{ name: $name }) RETURN p',
+   *                  { name: 'Person1'},
+   *                  { routing: neo4j.routing.READERS})
+   *
+   * @example
+   * // this lines
+   * const transformedResult = await driver.executeQuery(
+   *       "<QUERY>",
+   *       <PARAMETERS>,
+   *       QueryConfig {
+   *           routing: neo4j.routing.WRITERS,
+   *           resultTransformer: transformer,
+   *           database: "<DATABASE>",
+   *           impersonatedUser: "<USER>",
+   *           bookmarkManager: bookmarkManager
+   *       }
+   *   )
+   * // are equivalent to this ones
+   * const session = driver.session({
+   *            database: "<DATABASE>",
+   *            impersonatedUser: "<USER>",
+   *            bookmarkManager: bookmarkManager
+   * })
+   *
+   * try {
+   *    const transformedResult = await session.executeWrite(tx => {
+   *        const result = tx.run("<QUERY>", <PARAMETERS>)
+   *        return transformer(result)
+   *    })
+   * } finally {
+   *    await session.close()
+   * }
+   *
+   * @public
+   * @param {string} query - Cypher query to execute
+   * @param {Object} parameters - Map with parameters to use in query
+   * @param {QueryConfig<T>} config - The query configuration
+   * @returns {Promise<T>}
+   */
+  async executeQuery<Entries extends Dict = Dict, T = EagerResult<Entries>> (query: string, parameters?: any, config: QueryConfig<T> = {}): Promise<T> {
+    const bookmarkManager = config.bookmarkManager === null ? undefined : config.bookmarkManager ?? this.queryBookmarkManager
+    const session = this.session({ database: config.database, bookmarkManager })
+    try {
+      const execute = config.routing === routing.READERS
+        ? session.executeRead.bind(session)
+        : session.executeWrite.bind(session)
+      const transformer = config.resultTransformer ?? createEagerResultFromResult
+
+      return (await execute((tx: ManagedTransaction) => {
+        const result = tx.run(query, parameters)
+        return transformer(result)
+      })) as unknown as T
+    } finally {
+      await session.close()
+    }
+  }
+
   /**
    * Verifies connectivity of this driver by trying to open a connection with the provided driver options.
    *
@@ -418,6 +582,7 @@ class Driver {
 
   /**
    * @protected
+   * @returns {void}
    */
   _afterConstruction (): void {
     this._log.info(
@@ -589,6 +754,6 @@ function createHostNameResolver (config: any): ConfiguredCustomResolver {
   return new ConfiguredCustomResolver(config.resolver)
 }
 
-export { Driver, READ, WRITE }
-export type { SessionConfig }
+export { Driver, READ, WRITE, routing }
+export type { SessionConfig, QueryConfig, RoutingControl }
 export default Driver

packages/core/src/index.ts

@@ -67,6 +67,7 @@ import ResultSummary, {
   Stats
 } from './result-summary'
 import Result, { QueryResult, ResultObserver } from './result'
+import EagerResult from './result-eager'
 import ConnectionProvider from './connection-provider'
 import Connection from './connection'
 import Transaction from './transaction'
@@ -76,7 +77,7 @@ import Session, { TransactionConfig } from './session'
 import Driver, * as driver from './driver'
 import auth from './auth'
 import BookmarkManager, { BookmarkManagerConfig, bookmarkManager } from './bookmark-manager'
-import { SessionConfig } from './driver'
+import { SessionConfig, QueryConfig, RoutingControl, routing } from './driver'
 import * as types from './types'
 import * as json from './json'
 import * as internal from './internal' // todo: removed afterwards
@@ -139,6 +140,7 @@ const forExport = {
   QueryStatistics,
   Stats,
   Result,
+  EagerResult,
   Transaction,
   ManagedTransaction,
   TransactionPromise,
@@ -149,7 +151,8 @@ const forExport = {
   driver,
   json,
   auth,
-  bookmarkManager
+  bookmarkManager,
+  routing
 }
 
 export {
@@ -198,6 +201,7 @@ export {
   QueryStatistics,
   Stats,
   Result,
+  EagerResult,
   ConnectionProvider,
   Connection,
   Transaction,
@@ -209,7 +213,8 @@ export {
   driver,
   json,
   auth,
-  bookmarkManager
+  bookmarkManager,
+  routing
 }
 
 export type {
@@ -221,7 +226,9 @@ export type {
   TransactionConfig,
   BookmarkManager,
   BookmarkManagerConfig,
-  SessionConfig
+  SessionConfig,
+  QueryConfig,
+  RoutingControl
 }
 
 export default forExport

packages/core/src/record.ts

@@ -243,3 +243,7 @@ class Record<
 }
 
 export default Record
+
+export type {
+  Dict
+}