Skip to content

Commit 362b141

Browse files
bigmontzbigmontz
committed
Add configuration docs
1 parent 3fa1439 commit 362b141

File tree

7 files changed

+127
-19
lines changed

7 files changed

+127
-19
lines changed

‎packages/core/src/driver.ts

Lines changed: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -164,10 +164,10 @@ class SessionConfig {
164164
* Enabling it is done by supplying an BookmarkManager implementation instance to this param.
165165
* A default implementation could be acquired by calling the factory function {@link bookmarkManager}.
166166
*
167-
* **Warning**: Share the same BookmarkManager instance accross all session can have a negative impact
167+
* **Warning**: Share the same BookmarkManager instance across all session can have a negative impact
168168
* on performance since all the queries will wait for the latest changes being propagated across the cluster.
169169
* For keeping consistency between a group of queries, use {@link Session} for grouping them.
170-
* For keeping consistency between a group of sessions, use {@link BookmarkManager} instance for groupping them.
170+
* For keeping consistency between a group of sessions, use {@link BookmarkManager} instance for grouping them.
171171
*
172172
* @example
173173
* const bookmarkManager = neo4j.bookmarkManager()
@@ -184,7 +184,7 @@ class SessionConfig {
184184
*
185185
* // Reading Driver User will wait of the changes being propagated to the server before RUN the query
186186
* // So the 'Driver User' person should exist in the Result, unless deleted.
187-
* const linkedSesssion2 = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})
187+
* const linkedSession2 = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})
188188
*
189189
* await linkedSession1.close()
190190
* await linkedSession2.close()
@@ -197,8 +197,57 @@ class SessionConfig {
197197
this.bookmarkManager = undefined
198198

199199
/**
200-
* @todo docs
200+
* Configure filter for {@link Notification} objects returned in {@link ResultSummary#notifications}.
201+
*
202+
* The filters are defined by "{@link NotificationSeverityLevel}.{@link NotificationCategory}" with the
203+
* exception of the "UNKNOWN" severity and category.
204+
* "ALL" is added for possible value of category and severity filters.
205+
*
206+
* Disabling the filters is done by setting this configuration to ["NONE"].
207+
* Using the default values is done by setting this configuration to ["SERVER_DEFAULT"].
208+
*
209+
* Helper constants and methods are defined at {@link notificationFilter}.
210+
*
211+
* @example
212+
* // disabling notifications
213+
* const sessionWithoutNotifications = driver.session({ database:'neo4j', notificationFilters: neo4j.notificationFilter.disabled() })
214+
* // EQUIVALENT TO: const sessionWithoutNotifications = driver.session({ database:'neo4j', notificationFilters: ["NONE"] })
215+
*
216+
* // using default server configuration
217+
* const sessionWithSeverDefaultNotifications = driver.session({ database:'neo4j', notificationFilters: neo4j.notificationFilter.serverDefault() })
218+
* // EQUIVALENT TO: const sessionWithSeverDefaultNotifications = driver.session({ database:'neo4j', notificationFilters: ["SERVER_DEFAULT"] })
219+
* // OR SIMPLY: const sessionWithSeverDefaultNotifications = driver.session({ database:'neo4j' })
220+
*
221+
* // Enable all notifications
222+
* const sessionWithAllNotifications = driver.session({ database:'neo4j', notificationFilters: [neo4j.notificationFilter.ALL.ALL] })
223+
* // EQUIVALENT TO: const sessionWithAllNotifications = driver.session({ database:'neo4j', notificationFilters: ['ALL.ALL'] })
224+
*
225+
* // Configuring for any categories with severity "WARNING",
226+
* // or any severity with category "QUERY"
227+
* // or severity "INFORMATION" and category "PERFORMANCE".
228+
* const sessionFineConfigured = driver.session({
229+
* database: 'neo4j',
230+
* notificationFilters: [
231+
* neo4j.notificationFilter.WARNING.ALL,
232+
* neo4j.notificationFilter.ALL.QUERY,
233+
* neo4j.notificationFilter.INFORMATION.PERFORMANCE
234+
* ]
235+
* })
236+
*
237+
* // Configuring for any categories with severity "WARNING",
238+
* // or any severity with category "QUERY"
239+
* // or severity "INFORMATION" and category "PERFORMANCE".
240+
* // const sessionFineConfigured = driver.session({
241+
* // database: 'neo4j',
242+
* // notificationFilters: [
243+
* // 'WARNING.ALL',
244+
* // 'ALL.QUERY',
245+
* // 'INFORMATION.PERFORMANCE'
246+
* // ]
247+
* // })
248+
*
201249
* @type {NotificationFilter[]|undefined}
250+
* @since 5.3
202251
*/
203252
this.notificationFilters = undefined
204253
}
@@ -639,6 +688,5 @@ function validateNotificationFilters (filters: any): void {
639688
}
640689
}
641690

