Moving configuration to the session

Author: bigmontz

packages/core/src/bookmark-manager.ts

@@ -20,9 +20,15 @@
 /**
  * Interface for the piece of software responsible for keeping track of current active bookmarks accross the driver.
  * @interface
+ * @since 5.0
+ * @experimental
  */
 export default class BookmarkManager {
-  constructor () {
+  /**
+   * @constructor
+   * @private
+   */
+  private constructor () {
     throw new Error('Not implemented')
   }
 
@@ -31,6 +37,7 @@ export default class BookmarkManager {
    *
    * This method will be called when auto-commit queries finish and when explicit transactions
    * get commited.
+   *
    * @param {string} database The database which the bookmarks belongs to
    * @param {Iterable<string>} previousBookmarks The bookmarks used when starting the transaction
    * @param {Iterable<string>} newBookmarks The new bookmarks received at the end of the transaction.
@@ -81,7 +88,10 @@ export interface BookmarkManagerConfig {
 
 /**
  * @typedef {Object} BookmarkManagerConfig
- * @property {Map<string,Iterable<string>>} [initialBookmarks] Defines the initial set of bookmarks. The key is the database name and the values are the bookmarks.
+ *
+ * @since 5.0
+ * @experimental
+ * @property {Map<string,Iterable<string>>} [initialBookmarks@experimental] Defines the initial set of bookmarks. The key is the database name and the values are the bookmarks.
  * @property {function([database]: string):Promise<Iterable<string>>} [bookmarksSupplier] Called for supplying extra bookmarks to the BookmarkManager
  * 1. supplying bookmarks from the given database when the default BookmarkManager's `.getBookmarks(database)` gets called.
  * 2. supplying all the bookmarks when the default BookmarkManager's `.getAllBookmarks()` gets called
@@ -90,6 +100,8 @@ export interface BookmarkManagerConfig {
 /**
  * Provides an configured {@link BookmarkManager} instance.
  *
+ * @since 5.0
+ * @experimental
  * @param {BookmarkManagerConfig} [config={}]
  * @returns {BookmarkManager}
  */

packages/core/src/driver.ts

@@ -96,7 +96,110 @@ interface DriverConfig {
   trust?: TrustStrategy
   fetchSize?: number
   logging?: LoggingConfig
+}
+
+/**
+ * The session configuration
+ *
+ * @interface
+ *
+ * @param {string} defaultAccessMode=WRITE - The access mode of this session, allowed values are {@link READ} and {@link WRITE}.
+ * @param {string|string[]} bookmarks - The initial reference or references to some previous
+ * transactions. Value is optional and absence indicates that that the bookmarks do not exist or are unknown.
+ * @param {number} fetchSize - The record fetch size of each batch of this session.
+ * Use {@link FETCH_ALL} to always pull all records in one batch. This will override the config value set on driver config.
+ * @param {string} database - The database this session will operate on.
+ * @param {string} impersonatedUser - The username which the user wants to impersonate for the duration of the session.
+ * @param {BookmarkManager} [bookmarkManager] = The bookmark manager
+ */
+class SessionConfig {
+  defaultAccessMode?: SessionMode
+  bookmarks?: string | string[]
+  database?: string
+  impersonatedUser?: string
+  fetchSize?: number
   bookmarkManager?: BookmarkManager
+
+  /**
+   * @constructor
+   * @private
+   */
+  constructor () {
+    /**
+     * The access mode of this session, allowed values are {@link READ} and {@link WRITE}.
+     * **Default**: {@link WRITE}
+     * @type {string}
+     */
+    this.defaultAccessMode = WRITE
+    /**
+     * The initial reference or references to some previous
+     * transactions. Value is optional and absence indicates that that the bookmarks do not exist or are unknown.
+     * @type {string|string[]|undefined}
+     */
+    this.bookmarks = []
+
+    /**
+     * 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 session.
+     *
+     * @type {string|undefined}
+     */
+    this.impersonatedUser = undefined
+
+    /**
+     * The record fetch size of each batch of this session.
+     *
+     * Use {@link FETCH_ALL} to always pull all records in one batch. This will override the config value set on driver config.
+     *
+     * @type {number|undefined}
+     */
+    this.fetchSize = 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.
+     * 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
+     * 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.
+     *
+     * @example
+     * const bookmarkManager = neo4j.bookmarkManager()
+     * const linkedSession1 = driver.session({ database:'neo4j', bookmarkManager })
+     * const linkedSession2 = driver.session({ database:'neo4j', bookmarkManager })
+     * const unlinkedSession = driver.session({ database:'neo4j' })
+     *
+     * // Creating Driver User
+     * const createUserQueryResult = await linkedSession1.run('CREATE (p:Person {name: $name})', { name: 'Driver User'})
+     *
+     * // Reading Driver User will *NOT* wait of the changes being propagated to the server before RUN the query
+     * // So the 'Driver User' person might not exist in the Result
+     * const unlinkedReadResult = await unlinkedSession.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})
+     *
+     * // 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'})
+     *
+     * await linkedSession1.close()
+     * await linkedSession2.close()
+     * await unlinkedSession.close()
+     *
+     * @experimental
+     * @type {BookmarkManager|undefined}
+     * @since 5.0
+     */
+    this.bookmarkManager = undefined
+  }
 }
 
 /**
@@ -285,15 +388,7 @@ class Driver {
    * pool and made available for others to use.
    *
    * @public
-   * @param {Object} param - The object parameter
-   * @param {string} param.defaultAccessMode=WRITE - The access mode of this session, allowed values are {@link READ} and {@link WRITE}.
-   * @param {string|string[]} param.bookmarks - The initial reference or references to some previous
-   * transactions. Value is optional and absence indicates that that the bookmarks do not exist or are unknown.
-   * @param {number} param.fetchSize - The record fetch size of each batch of this session.
-   * Use {@link FETCH_ALL} to always pull all records in one batch. This will override the config value set on driver config.
-   * @param {string} param.database - The database this session will operate on.
-   * @param {string} param.impersonatedUser - The username which the user wants to impersonate for the duration of the session.
-   * @param {boolean} param.ignoreBookmarkManager - Disable the bookmark manager usage in the session.
+   * @param {SessionConfig} param - The session configuration
    * @return {Session} new session.
    */
   session ({
@@ -302,15 +397,8 @@ class Driver {
     database = '',
     impersonatedUser,
     fetchSize,
-    ignoreBookmarkManager
-  }: {
-    defaultAccessMode?: SessionMode
-    bookmarks?: string | string[]
-    database?: string
-    impersonatedUser?: string
-    fetchSize?: number
-    ignoreBookmarkManager?: boolean
-  } = {}): Session {
+    bookmarkManager
+  }: SessionConfig = {}): Session {
     return this._newSession({
       defaultAccessMode,
       bookmarkOrBookmarks,
@@ -319,7 +407,7 @@ class Driver {
       impersonatedUser,
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       fetchSize: validateFetchSizeValue(fetchSize, this._config.fetchSize!),
-      ignoreBookmarkManager
+      bookmarkManager
     })
   }
 
@@ -356,24 +444,22 @@ class Driver {
     reactive,
     impersonatedUser,
     fetchSize,
-    ignoreBookmarkManager
+    bookmarkManager
   }: {
     defaultAccessMode: SessionMode
     bookmarkOrBookmarks?: string | string[]
     database: string
     reactive: boolean
     impersonatedUser?: string
     fetchSize: number
-    ignoreBookmarkManager?: boolean
+    bookmarkManager?: BookmarkManager
   }): Session {
     const sessionMode = Session._validateSessionMode(defaultAccessMode)
     const connectionProvider = this._getOrCreateConnectionProvider()
     const bookmarks = bookmarkOrBookmarks != null
       ? new Bookmarks(bookmarkOrBookmarks)
       : Bookmarks.empty()
-    const bookmarkManager = ignoreBookmarkManager !== true
-      ? this._config.bookmarkManager
-      : undefined
+
     return this._createSession({
       mode: sessionMode,
       database: database ?? '',
@@ -486,7 +572,7 @@ function validateFetchSizeValue (
 /**
  * @private
  */
-function extractConnectionTimeout (config: any): number|null {
+function extractConnectionTimeout (config: any): number | null {
   const configuredTimeout = parseInt(config.connectionTimeout, 10)
   if (configuredTimeout === 0) {
     // timeout explicitly configured to 0
@@ -513,5 +599,5 @@ function createHostNameResolver (config: any): ConfiguredCustomResolver {
 }
 
 export { Driver, READ, WRITE }
-
+export type { SessionConfig }
 export default Driver

packages/core/src/index.ts

@@ -76,6 +76,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 * as types from './types'
 import * as json from './json'
 import * as internal from './internal' // todo: removed afterwards
@@ -219,7 +220,8 @@ export type {
   ResultObserver,
   TransactionConfig,
   BookmarkManager,
-  BookmarkManagerConfig
+  BookmarkManagerConfig,
+  SessionConfig
 }
 
 export default forExport

packages/core/src/types.ts

@@ -17,8 +17,6 @@
  * limitations under the License.
  */
 
-import BookmarkManager from './bookmark-manager'
-
 /**
  * @private
  */
@@ -66,7 +64,6 @@ export interface Config {
   logging?: LoggingConfig
   resolver?: (address: string) => string[] | Promise<string[]>
   userAgent?: string
-  bookmarkManager?: BookmarkManager
 }
 
 /**

packages/core/test/driver.test.ts

@@ -89,12 +89,12 @@ describe('Driver', () => {
         const manager = bookmarkManager()
         const driver = new Driver(
           META_INFO,
-          { ...CONFIG, bookmarkManager: manager },
+          { ...CONFIG },
           mockCreateConnectonProvider(connectionProvider),
           createSession
         )
 
-        const session = driver.session()
+        const session = driver.session({ bookmarkManager: manager })
 
         try {
           expect(createSession).toBeCalledWith(expect.objectContaining({
@@ -107,48 +107,47 @@ describe('Driver', () => {
         }
       })
 
-      it('should create session without bookmark manager when bookmark manager is ignored', async () => {
+      it.each([
+        [[], Bookmarks.empty()],
+        ['bookmark', new Bookmarks('bookmark')],
+        [['bookmark'], new Bookmarks(['bookmark'])],
+        [['bookmark1', 'bookmark2'], new Bookmarks(['bookmark1', 'bookmark2'])]
+      ])('should create session with bookmark manager when bookmark set', async (bookmarks, expectedBookmarks) => {
         const manager = bookmarkManager()
         const driver = new Driver(
           META_INFO,
-          { ...CONFIG, bookmarkManager: manager },
+          { ...CONFIG },
           mockCreateConnectonProvider(connectionProvider),
           createSession
         )
 
-        const session = driver.session({ ignoreBookmarkManager: true })
+        const session = driver.session({ bookmarks, bookmarkManager: manager })
 
         try {
           expect(createSession).toBeCalledWith(expect.objectContaining({
-            bookmarkManager: undefined,
-            bookmarks: Bookmarks.empty()
+            bookmarkManager: manager,
+            bookmarks: expectedBookmarks
           }))
         } finally {
           await session.close()
           await driver.close()
         }
       })
 
-      it.each([
-        [[], Bookmarks.empty()],
-        ['bookmark', new Bookmarks('bookmark')],
-        [['bookmark'], new Bookmarks(['bookmark'])],
-        [['bookmark1', 'bookmark2'], new Bookmarks(['bookmark1', 'bookmark2'])]
-      ])('should create session with bookmark manager when bookmark set', async (bookmarks, expectedBookmarks) => {
-        const manager = bookmarkManager()
+      it('should create session without bookmark manager when no bookmark manager is set', async () => {
         const driver = new Driver(
           META_INFO,
-          { ...CONFIG, bookmarkManager: manager },
+          { ...CONFIG },
           mockCreateConnectonProvider(connectionProvider),
           createSession
         )
 
-        const session = driver.session({ bookmarks })
+        const session = driver.session()
 
         try {
           expect(createSession).toBeCalledWith(expect.objectContaining({
-            bookmarkManager: manager,
-            bookmarks: expectedBookmarks
+            bookmarkManager: undefined,
+            bookmarks: Bookmarks.empty()
           }))
         } finally {
           await session.close()

packages/neo4j-driver-lite/src/index.ts

@@ -72,7 +72,8 @@ import {
   auth,
   BookmarkManager,
   bookmarkManager,
-  BookmarkManagerConfig
+  BookmarkManagerConfig,
+  SessionConfig
 } from 'neo4j-driver-core'
 import {
   DirectConnectionProvider,
@@ -202,21 +203,6 @@ const {
  *         logger: (level, message) => console.log(level + ' ' + message)
  *       },
  *
- *       // Configure a BookmarkManager for the driver to use
- *       //
- *       // A BookmarkManager is a piece of software responsible for keeping casual consistency between different sessions by sharing bookmarks
- *       // between the them.
- *       // Enabling it is done by supplying an BookmarkManager implementation instance to this param.
- *       // A default implementation could be acquired by calling the factory function bookmarkManager.
- *       //
- *       // **Warning**: Enabling the BookmarkManager 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 Session for grouping them.
- *       //
- *       // Example:
- *       // const driver = neo4j.driver(url, auth, { bookmarkManager: neo4j.bookmarkManager() })
- *       bookmarkManager: undefined, // Disabled
- *
  *       // Specify a custom server address resolver function used by the routing driver to resolve the initial address used to create the driver.
  *       // Such resolution happens:
  *       //  * during the very first rediscovery when driver is created
@@ -544,6 +530,7 @@ export type {
   ResultObserver,
   NotificationPosition,
   BookmarkManager,
-  BookmarkManagerConfig
+  BookmarkManagerConfig,
+  SessionConfig
 }
 export default forExport