Release BookmarkManager and Driver.executeQuery (#1073)

These new APIs are ready to be released in the Javascript Driver 5.8. This change remove the experimental tags from related APIs while makes the final adjustments to the API.

`neo4j.routing.WRITERS` and `neo4j.routing.READERS` were renamed to `neo4j.routing.WRITE` and `neo4j.routing.READ`, respectively. Or, `'WRITE'`/`'READ'` in plain string.

`Driver.defaultExecuteQueryBookmarkManager` was renamed to `Driver.executeQueryBookmarkManager`.

Author: bigmontz

packages/core/src/bookmark-manager.ts

@@ -21,7 +21,6 @@
  * 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 {
   /**
@@ -66,7 +65,6 @@ export interface BookmarkManagerConfig {
  * @typedef {Object} BookmarkManagerConfig
  *
  * @since 5.0
- * @experimental
  * @property {Iterable<string>} [initialBookmarks] Defines the initial set of bookmarks. The key is the database name and the values are the bookmarks.
  * @property {function():Promise<Iterable<string>>} [bookmarksSupplier] Called for supplying extra bookmarks to the BookmarkManager
  * @property {function(bookmarks: Iterable<string>): Promise<void>} [bookmarksConsumer] Called when the set of bookmarks  get updated
@@ -75,7 +73,6 @@ export interface BookmarkManagerConfig {
  * Provides an configured {@link BookmarkManager} instance.
  *
  * @since 5.0
- * @experimental
  * @param {BookmarkManagerConfig} [config={}]
  * @returns {BookmarkManager}
  */

packages/core/src/driver.ts

@@ -253,7 +253,6 @@ class SessionConfig {
      * await linkedSession2.close()
      * await unlinkedSession.close()
      *
-     * @experimental
      * @type {BookmarkManager|undefined}
      * @since 5.0
      */
@@ -325,30 +324,28 @@ class SessionConfig {
   }
 }
 
-type RoutingControl = 'WRITERS' | 'READERS'
-const WRITERS: RoutingControl = 'WRITERS'
-const READERS: RoutingControl = 'READERS'
+type RoutingControl = 'WRITE' | 'READ'
+const ROUTING_WRITE: RoutingControl = 'WRITE'
+const ROUTING_READ: RoutingControl = 'READ'
 /**
- * @typedef {'WRITERS'|'READERS'} RoutingControl
+ * @typedef {'WRITE'|'READ'} RoutingControl
  */
 /**
  * Constants that represents routing modes.
  *
  * @example
- * driver.executeQuery("<QUERY>", <PARAMETERS>, { routing: neo4j.routing.WRITERS })
+ * driver.executeQuery("<QUERY>", <PARAMETERS>, { routing: neo4j.routing.WRITE })
  */
 const routing = {
-  WRITERS,
-  READERS
+  WRITE: ROUTING_WRITE,
+  READ: ROUTING_READ
 }
 
 Object.freeze(routing)
 
 /**
  * The query configuration
  * @interface
- * @experimental This can be changed or removed anytime.
- * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 class QueryConfig<T = EagerResult> {
   routing?: RoutingControl
@@ -367,7 +364,7 @@ class QueryConfig<T = EagerResult> {
      *
      * @type {RoutingControl}
      */
-    this.routing = routing.WRITERS
+    this.routing = routing.WRITE
 
     /**
      * Define the transformation will be applied to the Result before return from the
@@ -398,7 +395,7 @@ class QueryConfig<T = EagerResult> {
      * A BookmarkManager is a piece of software responsible for keeping casual consistency between different pieces of work by sharing bookmarks
      * between the them.
      *
-     * By default, it uses the driver's non mutable driver level bookmark manager. See, {@link Driver.defaultExecuteQueryBookmarkManager}
+     * By default, it uses the driver's non mutable driver level bookmark manager. See, {@link Driver.executeQueryBookmarkManager}
      *
      * Can be set to null to disable causal chaining.
      * @type {BookmarkManager|null}
@@ -472,11 +469,9 @@ class Driver {
   /**
    * The bookmark managed used by {@link Driver.executeQuery}
    *
-   * @experimental This can be changed or removed anytime.
    * @type {BookmarkManager}
-   * @returns {BookmarkManager}
    */
-  get defaultExecuteQueryBookmarkManager (): BookmarkManager {
+  get executeQueryBookmarkManager (): BookmarkManager {
     return this._defaultExecuteQueryBookmarkManager
   }
 
@@ -498,7 +493,7 @@ class Driver {
    * const { keys, records, summary } = await driver.executeQuery(
    *    'MATCH (p:Person{ name: $name }) RETURN p',
    *    { name: 'Person1'},
-   *    { routing: neo4j.routing.READERS})
+   *    { routing: neo4j.routing.READ})
    *
    * @example
    * // Run a read query returning a Person Nodes per elementId
@@ -526,7 +521,7 @@ class Driver {
    *    "<QUERY>",
    *    <PARAMETERS>,
    *    {
-   *       routing: neo4j.routing.WRITERS,
+   *       routing: neo4j.routing.WRITE,
    *       resultTransformer: transformer,
    *       database: "<DATABASE>",
    *       impersonatedUser: "<USER>",
@@ -549,21 +544,19 @@ class Driver {
    * }
    *
    * @public
-   * @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
    * @returns {Promise<T>}
    *
    * @see {@link resultTransformers} for provided result transformers.
-   * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
    */
   async executeQuery<T = EagerResult> (query: Query, parameters?: any, config: QueryConfig<T> = {}): Promise<T> {
-    const bookmarkManager = config.bookmarkManager === null ? undefined : (config.bookmarkManager ?? this.defaultExecuteQueryBookmarkManager)
+    const bookmarkManager = config.bookmarkManager === null ? undefined : (config.bookmarkManager ?? this.executeQueryBookmarkManager)
     const resultTransformer = (config.resultTransformer ?? resultTransformers.eagerResultTransformer()) as ResultTransformer<T>
-    const routingConfig: string = config.routing ?? routing.WRITERS
+    const routingConfig: string = config.routing ?? routing.WRITE
 
-    if (routingConfig !== routing.READERS && routingConfig !== routing.WRITERS) {
+    if (routingConfig !== routing.READ && routingConfig !== routing.WRITE) {
       throw newError(`Illegal query routing config: "${routingConfig}"`)
     }
 

packages/core/src/internal/query-executor.ts

@@ -28,7 +28,7 @@ type SessionFactory = (config: { database?: string, bookmarkManager?: BookmarkMa
 type TransactionFunction<T> = (transactionWork: (tx: ManagedTransaction) => Promise<T>) => Promise<T>
 
 interface ExecutionConfig<T> {
-  routing: 'WRITERS' | 'READERS'
+  routing: 'WRITE' | 'READ'
   database?: string
   impersonatedUser?: string
   bookmarkManager?: BookmarkManager
@@ -47,7 +47,7 @@ export default class QueryExecutor {
       impersonatedUser: config.impersonatedUser
     })
     try {
-      const executeInTransaction: TransactionFunction<T> = config.routing === 'READERS'
+      const executeInTransaction: TransactionFunction<T> = config.routing === 'READ'
         ? session.executeRead.bind(session)
         : session.executeWrite.bind(session)
 

packages/core/src/result-transformers.ts

@@ -35,17 +35,12 @@ type ResultTransformer<T> = (result: Result) => Promise<T>
  *
  * @typedef {function<T>(result:Result):Promise<T>} ResultTransformer
  * @interface
- * @experimental This can be changed or removed anytime.
  *
  * @see {@link resultTransformers} for provided implementations.
  * @see {@link Driver#executeQuery} for usage.
- * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 /**
  * Defines the object which holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
- *
- * @experimental This can be changed or removed anytime.
- * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 class ResultTransformers {
   /**
@@ -62,10 +57,7 @@ class ResultTransformers {
    * // is equivalent to:
    * const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'})
    *
-   *
-   * @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
    */
   eagerResultTransformer<Entries extends Dict = Dict>(): ResultTransformer<EagerResult<Entries>> {
     return createEagerResultFromResult
@@ -126,14 +118,12 @@ 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 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
    * the result data to the transformer output.
    * @returns {ResultTransformer<T>} The result transformer
    * @see {@link Driver#executeQuery}
-   * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
    */
   mappedResultTransformer <
     R = Record, T = { records: R[], keys: string[], summary: ResultSummary }
@@ -178,9 +168,6 @@ class ResultTransformers {
 
 /**
  * Holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
- *
- * @experimental This can be changed or removed anytime.
- * @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
  */
 const resultTransformers = new ResultTransformers()
 

packages/core/test/driver.test.ts

@@ -397,8 +397,8 @@ describe('Driver', () => {
         expect(eagerResult).toEqual(expected)
         expect(spiedExecute).toBeCalledWith({
           resultTransformer: resultTransformers.eagerResultTransformer(),
-          bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
-          routing: routing.WRITERS,
+          bookmarkManager: driver?.executeQueryBookmarkManager,
+          routing: routing.WRITE,
           database: undefined,
           impersonatedUser: undefined
         }, query, params)
@@ -423,8 +423,8 @@ describe('Driver', () => {
         expect(summary).toEqual(expected.summary)
         expect(spiedExecute).toBeCalledWith({
           resultTransformer: resultTransformers.eagerResultTransformer(),
-          bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
-          routing: routing.WRITERS,
+          bookmarkManager: driver?.executeQueryBookmarkManager,
+          routing: routing.WRITE,
           database: undefined,
           impersonatedUser: undefined
         }, query, params)
@@ -476,8 +476,8 @@ describe('Driver', () => {
 
       it.each([
         ['empty config', 'the query', {}, {}, extendsDefaultWith({})],
-        ['config.routing=WRITERS', 'another query $s', { s: 'str' }, { routing: routing.WRITERS }, extendsDefaultWith({ routing: routing.WRITERS })],
-        ['config.routing=READERS', 'create num $d', { d: 1 }, { routing: routing.READERS }, extendsDefaultWith({ routing: routing.READERS })],
+        ['config.routing=WRITE', 'another query $s', { s: 'str' }, { routing: routing.WRITE }, extendsDefaultWith({ routing: routing.WRITE })],
+        ['config.routing=READ', 'create num $d', { d: 1 }, { routing: routing.READ }, extendsDefaultWith({ routing: routing.READ })],
         ['config.database="dbname"', 'q', {}, { database: 'dbname' }, extendsDefaultWith({ database: 'dbname' })],
         ['config.impersonatedUser="the_user"', 'q', {}, { impersonatedUser: 'the_user' }, extendsDefaultWith({ impersonatedUser: 'the_user' })],
         ['config.bookmarkManager=null', 'q', {}, { bookmarkManager: null }, extendsDefaultWith({ bookmarkManager: undefined })],
@@ -547,8 +547,8 @@ describe('Driver', () => {
         return () => {
           const defaultConfig = {
             resultTransformer: resultTransformers.eagerResultTransformer(),
-            bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
-            routing: routing.WRITERS,
+            bookmarkManager: driver?.executeQueryBookmarkManager,
+            routing: routing.WRITE,
             database: undefined,
             impersonatedUser: undefined
           }

packages/core/test/internal/query-executor.test.ts

@@ -39,20 +39,20 @@ describe('QueryExecutor', () => {
     const { queryExecutor, createSession } = createExecutor()
 
     await queryExecutor.execute({
-      routing: 'WRITERS',
+      routing: 'WRITE',
       resultTransformer: async (result: Result) => await Promise.resolve(),
       ...executorConfig
     }, 'query')
 
     expect(createSession).toBeCalledWith(expectConfig)
   })
 
-  describe('when routing="READERS"', () => {
+  describe('when routing="READ"', () => {
     const baseConfig: {
-      routing: 'READERS'
+      routing: 'READ'
       resultTransformer: (result: Result) => Promise<void>
     } = {
-      routing: 'READERS',
+      routing: 'READ',
       resultTransformer: async (result: Result) => await Promise.resolve()
     }
 
@@ -174,12 +174,12 @@ describe('QueryExecutor', () => {
     })
   })
 
-  describe('when routing="WRITERS"', () => {
+  describe('when routing="WRITE"', () => {
     const baseConfig: {
-      routing: 'WRITERS'
+      routing: 'WRITE'
       resultTransformer: (result: Result) => Promise<void>
     } = {
-      routing: 'WRITERS',
+      routing: 'WRITE',
       resultTransformer: async (result: Result) => await Promise.resolve()
     }
 

packages/neo4j-driver-deno/lib/core/bookmark-manager.ts

@@ -21,7 +21,6 @@
  * 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 {
   /**
@@ -66,7 +65,6 @@ export interface BookmarkManagerConfig {
  * @typedef {Object} BookmarkManagerConfig
  *
  * @since 5.0
- * @experimental
  * @property {Iterable<string>} [initialBookmarks] Defines the initial set of bookmarks. The key is the database name and the values are the bookmarks.
  * @property {function():Promise<Iterable<string>>} [bookmarksSupplier] Called for supplying extra bookmarks to the BookmarkManager
  * @property {function(bookmarks: Iterable<string>): Promise<void>} [bookmarksConsumer] Called when the set of bookmarks  get updated
@@ -75,7 +73,6 @@ export interface BookmarkManagerConfig {
  * Provides an configured {@link BookmarkManager} instance.
  *
  * @since 5.0
- * @experimental
  * @param {BookmarkManagerConfig} [config={}]
  * @returns {BookmarkManager}
  */