642-
export { Driver, READ, WRITE }
643-
export type { SessionConfig }
691+
export { Driver, READ, WRITE, SessionConfig }
644692
export default Driver

‎packages/core/src/index.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,8 @@ export {
220220
bookmarkManager,
221221
notificationCategory,
222222
notificationSeverityLevel,
223-
notificationFilter
223+
notificationFilter,
224+
SessionConfig
224225
}
225226

226227
export type {
@@ -232,7 +233,6 @@ export type {
232233
TransactionConfig,
233234
BookmarkManager,
234235
BookmarkManagerConfig,
235-
SessionConfig,
236236
NotificationCategory,
237237
NotificationSeverityLevel,
238238
NotificationFilter

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

Lines changed: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -164,10 +164,10 @@ class SessionConfig {
164164
* Enabling it is done by supplying an BookmarkManager implementation instance to this param.
165165
* A default implementation could be acquired by calling the factory function {@link bookmarkManager}.
166166
*
167-
* **Warning**: Share the same BookmarkManager instance accross all session can have a negative impact
167+
* **Warning**: Share the same BookmarkManager instance across all session can have a negative impact
168168
* on performance since all the queries will wait for the latest changes being propagated across the cluster.
169169
* For keeping consistency between a group of queries, use {@link Session} for grouping them.
170-
* For keeping consistency between a group of sessions, use {@link BookmarkManager} instance for groupping them.
170+
* For keeping consistency between a group of sessions, use {@link BookmarkManager} instance for grouping them.
171171
*
172172
* @example
173173
* const bookmarkManager = neo4j.bookmarkManager()
@@ -184,7 +184,7 @@ class SessionConfig {
184184
*
185185
* // Reading Driver User will wait of the changes being propagated to the server before RUN the query
186186
* // So the 'Driver User' person should exist in the Result, unless deleted.
187-
* const linkedSesssion2 = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})
187+
* const linkedSession2 = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})
188188
*
189189
* await linkedSession1.close()
190190
* await linkedSession2.close()
@@ -197,8 +197,57 @@ class SessionConfig {
197197
this.bookmarkManager = undefined
198198

199199
/**
200-
* @todo docs
200+
* Configure filter for {@link Notification} objects returned in {@link ResultSummary#notifications}.
201+
*
202+
* The filters are defined by "{@link NotificationSeverityLevel}.{@link NotificationCategory}" with the
203+
* exception of the "UNKNOWN" severity and category.
204+
* "ALL" is added for possible value of category and severity filters.
205+
*
206+
* Disabling the filters is done by setting this configuration to ["NONE"].
207+
* Using the default values is done by setting this configuration to ["SERVER_DEFAULT"].
208+
*
209+
* Helper constants and methods are defined at {@link notificationFilter}.
210+
*
211+
* @example
212+
* // disabling notifications
213+
* const sessionWithoutNotifications = driver.session({ database:'neo4j', notificationFilters: neo4j.notificationFilter.disabled() })
214+
* // EQUIVALENT TO: const sessionWithoutNotifications = driver.session({ database:'neo4j', notificationFilters: ["NONE"] })
215+
*
216+
* // using default server configuration
217+
* const sessionWithSeverDefaultNotifications = driver.session({ database:'neo4j', notificationFilters: neo4j.notificationFilter.serverDefault() })
218+
* // EQUIVALENT TO: const sessionWithSeverDefaultNotifications = driver.session({ database:'neo4j', notificationFilters: ["SERVER_DEFAULT"] })
219+
* // OR SIMPLY: const sessionWithSeverDefaultNotifications = driver.session({ database:'neo4j' })
220+
*
221+
* // Enable all notifications
222+
* const sessionWithAllNotifications = driver.session({ database:'neo4j', notificationFilters: [neo4j.notificationFilter.ALL.ALL] })
223+
* // EQUIVALENT TO: const sessionWithAllNotifications = driver.session({ database:'neo4j', notificationFilters: ['ALL.ALL'] })
224+
*
225+
* // Configuring for any categories with severity "WARNING",
226+
* // or any severity with category "QUERY"
227+
* // or severity "INFORMATION" and category "PERFORMANCE".
228+
* const sessionFineConfigured = driver.session({
229+
* database: 'neo4j',
230+
* notificationFilters: [
231+
* neo4j.notificationFilter.WARNING.ALL,
232+
* neo4j.notificationFilter.ALL.QUERY,
233+
* neo4j.notificationFilter.INFORMATION.PERFORMANCE
234+
* ]
235+
* })
236+
*
237+
* // Configuring for any categories with severity "WARNING",
238+
* // or any severity with category "QUERY"
239+
* // or severity "INFORMATION" and category "PERFORMANCE".
240+
* // const sessionFineConfigured = driver.session({
241+
* // database: 'neo4j',
242+
* // notificationFilters: [
243+
* // 'WARNING.ALL',
244+
* // 'ALL.QUERY',
245+
* // 'INFORMATION.PERFORMANCE'
246+
* // ]
247+
* // })
248+
*
201249
* @type {NotificationFilter[]|undefined}
250+
* @since 5.3
202251
*/
203252
this.notificationFilters = undefined
204253
}
@@ -639,6 +688,5 @@ function validateNotificationFilters (filters: any): void {
639688
}
640689
}
641690

