Skip to content

Commit 741b746

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 c4c0f9c commit 741b746

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

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

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)