Release BookmarkManager and Driver.executeQuery

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 adjustements to the API.

`neo4j.routing.WRITERS` and `neo4j.routing.READERS` were renamed to `neo4j.routing.WRITER` 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

@@ -234,7 +234,6 @@ class SessionConfig {
      * await linkedSession2.close()
      * await unlinkedSession.close()
      *
-     * @experimental
      * @type {BookmarkManager|undefined}
      * @since 5.0
      */
@@ -306,30 +305,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
@@ -348,7 +345,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
@@ -379,7 +376,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}
@@ -453,11 +450,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
   }
 
@@ -479,7 +474,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
@@ -507,7 +502,7 @@ class Driver {
    *    "<QUERY>",
    *    <PARAMETERS>,
    *    {
-   *       routing: neo4j.routing.WRITERS,
+   *       routing: neo4j.routing.WRITE,
    *       resultTransformer: transformer,
    *       database: "<DATABASE>",
    *       impersonatedUser: "<USER>",
@@ -530,21 +525,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

@@ -360,8 +360,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)
@@ -386,8 +386,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)
@@ -439,8 +439,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 })],
@@ -510,8 +510,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}
  */