Skip to content

Commit 8b89175

Browse files
bigmontzbigmontz
committed
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`.
1 parent 93c0a16 commit 8b89175

File tree

13 files changed

+57
-103
lines changed

13 files changed

+57
-103
lines changed

‎packages/core/src/bookmark-manager.ts

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@
2121
* Interface for the piece of software responsible for keeping track of current active bookmarks accross the driver.
2222
* @interface
2323
* @since 5.0
24-
* @experimental
2524
*/
2625
export default class BookmarkManager {
2726
/**
@@ -66,7 +65,6 @@ export interface BookmarkManagerConfig {
6665
* @typedef {Object} BookmarkManagerConfig
6766
*
6867
* @since 5.0
69-
* @experimental
7068
* @property {Iterable<string>} [initialBookmarks] Defines the initial set of bookmarks. The key is the database name and the values are the bookmarks.
7169
* @property {function():Promise<Iterable<string>>} [bookmarksSupplier] Called for supplying extra bookmarks to the BookmarkManager
7270
* @property {function(bookmarks: Iterable<string>): Promise<void>} [bookmarksConsumer] Called when the set of bookmarks get updated
@@ -75,7 +73,6 @@ export interface BookmarkManagerConfig {
7573
* Provides an configured {@link BookmarkManager} instance.
7674
*
7775
* @since 5.0
78-
* @experimental
7976
* @param {BookmarkManagerConfig} [config={}]
8077
* @returns {BookmarkManager}
8178
*/

‎packages/core/src/driver.ts

Lines changed: 15 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -234,7 +234,6 @@ class SessionConfig {
234234
* await linkedSession2.close()
235235
* await unlinkedSession.close()
236236
*
237-
* @experimental
238237
* @type {BookmarkManager|undefined}
239238
* @since 5.0
240239
*/
@@ -306,30 +305,28 @@ class SessionConfig {
306305
}
307306
}
308307

309-
type RoutingControl = 'WRITERS' | 'READERS'
310-
const WRITERS: RoutingControl = 'WRITERS'
311-
const READERS: RoutingControl = 'READERS'
308+
type RoutingControl = 'WRITE' | 'READ'
309+
const ROUTING_WRITE: RoutingControl = 'WRITE'
310+
const ROUTING_READ: RoutingControl = 'READ'
312311
/**
313-
* @typedef {'WRITERS'|'READERS'} RoutingControl
312+
* @typedef {'WRITE'|'READ'} RoutingControl
314313
*/
315314
/**
316315
* Constants that represents routing modes.
317316
*
318317
* @example
319-
* driver.executeQuery("<QUERY>", <PARAMETERS>, { routing: neo4j.routing.WRITERS })
318+
* driver.executeQuery("<QUERY>", <PARAMETERS>, { routing: neo4j.routing.WRITE })
320319
*/
321320
const routing = {
322-
WRITERS,
323-
READERS
321+
WRITE: ROUTING_WRITE,
322+
READ: ROUTING_READ
324323
}
325324

326325
Object.freeze(routing)
327326

328327
/**
329328
* The query configuration
330329
* @interface
331-
* @experimental This can be changed or removed anytime.
332-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
333330
*/
334331
class QueryConfig<T = EagerResult> {
335332
routing?: RoutingControl
@@ -348,7 +345,7 @@ class QueryConfig<T = EagerResult> {
348345
*
349346
* @type {RoutingControl}
350347
*/
351-
this.routing = routing.WRITERS
348+
this.routing = routing.WRITE
352349

353350
/**
354351
* Define the transformation will be applied to the Result before return from the
@@ -379,7 +376,7 @@ class QueryConfig<T = EagerResult> {
379376
* A BookmarkManager is a piece of software responsible for keeping casual consistency between different pieces of work by sharing bookmarks
380377
* between the them.
381378
*
382-
* By default, it uses the driver's non mutable driver level bookmark manager. See, {@link Driver.defaultExecuteQueryBookmarkManager}
379+
* By default, it uses the driver's non mutable driver level bookmark manager. See, {@link Driver.executeQueryBookmarkManager}
383380
*
384381
* Can be set to null to disable causal chaining.
385382
* @type {BookmarkManager|null}
@@ -453,11 +450,9 @@ class Driver {
453450
/**
454451
* The bookmark managed used by {@link Driver.executeQuery}
455452
*
456-
* @experimental This can be changed or removed anytime.
457453
* @type {BookmarkManager}
458-
* @returns {BookmarkManager}
459454
*/
460-
get defaultExecuteQueryBookmarkManager (): BookmarkManager {
455+
get executeQueryBookmarkManager (): BookmarkManager {
461456
return this._defaultExecuteQueryBookmarkManager
462457
}
463458

@@ -479,7 +474,7 @@ class Driver {
479474
* const { keys, records, summary } = await driver.executeQuery(
480475
* 'MATCH (p:Person{ name: $name }) RETURN p',
481476
* { name: 'Person1'},
482-
* { routing: neo4j.routing.READERS})
477+
* { routing: neo4j.routing.READ})
483478
*
484479
* @example
485480
* // Run a read query returning a Person Nodes per elementId
@@ -507,7 +502,7 @@ class Driver {
507502
* "<QUERY>",
508503
* <PARAMETERS>,
509504
* {
510-
* routing: neo4j.routing.WRITERS,
505+
* routing: neo4j.routing.WRITE,
511506
* resultTransformer: transformer,
512507
* database: "<DATABASE>",
513508
* impersonatedUser: "<USER>",
@@ -530,21 +525,19 @@ class Driver {
530525
* }
531526
*
532527
* @public
533-
* @experimental This can be changed or removed anytime.
534528
* @param {string | {text: string, parameters?: object}} query - Cypher query to execute
535529
* @param {Object} parameters - Map with parameters to use in the query
536530
* @param {QueryConfig<T>} config - The query configuration
537531
* @returns {Promise<T>}
538532
*
539533
* @see {@link resultTransformers} for provided result transformers.
540-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
541534
*/
542535
async executeQuery<T = EagerResult> (query: Query, parameters?: any, config: QueryConfig<T> = {}): Promise<T> {
543-
const bookmarkManager = config.bookmarkManager === null ? undefined : (config.bookmarkManager ?? this.defaultExecuteQueryBookmarkManager)
536+
const bookmarkManager = config.bookmarkManager === null ? undefined : (config.bookmarkManager ?? this.executeQueryBookmarkManager)
544537
const resultTransformer = (config.resultTransformer ?? resultTransformers.eagerResultTransformer()) as ResultTransformer<T>
545-
const routingConfig: string = config.routing ?? routing.WRITERS
538+
const routingConfig: string = config.routing ?? routing.WRITE
546539

547-
if (routingConfig !== routing.READERS && routingConfig !== routing.WRITERS) {
540+
if (routingConfig !== routing.READ && routingConfig !== routing.WRITE) {
548541
throw newError(`Illegal query routing config: "${routingConfig}"`)
549542
}
550543

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ type SessionFactory = (config: { database?: string, bookmarkManager?: BookmarkMa
2828
type TransactionFunction<T> = (transactionWork: (tx: ManagedTransaction) => Promise<T>) => Promise<T>
2929

3030
interface ExecutionConfig<T> {
31-
routing: 'WRITERS' | 'READERS'
31+
routing: 'WRITE' | 'READ'
3232
database?: string
3333
impersonatedUser?: string
3434
bookmarkManager?: BookmarkManager
@@ -47,7 +47,7 @@ export default class QueryExecutor {
4747
impersonatedUser: config.impersonatedUser
4848
})
4949
try {
50-
const executeInTransaction: TransactionFunction<T> = config.routing === 'READERS'
50+
const executeInTransaction: TransactionFunction<T> = config.routing === 'READ'
5151
? session.executeRead.bind(session)
5252
: session.executeWrite.bind(session)
5353

‎packages/core/src/result-transformers.ts

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -35,17 +35,12 @@ type ResultTransformer<T> = (result: Result) => Promise<T>
3535
*
3636
* @typedef {function<T>(result:Result):Promise<T>} ResultTransformer
3737
* @interface
38-
* @experimental This can be changed or removed anytime.
3938
*
4039
* @see {@link resultTransformers} for provided implementations.
4140
* @see {@link Driver#executeQuery} for usage.
42-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
4341
*/
4442
/**
4543
* Defines the object which holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
46-
*
47-
* @experimental This can be changed or removed anytime.
48-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
4944
*/
5045
class ResultTransformers {
5146
/**
@@ -62,10 +57,7 @@ class ResultTransformers {
6257
* // is equivalent to:
6358
* const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'})
6459
*
65-
*
66-
* @experimental This can be changed or removed anytime.
6760
* @returns {ResultTransformer<EagerResult<Entries>>} The result transformer
68-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
6961
*/
7062
eagerResultTransformer<Entries extends Dict = Dict>(): ResultTransformer<EagerResult<Entries>> {
7163
return createEagerResultFromResult
@@ -126,14 +118,12 @@ class ResultTransformers {
126118
* const objects = await session.executeRead(tx => getRecordsAsObjects(tx.run('MATCH (p:Person{ age: $age }) RETURN p.name as name')))
127119
* objects.forEach(object => console.log(`${object.name} has 25`))
128120
*
129-
* @experimental This can be changed or removed anytime.
130121
* @param {object} config The result transformer configuration
131122
* @param {function(record:Record):R} [config.map=function(record) { return record }] Method called for mapping each record
132123
* @param {function(records:R[], summary:ResultSummary, keys:string[]):T} [config.collect=function(records, summary, keys) { return { records, summary, keys }}] Method called for mapping
133124
* the result data to the transformer output.
134125
* @returns {ResultTransformer<T>} The result transformer
135126
* @see {@link Driver#executeQuery}
136-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
137127
*/
138128
mappedResultTransformer <
139129
R = Record, T = { records: R[], keys: string[], summary: ResultSummary }
@@ -178,9 +168,6 @@ class ResultTransformers {
178168

179169
/**
180170
* Holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
181-
*
182-
* @experimental This can be changed or removed anytime.
183-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
184171
*/
185172
const resultTransformers = new ResultTransformers()
186173

‎packages/core/test/driver.test.ts

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -360,8 +360,8 @@ describe('Driver', () => {
360360
expect(eagerResult).toEqual(expected)
361361
expect(spiedExecute).toBeCalledWith({
362362
resultTransformer: resultTransformers.eagerResultTransformer(),
363-
bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
364-
routing: routing.WRITERS,
363+
bookmarkManager: driver?.executeQueryBookmarkManager,
364+
routing: routing.WRITE,
365365
database: undefined,
366366
impersonatedUser: undefined
367367
}, query, params)
@@ -386,8 +386,8 @@ describe('Driver', () => {
386386
expect(summary).toEqual(expected.summary)
387387
expect(spiedExecute).toBeCalledWith({
388388
resultTransformer: resultTransformers.eagerResultTransformer(),
389-
bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
390-
routing: routing.WRITERS,
389+
bookmarkManager: driver?.executeQueryBookmarkManager,
390+
routing: routing.WRITE,
391391
database: undefined,
392392
impersonatedUser: undefined
393393
}, query, params)
@@ -439,8 +439,8 @@ describe('Driver', () => {
439439

440440
it.each([
441441
['empty config', 'the query', {}, {}, extendsDefaultWith({})],
442-
['config.routing=WRITERS', 'another query $s', { s: 'str' }, { routing: routing.WRITERS }, extendsDefaultWith({ routing: routing.WRITERS })],
443-
['config.routing=READERS', 'create num $d', { d: 1 }, { routing: routing.READERS }, extendsDefaultWith({ routing: routing.READERS })],
442+
['config.routing=WRITE', 'another query $s', { s: 'str' }, { routing: routing.WRITE }, extendsDefaultWith({ routing: routing.WRITE })],
443+
['config.routing=READ', 'create num $d', { d: 1 }, { routing: routing.READ }, extendsDefaultWith({ routing: routing.READ })],
444444
['config.database="dbname"', 'q', {}, { database: 'dbname' }, extendsDefaultWith({ database: 'dbname' })],
445445
['config.impersonatedUser="the_user"', 'q', {}, { impersonatedUser: 'the_user' }, extendsDefaultWith({ impersonatedUser: 'the_user' })],
446446
['config.bookmarkManager=null', 'q', {}, { bookmarkManager: null }, extendsDefaultWith({ bookmarkManager: undefined })],
@@ -510,8 +510,8 @@ describe('Driver', () => {
510510
return () => {
511511
const defaultConfig = {
512512
resultTransformer: resultTransformers.eagerResultTransformer(),
513-
bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
514-
routing: routing.WRITERS,
513+
bookmarkManager: driver?.executeQueryBookmarkManager,
514+
routing: routing.WRITE,
515515
database: undefined,
516516
impersonatedUser: undefined
517517
}

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,20 +39,20 @@ describe('QueryExecutor', () => {
3939
const { queryExecutor, createSession } = createExecutor()
4040

4141
await queryExecutor.execute({
42-
routing: 'WRITERS',
42+
routing: 'WRITE',
4343
resultTransformer: async (result: Result) => await Promise.resolve(),
4444
...executorConfig
4545
}, 'query')
4646

4747
expect(createSession).toBeCalledWith(expectConfig)
4848
})
4949

50-
describe('when routing="READERS"', () => {
50+
describe('when routing="READ"', () => {
5151
const baseConfig: {
52-
routing: 'READERS'
52+
routing: 'READ'
5353
resultTransformer: (result: Result) => Promise<void>
5454
} = {
55-
routing: 'READERS',
55+
routing: 'READ',
5656
resultTransformer: async (result: Result) => await Promise.resolve()
5757
}
5858

@@ -174,12 +174,12 @@ describe('QueryExecutor', () => {
174174
})
175175
})
176176

177-
describe('when routing="WRITERS"', () => {
177+
describe('when routing="WRITE"', () => {
178178
const baseConfig: {
179-
routing: 'WRITERS'
179+
routing: 'WRITE'
180180
resultTransformer: (result: Result) => Promise<void>
181181
} = {
182-
routing: 'WRITERS',
182+
routing: 'WRITE',
183183
resultTransformer: async (result: Result) => await Promise.resolve()
184184
}
185185

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

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@
2121
* Interface for the piece of software responsible for keeping track of current active bookmarks accross the driver.
2222
* @interface
2323
* @since 5.0
24-
* @experimental
2524
*/
2625
export default class BookmarkManager {
2726
/**
@@ -66,7 +65,6 @@ export interface BookmarkManagerConfig {
6665
* @typedef {Object} BookmarkManagerConfig
6766
*
6867
* @since 5.0
69-
* @experimental
7068
* @property {Iterable<string>} [initialBookmarks] Defines the initial set of bookmarks. The key is the database name and the values are the bookmarks.
7169
* @property {function():Promise<Iterable<string>>} [bookmarksSupplier] Called for supplying extra bookmarks to the BookmarkManager
7270
* @property {function(bookmarks: Iterable<string>): Promise<void>} [bookmarksConsumer] Called when the set of bookmarks get updated
@@ -75,7 +73,6 @@ export interface BookmarkManagerConfig {
7573
* Provides an configured {@link BookmarkManager} instance.
7674
*
7775
* @since 5.0
78-
* @experimental
7976
* @param {BookmarkManagerConfig} [config={}]
8077
* @returns {BookmarkManager}
8178
*/

0 commit comments

Comments
 (0)