642-
export { Driver, READ, WRITE }
643-
export type { SessionConfig }
691+
export { Driver, READ, WRITE, SessionConfig }
644692
export default Driver

‎packages/neo4j-driver-deno/lib/core/index.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,8 @@ export {
220220
bookmarkManager,
221221
notificationCategory,
222222
notificationSeverityLevel,
223-
notificationFilter
223+
notificationFilter,
224+
SessionConfig
224225
}
225226

226227
export type {
@@ -232,7 +233,6 @@ export type {
232233
TransactionConfig,
233234
BookmarkManager,
234235
BookmarkManagerConfig,
235-
SessionConfig,
236236
NotificationCategory,
237237
NotificationSeverityLevel,
238238
NotificationFilter

‎packages/neo4j-driver-deno/lib/mod.ts

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,11 @@ const {
224224
* return ['127.0.0.1:8888', 'fallback.db.com:7687'];
225225
* },
226226
*
227-
* // Optionally override the default user agent name.
227+
* // Configure filter for Notification objects returned in ResultSummary#notifications.
228+
* // See SessionConfig#notificationFilters for usage instructions.
229+
* notificationFilters: ['SERVER_DEFAULT']
230+
*
231+
* // Optionally override the default user agent name.
228232
* userAgent: USER_AGENT
229233
* }
230234
*

‎packages/neo4j-driver-lite/src/index.ts

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,11 @@ const {
223223
* return ['127.0.0.1:8888', 'fallback.db.com:7687'];
224224
* },
225225
*
226-
* // Optionally override the default user agent name.
226+
* // Configure filter for Notification objects returned in ResultSummary#notifications.
227+
* // See SessionConfig#notificationFilters for usage instructions.
228+
* notificationFilters: ['SERVER_DEFAULT']
229+
*
230+
* // Optionally override the default user agent name.
227231
* userAgent: USER_AGENT
228232
* }
229233
*

‎packages/neo4j-driver/src/index.js

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,11 @@ const {
203203
* return ['127.0.0.1:8888', 'fallback.db.com:7687'];
204204
* },
205205
*
206-
* // Optionally override the default user agent name.
206+
* // Configure filter for Notification objects returned in ResultSummary#notifications.
207+
* // See SessionConfig#notificationFilters for usage instructions.
208+
* notificationFilters: ['SERVER_DEFAULT']
209+
*
210+
* // Optionally override the default user agent name.
207211
* userAgent: USER_AGENT
208212
* }
209213
*

0 commit comments

Comments
 (0)