Skip to content

Commit f212ff1

Browse files
bigmontzbigmontz
authored
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`.
1 parent c4c0f9c commit f212ff1

File tree

13 files changed

+57
-103
lines changed

13 files changed

+57
-103
lines changed

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

-3
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

+15-22
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,6 @@ class SessionConfig {
253253
* await linkedSession2.close()
254254
* await unlinkedSession.close()
255255
*
256-
* @experimental
257256
* @type {BookmarkManager|undefined}
258257
* @since 5.0
259258
*/
@@ -325,30 +324,28 @@ class SessionConfig {
325324
}
326325
}
327326

328-
type RoutingControl = 'WRITERS' | 'READERS'
329-
const WRITERS: RoutingControl = 'WRITERS'
330-
const READERS: RoutingControl = 'READERS'
327+
type RoutingControl = 'WRITE' | 'READ'
328+
const ROUTING_WRITE: RoutingControl = 'WRITE'
329+
const ROUTING_READ: RoutingControl = 'READ'
331330
/**
332-
* @typedef {'WRITERS'|'READERS'} RoutingControl
331+
* @typedef {'WRITE'|'READ'} RoutingControl
333332
*/
334333
/**
335334
* Constants that represents routing modes.
336335
*
337336
* @example
338-
* driver.executeQuery("<QUERY>", <PARAMETERS>, { routing: neo4j.routing.WRITERS })
337+
* driver.executeQuery("<QUERY>", <PARAMETERS>, { routing: neo4j.routing.WRITE })
339338
*/
340339
const routing = {
341-
WRITERS,
342-
READERS
340+
WRITE: ROUTING_WRITE,
341+
READ: ROUTING_READ
343342
}
344343

345344
Object.freeze(routing)
346345

347346
/**
348347
* The query configuration
349348
* @interface
350-
* @experimental This can be changed or removed anytime.
351-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
352349
*/
353350
class QueryConfig<T = EagerResult> {
354351
routing?: RoutingControl
@@ -367,7 +364,7 @@ class QueryConfig<T = EagerResult> {
367364
*
368365
* @type {RoutingControl}
369366
*/
370-
this.routing = routing.WRITERS
367+
this.routing = routing.WRITE
371368

372369
/**
373370
* Define the transformation will be applied to the Result before return from the
@@ -398,7 +395,7 @@ class QueryConfig<T = EagerResult> {
398395
* A BookmarkManager is a piece of software responsible for keeping casual consistency between different pieces of work by sharing bookmarks
399396
* between the them.
400397
*
401-
* By default, it uses the driver's non mutable driver level bookmark manager. See, {@link Driver.defaultExecuteQueryBookmarkManager}
398+
* By default, it uses the driver's non mutable driver level bookmark manager. See, {@link Driver.executeQueryBookmarkManager}
402399
*
403400
* Can be set to null to disable causal chaining.
404401
* @type {BookmarkManager|null}
@@ -472,11 +469,9 @@ class Driver {
472469
/**
473470
* The bookmark managed used by {@link Driver.executeQuery}
474471
*
475-
* @experimental This can be changed or removed anytime.
476472
* @type {BookmarkManager}
477-
* @returns {BookmarkManager}
478473
*/
479-
get defaultExecuteQueryBookmarkManager (): BookmarkManager {
474+
get executeQueryBookmarkManager (): BookmarkManager {
480475
return this._defaultExecuteQueryBookmarkManager
481476
}
482477

@@ -498,7 +493,7 @@ class Driver {
498493
* const { keys, records, summary } = await driver.executeQuery(
499494
* 'MATCH (p:Person{ name: $name }) RETURN p',
500495
* { name: 'Person1'},
501-
* { routing: neo4j.routing.READERS})
496+
* { routing: neo4j.routing.READ})
502497
*
503498
* @example
504499
* // Run a read query returning a Person Nodes per elementId
@@ -526,7 +521,7 @@ class Driver {
526521
* "<QUERY>",
527522
* <PARAMETERS>,
528523
* {
529-
* routing: neo4j.routing.WRITERS,
524+
* routing: neo4j.routing.WRITE,
530525
* resultTransformer: transformer,
531526
* database: "<DATABASE>",
532527
* impersonatedUser: "<USER>",
@@ -549,21 +544,19 @@ class Driver {
549544
* }
550545
*
551546
* @public
552-
* @experimental This can be changed or removed anytime.
553547
* @param {string | {text: string, parameters?: object}} query - Cypher query to execute
554548
* @param {Object} parameters - Map with parameters to use in the query
555549
* @param {QueryConfig<T>} config - The query configuration
556550
* @returns {Promise<T>}
557551
*
558552
* @see {@link resultTransformers} for provided result transformers.
559-
* @see https://github.com/neo4j/neo4j-javascript-driver/discussions/1052
560553
*/
561554
async executeQuery<T = EagerResult> (query: Query, parameters?: any, config: QueryConfig<T> = {}): Promise<T> {
562-
const bookmarkManager = config.bookmarkManager === null ? undefined : (config.bookmarkManager ?? this.defaultExecuteQueryBookmarkManager)
555+
const bookmarkManager = config.bookmarkManager === null ? undefined : (config.bookmarkManager ?? this.executeQueryBookmarkManager)
563556
const resultTransformer = (config.resultTransformer ?? resultTransformers.eagerResultTransformer()) as ResultTransformer<T>
564-
const routingConfig: string = config.routing ?? routing.WRITERS
557+
const routingConfig: string = config.routing ?? routing.WRITE
565558

566-
if (routingConfig !== routing.READERS && routingConfig !== routing.WRITERS) {
559+
if (routingConfig !== routing.READ && routingConfig !== routing.WRITE) {
567560
throw newError(`Illegal query routing config: "${routingConfig}"`)
568561
}
569562

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

+2-2
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

-13
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

+8-8
Original file line numberDiff line numberDiff line change
@@ -397,8 +397,8 @@ describe('Driver', () => {
397397
expect(eagerResult).toEqual(expected)
398398
expect(spiedExecute).toBeCalledWith({
399399
resultTransformer: resultTransformers.eagerResultTransformer(),
400-
bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
401-
routing: routing.WRITERS,
400+
bookmarkManager: driver?.executeQueryBookmarkManager,
401+
routing: routing.WRITE,
402402
database: undefined,
403403
impersonatedUser: undefined
404404
}, query, params)
@@ -423,8 +423,8 @@ describe('Driver', () => {
423423
expect(summary).toEqual(expected.summary)
424424
expect(spiedExecute).toBeCalledWith({
425425
resultTransformer: resultTransformers.eagerResultTransformer(),
426-
bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
427-
routing: routing.WRITERS,
426+
bookmarkManager: driver?.executeQueryBookmarkManager,
427+
routing: routing.WRITE,
428428
database: undefined,
429429
impersonatedUser: undefined
430430
}, query, params)
@@ -476,8 +476,8 @@ describe('Driver', () => {
476476

477477
it.each([
478478
['empty config', 'the query', {}, {}, extendsDefaultWith({})],
479-
['config.routing=WRITERS', 'another query $s', { s: 'str' }, { routing: routing.WRITERS }, extendsDefaultWith({ routing: routing.WRITERS })],
480-
['config.routing=READERS', 'create num $d', { d: 1 }, { routing: routing.READERS }, extendsDefaultWith({ routing: routing.READERS })],
479+
['config.routing=WRITE', 'another query $s', { s: 'str' }, { routing: routing.WRITE }, extendsDefaultWith({ routing: routing.WRITE })],
480+
['config.routing=READ', 'create num $d', { d: 1 }, { routing: routing.READ }, extendsDefaultWith({ routing: routing.READ })],
481481
['config.database="dbname"', 'q', {}, { database: 'dbname' }, extendsDefaultWith({ database: 'dbname' })],
482482
['config.impersonatedUser="the_user"', 'q', {}, { impersonatedUser: 'the_user' }, extendsDefaultWith({ impersonatedUser: 'the_user' })],
483483
['config.bookmarkManager=null', 'q', {}, { bookmarkManager: null }, extendsDefaultWith({ bookmarkManager: undefined })],
@@ -547,8 +547,8 @@ describe('Driver', () => {
547547
return () => {
548548
const defaultConfig = {
549549
resultTransformer: resultTransformers.eagerResultTransformer(),
550-
bookmarkManager: driver?.defaultExecuteQueryBookmarkManager,
551-
routing: routing.WRITERS,
550+
bookmarkManager: driver?.executeQueryBookmarkManager,
551+
routing: routing.WRITE,
552552
database: undefined,
553553
impersonatedUser: undefined
554554
}

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

+7-7
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

-3
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)